map {objects} {clause}+ [Command]

Maps over {objects} and evaluates each {clause} in the context of the currently mapped object. For example:

Stella [Top-Level]: map * collect note
would map the clause collect note over the objects in *, causing the value of the note slot of each element to be collected in a list and printed to the terminal.

There are two broad categories of clauses: informational clauses and command clauses. Informational clauses perform some sort of statistical operation on each object mapped and then display the combined results of the operation at the end of the command. Informational clauses are generally in the form: {operator expr} where operator is the information action to perform and expr is the expression to evaluate in the context of the currently mapped object. For example:

Stella [Top-Level]: map * sum rhythm and collect (transpose note -1)
would map two informational clauses over all the elements in *, displaying the sum of all rhythms and the list of all the transposed notes at the conclusion..

Command clauses generally have an exact command analogue in the top-level interpreter. These top level commands have been imbedded in the map command to support conditional editing and complex editing combinations. For example:

Stella [Top-Level]: {map * when (scale> note 'c4) scale rhythm .1 
                        and set amp (between .1 .6)}
would perform the SCALE and SET commands only in the event that the current object's note was higher than C5. Command clauses are generally in the form {operator {slot expr}+} where operator is the name of the top-level command and {slot expr+} are one or more pairs of slot name and value expressions. Note that it is possible for a map expression to "span" more than one line of input if the entire expression is delimited by {}

Clauses of any type may be optionally joined by the AND operator, or made conditional by the when and unless operators. For example:

Stella [Top-Level]: map * print note and sum rhythm
would print each note value and sum each rhythm value in *. Note that, since clauses are normally processed conjunctively anyway, using the AND operator is only necessary in the case of a conditional clause having more than one consequent. For example:
Stella [Top-Level]: {map * when (> amp .2) transpose note -12
                        and scale rhythm 1.5 dur .5
                        print note}
would map over all the elements in * and, for each element whose amp value is greater than .2, would transpose its note value down one octave and scale its rhythm value by 1.5 and its dur value by .5. The value of the note slot would always be printed. (Since it is not connected to the WHEN predicate by a conjunction the PRINT clause is therefor a second "top-level" clause.)

The following is a table of clause operators grouped by functionality. For information about the evalutation rules of operator expressions (denoted "expr" in table), see the help text for the SET command.

Information clauses:

collect {expr} {into var}*
Return list of expr.
sum {expr} {into var}*
Return the sum of expr.
count {expr} {into var}*
Count number of times expr is true.
minimize {expr} {into var}*
Return the smallest value of expr.
maximize {expr} {into var}*
Return the maximum value of expr.
lowest {expr} {into var}*
Minimize allowing note names.
highest {expr} {into var}*
Maximize allowing note names.
average {expr}
Return average value of expr.
find {expr}
Return pos where expr is true.
analyze {slot}
Print statistics about values in slot.

Command clauses

Slot values:

set {slot expr}+
Same as top level command.
unset {slot+
Same as top level command.
scale {slot expr}+
Same as top level command.
increment {slot expr}+
Same as top level command.
transpose {slot expr}+
Same as top level command.
invert {slot expr}+
Same as top level command.
round {slot decimal}+
Round data to decimal number of places.
quantize {slot step}+
Fit data to be increments of step size.
Objects:
change {newclass} {news old}*
Same as top level command.
insert {object}
Put object before current.
append {object}
Put object after current.
insert-at {pos object}+
Place object before pos.
append-at {pos object}+
Place object after pos.
delete {object}
Delete object.
undelete {object}
Undelete object.
hide {object}
Hide object
unhide {object}
Unhide object
mute {object}
Mute object
unmute {object}
Unmute object
General:
print {expr}
Print {expr} to terminal.
do {expr}
Evaluate {expr}

Clause Operators

and {clause}
Conjunction of two clauses.
when {expr} {clause}
Do {clause} if {expr} is true.
unless {expr} {clause}
Do {clause} if {expr} is false.
while {expr} {clause}
Return if {expr} false.
until {expr} {clause}
Return if {expr} true.

See Also:

set, scale, increment, transpose, invert


Last Modified: 5-Mar-1998