Scopes

[Toink]

Scopes

This tutorial will explain how to use scopes. Previous JASS Knowledge is required. Requires vJass.

What is a scope?

A scope is similar to a library, but it does not get moved to the top of the map's script. Think of a library as a section of code, something like a folder which contains functions. Instead of having them in the custom script section, you can make libraries instead, put all of your desired functions there and organize it along with other libraries. If for instance your library requires some functions outside the library, you can use the line requires <library name>
By using that line, libraries that are required will be put "ontop" or before it in the map's header.

For example:

JASS:

library MyLibrary requires CSCache, CSSafety
....
....
endlibrary

library CSCache initializer InitCSCache //This is the function that starts up on map init
....
....
endlibrary

Since your library requires CSCache and CSSafety, the order of the libraries will be:

JASS:

CSCache
CSSafety
MyLibrary

A library however, is moved to the top of the map's script. In short, it's like it is moved to the custom script section, but in an order(remember the requires blah blah thing?)

Scopes, are not moved. They are still a section of code which can contain private globals, private functions and other public/private members. If you want to use the private members and private globals but don't want it to be moved to the top of the map's custom script, use scopes.

Explain it to me please.

How do you declare scopes you say? Simple. Just do this :

JASS:

scope YourScope'sName
endscope

What can be done inside a scope?

You can declare globals, private globals, functions, private functions and public functions. You can also declare structs and methods. Here's an example.

JASS:

scope WTF
    globals
        private unit u
        private integer lvl
     endglobals

    private function PrivateFunc takes nothing returns nothing
        call BJDebugMsg("Hi")
    endfunction

    public function PublicFunc takes nothing returns nothing
        call PrivateFunc()
        call BJDebugMsg("Hello")
    endfunction

endscope

What are private members and public members?

Privates are members of it's class. Privates can only be used inside the scope they are in. Privates can also have the same name as other functions/global vars without giving an error. For example :

JASS:

scope wtfart

    globals
        private unit u // This global can only be used inside the scope wtfart.
    endglobals
   
    function Func takes nothing returns nothing
         set u = GetTriggerUnit() // This function is inside the scope so it can freely use that private
         call KillUnit(u)
    endfunction

endscope

globals
    unit u // Notice that we are using the name u again.
endglobals

function OtherFunc takes nothing returns nothing
    set u = GetTriggerUnit()
    call KillUnit(u)
endfunction

Publics are the opposite of privates. They act just like privates except that they can be used by functions outside the scope. For example :

JASS:

scope wtfart
    
    private function PrivFunc takes nothing returns string
        return "Hi"
    endfunction

    public function PubFunc takes nothing returns nothing
        call BJDebugMsg(PrivFunc()) // Gets the value returned by the private
    endfunction

endscope

function Func takes nothing returns nothing
    call wtfart_PubFunc() //You have to use the name of the scope it is in as a prefix and add a _
    call PubFunc() // This will not work
    call ExecuteFunc("wtfart_PubFunc")// You still need the prefix
endfunction

Nested Scopes

A nested scope is a scope inside a parent scope, this scope is considered a child scope. Child scopes cannot declare members that were previously declared as private or global by a parent scope.

Child scopes are always public members, meaning you can access a child scope's public members from outside the parent scope. But you must add a prefix for the parend and the child scope. Below is an example :

JASS:

library ParentScope //Notice I used a library, you can nest a scope inside a library but you can't nest a library in a library/scope
    scope ChildScopeA
        globals
            private integer Rawr
        endglobals

        public function WTF takes nothing returns nothing
            call BJDebugMsg(I2S(Rawr))
        endfunction
    endscope

    scope ChildScopeB
        globals
            public integer I
        endglobals

        public function WTF takes nothing returns nothing
            call BJDebugMsg(I2S(I))
        endfunction
    endscope

As I've said, child scopes cannot declare public/private members that are already declared by the parent scope. For example :

JASS:

library LibraryA
    globals
        unit BibleDude
    endglobals

    scope ChildScope
        globals
            unit BibleDude // This will cause an error, you have redeclared the variable BibleDude
        endglobals
    endscope
endlibrary

There are also two constants you can use inside scopes. They are SCOPE_PREFIX and SCOPE_PRIVATE.

SCOPE_PREFIX returns the prefix of the scope concatenated with a '_' (underscore). It is the prefix you use to call public functions.

SCOPE_PRIVATE returns the name of the current prefix for private members.

JASS:

scope WTF

    private function Blarg takes nothing returns nothing
        call BJDebugMsg("...")
    endfunction

    function lala takes nothing returns nothing
         call ExecuteFunc(SCOPE_PRIVATE+"Blarg") //You need to call private functions with their prefixes, in this case the SCOPE_PRIVATE constant will return the prefix "WTF_"
    endfunction

endscope

[Whitehorn]

'It's like a Library' really doesn't explain what a Scope is. Anyone that knows what a scope is will find this useless. Those that don't will likely find it equally useless.

[Toink]

Have you read everything else?

[Whitehorn]

Tune in for more as I add in more detailed explanations.

Waiting on it.

<insert average non-sense here>

Is this really appropriate?

[PitzerMike]

You should probably rewrite that sentece about what a scope is.
A scope in the context of vJass is much like a namespace, simply to avoid naming conflicts between systems.

I'm also awaiting the promised additions :)

[Taur]

and you should probably say that it requires VJASS

[Mapz_Maker]

and that this does NOT require previous Jass knowledge, this requires previoud vJass knowledge. Those are two totally different languages, and as of i can you Jass effectively and this tutorial breaks all the rules of jass, i realize this is not jass, this is vJass. I stopped Jassing about 1/29/07 so, i have not used vJass. And with one exception everything in vJass is for lazy jassers because I can do everything except globals endglobals somehow or another in Jass, and i get to organize the code the way i want to organize, rather than letting a program do that. (sorry vexorian and all others who use vJass but it is the truth, more unique solutions are devised when you don't have structs, unions and so on. This is not meant to be offensive this is expressing a perspective)

[Vexorian]

There is nothing offensive about the NIH syndrome, it is actually understandable. Lame but understandable.

I am not sure though, how you are going to organize things correctly in Jass, manually? That's something that doesn't seem possible unless you like to add prefixes to code, but even there, private is something you can't get.

--
Edit: I must say, that of all vJASS features, scopes and libraries are the only ones I couldn't live without. The trigger editor is terrible at letting you organize code, and doing so manually is a symptom of masochism, and at the end you don't really organize anything at all.

Seriously, I could simply do things manually for everything else, including structs, I would take 120% more of the time typing that and my code would look ugly with all the array notation for an abstraction that is not an array, but it is possible to live without structs... Scopes on the other hand are crazy-useful . I don't think I would have finished the only map I ever made if it wasn't for them.

Not saying that everybody should use them, if you don't want to use other people's stuff, then make your own preprocessor for organizing code! It is VERY easy (definitely easier than doing the organization yourself) and it won't hurt your ego, + you will keep your sanity.

[Mapz_Maker]

lol, organize in the 'header' for the map, not the triggers. the triggers to be independent of each other but then have a 'library' at the top of the map. and btw, what is NIH stand for and how would you write a preprocessor? [and everything can be done in jass because it is! i have used an mpq editor to examine the work of vJass and it is... interesting.]

edit: and what does public/private matter when one can just go change a single word?

Summary! organize in header. triggers independent. what does public/private matter when one can just go change a single word? what does NIH stand for? how do you write a preprocessor for WE? this summary is pointless!

[Av3n]

Mapz maker. If you check the credits of JASSHelper document(HTML) You''ll see how he converted all of those keywords...

-Av3n

[Toink]

Sorry for the long delay in the update. I completely forgot about this, :(

But anywho, I added info on nested scopes. Yay :p

@Mapzmaker:

And yes, it does need previous Jass knowledge. You can't code vJass if you don't know Jass, since vJass is exactly the same as Jass, except with some additions like structs and such.

vJass is quite better than Jass. In fact, it is also JASS, it's just translated to make it work and can ease your coding. If you don't like vJass, stick to good 'ol Jass, I wouldn't mind.

[PitzerMike]

*approved*

[emjlr3]

can scope use initializers as libraries can?

[moyack]

Originally Posted by emjlr3

can scope use initializers as libraries can?

I'm afraid its not possible.