Command Expressions

[Topic]

A number of Stella's commands evaluate "command expressions", or exprs, whose results are then processed by the command in some manner. For example, the set command evaluates exprs to return new slot values for the referenced objects. The map command evaluates exprs in the context of each referenced object to compute statistics that are displayed in an information table. A command expression may be as simple as a variable or slot name, or may involve complicated parenthetical expressions. Though exprs are evaluated and may involve Lisp's prefix notation, they are not strictly Lisp. Exprs implement a number of changes and additions to basic Lisp syntax in order to support a comfortable yet terse input style. For example, the simple command expression:

rhythm

is roughly equivalent to the Lisp expression:

(or (and (slot-exists-p (mapped-object) 'rhythm)
         (slot-boundp (mapped-object) 'rhythm)
         (slot-value (mapped-object) 'rhythm)
    0)

Since command expressions are not strictly Lisp, they are only meaningful in conjunction with commands that understand their syntax and evaluation rules. These commands are: increment, invert, map, scale, set, transpose and unset. These commands are called mapping commands because they all map expressions over the references supplied to the command and evaluate each expressions in the context of each mapped object. The expressions rhythm, then, really means: "the value of the slot named rhythm in the currently mapped object, or 0 if that object has no rhythm." Note that when referencing by group there is no "currently mapped object" to speak of, since all members of a group are mapped in parallel. To access slot values and so fourth of an object within the currently mapped group, the access must be qualified with the object's index into the group. This index ranges from 1 to the width of the group, and is specified inside brackets after the basic name. For example:

Stella [Top-Level]: map :::2 find (= rhythm[1] rhythm[2])

would perform a pairwise examination of all the objects in * and return the index of each pair of objects that have the same value in their rhythm slots.

Command expression syntax and evaluation rules

Here is a brief summary of the syntax and evaluation rules for command expressions.

A symbol preceded by a $ is always interpreted as a slot name. Stella does her level best to determine if an unquoted symbol is meant as data, a variable or a slot name; the $ makes this unambiguous and is useful in cases where, say, a variable is actually meant as a slot name or the or the symbol is included inside a list expression.
A constant (string, number, defconstant or any quoted form) may appear anywhere in an expr and evaluates to its constant value.
An unquoted list may appear anywhere in an expr. If the first element is a valid function, the list is treated as a function call. Arguments to the function themselves treated as exprs. If the first element is not a function, the list is treated as constant data.
An unbound symbol (a symbol that does not have a value) may appear anywhere in an expr and is considered constant data.
A slot name evaluates to the value of that slot in the currently mapped object.
An item stream description is pre-evaluated to produce the item stream, and the stream object is automatically read using the item function. For example:
```
Stella [Top-Level]: set * note (pitches c4 d e in random)
```
would set the note slot of each object in * to successive pitches read from a random pitch stream.
An expr directly preceded by a comma is pre-evaluated before the command starts, and the result of this evaluation is used as the expr specification for the mapping. This allows, in effect, the computation of the mapping expression.

There are also several variables that are useful when working with value expressions.

The expr variables @ and @+1 may appear anywhere in an expr and are bound to the container position (zero and one based, respectively) of the currently mapped object. @ and @+1 are useful in conjunction with interpolating envelopes, for example:
```
Stella [Top-Level]: set * freq (interpl @ 0 220.0 40 440.0)
```
would set the freq slot of the (presumably forty) objects in * to an interpolated value between 200.0 and 400.0 Hz. It is also possible to qualify @ and @+1 by a group index, for example, @[1] would mean the container position of the first element in the currently mapped group.
The expr variable % may appear anywhere in an expr and is bound to the the container position of the currently mapped element expressed as a percentage. % is particularly useful in conjunction with normalized interpolating envelopes, for example:
```
Stella [Top-Level]: set * freq (interpl % 0 220.0 100 440.0)
```
would set the freq slot of the elements in * to an interpolated value between 200.0 and 400.0 Hz. It is possible to qualify % by a group index, for example, %[1] would mean the percentage position of the first element in the currently mapped group.
The special variable $$ may appear anywhere in an expr and is bound to the container (if only one) whose object is currently being mapped.

The mapping variables @, @+1, % and the special variable ? all have functional equivalents:

(@ object &optional container)
(@+1 object &optional container)
(% object &optional container)
(? object slot &optional value)

See Also:

increment [Command], invert [Command], map [Command], scale [Command], set [Command], transpose [Command] unset [Command]

Last Modified: 5-Mar-1998