sai-language/docs/24.Pronouns.md

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

# 

This file is automatically generated. _Do not edit._

Unknown Heading


### COUNTER - _pronount for integer-based loops_ - pronouns - ^counter

A partner to **count**, **counter** is a _pronoun_, populated by the **count** iterator,
if no other variable is specified in an **as** clause.

    .. counter

Like all pronouns, **counter** is only visible in attached expressions or code blocks, not in
any functions that may be called within those expressions.

An example:

    count friends.length
      debug counter

Similar to **it** in nested contexts, you are unable to access “outer” values of **counter** within
inner contexts unless you assign them to a name other than **counter** using the **as** clause.

    count 3
      count 3
        debug counter
        // only the inner loop's 'counter' is visible here.

    // prints 0 1 2 0 1 2 0 1 2

    count 3 as i
      count 3
        debug i+','+counter
        // outer loop's 'counter' now available here as 'i'

    // prints 0,0  0,1  0,2  1,0  1,1  1,2  2,0  2,1  2,2

    count 3
      count 3 as j
        debug counter+','+j
        // no, this doesn't work, you still can't access the outer 'counter'
        // 'counter' always has the value of the innermost context

    // prints 0,0  1,1  2,2  0,0  1,1  2,2  0,0  1,1  2,2



### ERROR - _catch pronoun_ - pronouns - ^error

summary

    .. error

Valid only within the **catch** exception handler clause of a **try/catch/finally** construct. Receives the exception thrown.

    try
      noFunction
    catch
      debug error

    > [TypeError: undefined is not a function]

You can override this behaviour by using an **as** clause with the **catch** statement:

    try
      noFunction
    catch as e
      debug e

    > [TypeError: undefined is not a function]



### IT - _context-sensitive pronoun_ - pronouns - ^it

**It** is the most commonly used pronoun, populated by most iterators and comprehensions, as well as
the **exists** conditional and **with** contextualizer.

    .. it

_Pronouns_ have values when provided by the system during certain code events.

The **it** variable is only available in attached expressions or code blocks -- not in any functions that
may be called within those expressions, and not in code outside those blocks.

A partial list of **it** enabled events:

    exists [expr] // it: expr
    with [expr]   // it: expr

    iterate [iterable] // it: each iterated value
    each [collection]  // it: each value in the collection
    ply [list]         // it: each element in the array

    .. [collection] | thru // it: each value in the collection
    .. [collection] | audit
    .. [collection] | into
    .. [collection] | has
    .. [collection] | highest
    .. [collection] | lowest

When nesting contexts that create a **it** context, you will be unable to access “outer”
values of **it** within the inner contexts unless you assign them to a name other
than **it** using the **as** clause.

    ply: 1,2,3
      ply: 4,5,6
        debug it

    // prints 4 5 6 4 5 6 4 5 6

    ply: 1,2,3
      ply: 4,5,6 as inner
        debug it

    // still prints 4 5 6 4 5 6 4 5 6

    ply: 1,2,3 as outer
      ply: 4,5,6
        debug outer

    // prints 1 1 1 2 2 2 3 3 3

When **it** is populated, you can also use the “unrooted” **attribute** ( . dot) scoping
prefix.  The following are all synonymous:

    set field to 'province'
    set quebeckers to friends has it.province='QC'
    set quebeckers to friends has it[field]='QC'
    set quebeckers to friends has .province='QC'

(There is no unrooted [] lookup available, you can't `[field]`.)



### KEY - _looping pronoun_ - pronouns - ^key

Often a partner to **it**, **key** is the second most commonly used _pronoun_, populated by most
iterators and comprehensions.

    .. key

Like all pronouns, **keys** is only visible in attached expressions or code blocks, not in any functions that may be called within those expressions.

A partial list of **keys** enabled events:

    each [collection]   // key: the trait name of each value in the collection
    ply [list]          // key: the array index of each element in the array
    count [expr]        // key: the number being counted
    iterate [generator] // key: the row number of the value being processed

    .. [collection] thru  // key: each trait name/array index of the collection
    .. [collection] audit
    .. [collection] into
    .. [collection] has

An example:

    ply friends
      debug key

    // prints: 0 1 2 3 4 5 6 7

    each friends[0]
      debug key

    // prints: name age cat province

Similar to **it** and **counter** in nested contexts, you are unable to access “outer”
values of **key** within inner contexts unless you assign them to a specific variable
using the **as** clause. See **counter** for an example of this issue.



### SELF - _pronoun for set statements_ - pronouns - ^self

A pronoun used only in a **set** statement that contains the original value of the variable
that is being set/modified.

    set [var] .. self ..

The following lines are equivalent; one of them is easier to read than the other.

    set totalskey to totalskey ? 0 + amount
    set totalskey to self ? 0 + amount



### SUM - _reduction pronoun_ - pronouns - ^sum

A pronoun active only within a **into** clause or code block.

    .. sum

Represents the static value that accumulates changes during **into** iteration over a data set.

    debug friends | into 0
      set sum + .age

    > 185

**Sum** is initialized with the value following **into**.

    debug friends | into blank
      set sum[.province] to (self default 0)+1

    > { ON: 5, QC: 3 }



### TRIAL - _pronoun for conditionals and switch_ - pronouns - ^trial

A pronoun set to the value tested in an **if/exists** or **switch** statement.

    if [expr]
      .. trial ..
    
    switch [expr]
      case [match]
        .. trial ..
      default
        .. trial ..

In an **if/exists** statement, **trial** is only valid in the body of the first code block.

    exists readline()
      // trial is available here
    else
      // trial is undefined here

In a **switch** statement, **trial** is available through all **case**s and the **default**.

    switch Keypress.toUpperCase()
      case 'N'
        Move 0,-1
      case 'S'
        Move 0,1
      default
        debug 'I don't know what ${trial} means.'
    ...

You can grant a specific name to the tested value with the **as** clause:

    if Keypress as key
      switch key.toUpperCase()
    ...

Note that **trial** receives the tested value; the final result of the **if** or **switch** expression, not the value of any component:

    if Keypress>0
      debug trial

    // the debug statement can only ever print 'true'

Using the parenthetical **as** is one solution to this problem:

    if ( Keypress as key) > 0
      debug key

    // reports the actual value of key