sai-language/docs/11.Variables.md

An object-oriented language designed to afford code comprehension and maintenance. Transpiles in-place to Javascript.

# Variables, Scoping and Magic

Information about variables!

## Scope Prefixes

There are four explicit scope prefixes, plus bareword (unscoped) variables. 

 - `foo` bareword - object method scope
 - `@foo` "this" object attribute
 - `$foo` named task parameter
 - `~foo` system global 
 - `.foo` iterator / context-sensitive  
 
### `foo` - No prefix (bareword)

Variables with no symbolic prefix are "bareword" variables.

#### Bareword method variables
 
Almost all bareword variables belong to an object method (e.g. a task, process, promise or dynamic attribute). 

    object Example1

    Exercise1 task
      set foo 1    // set a method variable
      local bar 2  // set a local variable 

You don't need to separately declare variables, but their value is `undefined` until you `set` them. 

    Exercise2 task
      debug foo         // prints 'undefined'
      set foo 'Hello!'
      debug foo         // prints 'Hello!'

Variables that are never `set` do not exist.

    Exercise3 task
      debug foo         // this throws an error, foo does not exist in this method

Bareword variables you create with `set` are scoped to the object method.

    object Example2

    Exercise1 task 
      set greeting 'Hi!'
      debug greeting      // prints 'Hi!'
      @Oops               // Invokes @Oops task on current object

    Oops task
      debug greeting      // this is an error, because greeting does not exist in Bar.
      
Bareword variables you `set` in work functions are still scoped to the outer object method.

    object Test
    
    Narf task
      set Pinky task      // define local function Pinky
        set clothing 'rubber pants'
      Pinky               // invoke function
      debug clothing      // prints "rubber pants" because clothing is scoped to the Narf method
      
#### Bareword local variables
      
Bareword variables created with `local` are tightly scoped to the code block they are created in.  Locals are very useful when creating recursive functions.

    Factorial task given n
      local product n
      if n > 1
        set product * Factorial(n-1)
      return product 

If a local variable has the same name as a method-scoped or file-scoped variable, it will _mask_ that variable's value until the local goes out of scope, after which time the previous value will be visible again.

    Confusing task
      set card 'Queen'      // set a method variable.
      if card is 'Queen'
        local card 'Joker'  // local variable declared and set
        debug card          // prints 'Joker'
      debug card            // prints 'Queen' because the local 'card' variable is now out of scope

#### Bareword reference variables
      
Bareword variables can also be created with `reference` at the top of a source file, outside the scope of an object definition. These _reference variables_ are scoped to the file. They have no scoping prefix and are intended to be constants; they are read-only.

    reference:
      fs from require 'fs'
      LOGFILE '/var/log/sheep'
      
    object Example3
    
    Instantiate task
      set log from fs.readFileSync LOGFILE, 'utf-8'
        
In the above example, the following line would result in a compile error:        

      set LOGFILE '/var/log/sheep2'  // you cannot set a reference variable

#### Bareword instance variables

Object instance variables declared with `instance:` can also be used as barewords. When used in this way, they refere to the instance that is currently executing, e.g. 

    object Beans
    instance: name 'unset', count 0
    Instantiate task given name_
      set name to name_
    PrintCount task
      debug 'You have ${count} ${name} beans.'

This last line is identical to:

      debug 'You have ${@count} ${@name} beans.'

It's just cleaner and clearer. To refer to another object's instance variables, use the `.` accessor as, e.g. `navybeans.count`

You are not allowed to use instance variable names as the names of parameters, renamed pronouns or local variables; the compiler suspects that if you try this that you've forgotten what your instance variables are and won't let you. That's why the `Instantiate` example above uses `aname` as a parameter value, because the following is an error:

    Instantiate task given name  // generates error, collision between parameter name and instance variable


#### Bareword pronoun variables

The _pronouns_ are technically barewords, but are not true variables as their content and scoping is dependent on context. This section talks about pronouns in general, for more about each pronoun specifically, refer to it in the Keywords document.
      
Here is a list of the pronouns. The most important thing to know is that pronouns cannot be used except within an appropriate context. Using a pronoun outside of its context will generate a compile error.

  - __it__ - iterators, comprehensions, **exists**, and the __with__ construct
  - __key__ - iterators & comprehensions
  - __sum__ - used by the __into__ comprehension
  - __counter__ - used by the __count__ construct
  - __self__ - used within __set__ statements
  - __trial__ - used by conditionals **if**, **unless**, **switch**, and the **while** looping construct.
  - __error__ - valid within a __catch__ clause only.
    
It's important to remember that you can override the use of any pronoun by specifying a distinct name for the value it represents with the __as__ clause in any of the places where pronouns occur.  

      
### @ prefix - object attributes

Each instantiated object has its own attributes.  


### $ prefix - named parameters

	.. $ 
	.. $[attribute]

When alone, **$** returns the first parameter a function was called with. 

	set ShowParameter to task
	  debug $

	ShowParameter 'Bianca'
	
	> Bianca

When followed immediately by an attribute name, that attribute of the first parameter in a function. (It is not necessary to include the dot.)

	set ShowAttribute to task
	  debug $name

	ShowAttribute friends[0]
	
	> Sara

Even if you use **as** to name your parameters, **$** continues to refer to the first parameter. 

	set ShowParameters to task given p1, p2
	  debug $
	  debug p1
	  debug p2

	ShowParameters 'First', 'Second'
	
	> First
	> First
	> Second


    

### ~ prefix - system globals