MAP {objects} {clause}+

Use commas to delimit more than one object.

Arguments:

  {objects}             One or more objects to map.
  {clause}+             One or more mapping clauses.

  Information clauses:

  COLLECT  {expr} {INTO var}*  Return list of expr.
  SUM      {expr} {INTO var}*  Return the sum of expr.
  COUNT    {expr} {INTO var}*  Return times expr is true.
  MINIMIZE {expr} {INTO var}*  Return the min of expr.
  MAXIMIZE {expr} {INTO var}*  Return the max of expr.
  LOWEST   {expr} {INTO var}*  Minimize for scale references.
  HIGHEST  {expr} {INTO var}*  Maximize for scale references.
  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]+                       ""
  SCALE     {slot expr}+                  ""    
  INCREMENT {slot expr}+                  ""
  TRANSPOSE {slot expr}+                  ""
  INVERT    {slot expr}+                  ""   
  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}*        "" 
  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
  UNDELETE object
  HIDE object
  UNDELETE object

  General:
  PRINT {expr}                 Print expr to terminal.
  DO    {expr}                 Evaluate expr.

  Clause operators:

  AND                          Conjunction of 2 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. 

Overview:

The MAP command maps over {objects} and evaluates each
{clause} in the context of the currently mapped object.
For example:

	map * print $note

would map the clause "print $note" over the objects in *, 
causing the value of the note slot of each element to be 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:

	{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. Note that it is possible
for a map expression to "span" more than one line of input if
the entire expression is delimted by {}.

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:

	{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.

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

	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:

	{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.

See also:

SET, SCALE, INCREMENT, TRANSPOSE, INVERT