Next Chapter
Previous Chapter
Table of Contents

Mapping Slot Data

The map command is a general purpose query and edit facility. For example, what the highest note value and the average rhythm of the events in Nood?

[This example assumes you have imported "noodle.midi" as in the previous chapter and renamed the thread to Nood]

Stella [Top-Level]: map nood highest note and average rhythm
CLAUSE           COUNT  VALUE

highest  note      180  GS6
average  rhythm    180  0.10138889

Stella [Top-Level]:
Map examined the data in Nood and returned information in a table. Each table entry shows the relevant command clause, the number of times it was processed and the value that the clause returned. The first entry says that the highest note in Nood is GS6 and that the clause was processed 180 times. This number might be less than the total number of elements mapped if the clause were conditional.

Mapping Clauses

The syntax of map is unlike any other command discussed so far. Map input consists of a series of clauses. Causes may be independent or conditional. A clause consists of an operator and an expression to evaluate in the context of the currently mapped object. There are three broad categories of clause operators. Information operators collect information about objects and return the results in a table. Command operators edit data. Clause operators connect clauses together. Here is a summary of the various types of mapping clauses

Information Clauses

collect expr        return values of expr in a list
sum expr            return sum of expr
count expr          return number of times expr is true
minimize expr       return minimum value of expr
maximize expr       return maximum value of expr
lowest expr         return minimum frequency of expr
highest expr        return maximum frequency of expr
average expr        return average value of expr
find expr           return positions where expr is true

Command Clauses

set {slot expr}+        set slot to expr
scale {slot expr}+      scale slot by expr
increment {slot expr}+  increment slot by expr
transpose {slot expr}+  transpose slot by expr
invert {slot expr}+     invert slot by expr
insert object           place object before current object
append object           place object after current object
insert-at {pos object}+ place object before pos
append-at {pos object}+ place object after pos
delete object           mark object as deleted
undelete object         undo delete
hide object             mark object as hidden
unhide object           undo hide
print expr              print expr to terminal
do expr                 evaluate expr

Clause Operators

and                        conjoin clauses
when expr clause    do clause if expr is true
unless expr clause  do clause if expr is false
while expr clause   stop if expr is false otherwise do clause
until expr clause   stop if expr is true otherwise do clause

Map Examples

To find the total rhythmic time of Nood:

Stella [Top-Level]: map nood sum rhythm

CLAUSE           COUNT  VALUE
sum      rhythm    180  18.25
To count the number of frequencies above fs5:

Stella [Top-Level]: map nood count (scale> note fs5)

CLAUSE                       COUNT  VALUE
count    (scale> note 'fs5)    180  81

To collect every 20th frequency in a list:

Stella [Top-Level]: map nood[1:*:20] collect note

CLAUSE         COUNT  VALUE
collect  note      9  (C4 GS4 F4 C4 C6 GS4 DS6 C6 DS6)

Conditional Mapping

Conditional operators such as when and unless evaluate a clause only in the event that their predicate test evaluates to true or false. For example, what is the rhythmic time occupied by notes higher than fs5?:

Stella [Top-Level]: map nood when (scale> note 'fs5) sum rhythm

CLAUSE           COUNT  VALUE
sum      rhythm     81  8.625
More than one clause may be conditional on a single test, and mixtures of conditional and independent clauses may also be expressed. The next example counts the note and sum the rhythms of frequencies higher than fs5, but sums all duration.

Stella [Top-Level]: map nood when (scale> note fs5) count note and
sum rhythm sum duration

CLAUSE             COUNT  VALUE
count    note         81  81
sum      rhythm       81  8.625
sum      duration    180  49.875
In this final example, material is scaled if the frequency is either c4, fs4, or c5:

Stella [Top-Level]: map nood when (member note '(c4 fs4 c5)) scale
amplitude 1.5
Stella [Top-Level]: mix nood
Start time offset: (<cr>=None) <cr>
Stella [Top-Level]: 

Next Chapter
Previous Chapter
Table of Contents