[Macro]
(process {clause}+)

Defines an iterative musical process using the same basic syntax as Lisp's loop macro. The body of a process definition consists of a series of clauses, each clause begins with a clausal operator. There are four broad categories of clauses:

  1. Initializations and finalizations:
    with declares and initializes local process variables
    initiallyperforms an action before iteration starts
    finallyperforms a final action immediately after process stops
  2. Iterations
    repeatsets the number of times the process runs
    fordefines a variable over a range of values, stops process when done
  3. Actions
    doevaluates one or more Lisp statements
    eachiterates action clause
    outputoutputs an event into the open output stream
    sproutinserts a new object into the scheduling queue
    waitprocess waits a specified amount of time before running again
  4. Conditionals
    whileevaluates an action if a test is true or stops the process if false
    untilevaluates an action if a test is or stops the process if true
    whenevaluates an action if a test is true
    unlessevaluates an action if a test is false
    ifevaluates one or more "then" or "else" actions based on a test

Iteration and action clauses are executed in the same order in which they appear in the code but the first action clause must appear after all initialization and iteration clauses. If more than one iteration clause is specified the process terminates as soon as the earliest iteration terminates.

Initializations and finalizations

with var [= form] {and var2 [= form2]}*
Declares local process variables and their optional initial values. The forms in a with clause are processed one time only immediately before process iteration starts. Each variable declaration in the with clause can be specified as either:
  • the name of the variable.
  • the name of the variable and an initial value separated by =.
If an initial value is not specified a variable is initialized to false. Use and to separate variables if more than one variable is declared. Declarations are processed in left to right order so a = value may reference variables declared to the left.
Example clause syntax:
with a and b = 32 and c = (* (random b) 4)
initially form
Evaluates form when the process is created and before the process starts running.
Example clause syntax:
initially (print 'initializing!)
finally form
Evaluates form immediately after the process stops.
Example clause syntax:
do ...
finally (print 'all-done!)

Iterations

repeat form
Causes the process to run form number of times and then stop.
Example clause syntax:
repeat 23
for var = form [then form2]
Sets var to the value of form on each iteration. If then is supplied var is set to form on the first iteration and to form2 on subsequent iterations.
Example clause syntax:
for k = (now)
for p = 60 then (+ p (random 10))
for var [from form] [to | below form] [by form]
Iterates var over a range of numbers. If the sequence is bounded the process stops once the last number has been reached.
  • from sets the starting value ofvar, defaults to 0.
  • to establishes an inclusive ceiling on the iteration and stops the process once the value has been reached.
  • below sets an exclusive ceiling on the iteration and stops the process just before the value has been reached.
  • by provides an optional increment for var, defaults to 1.

Example clause syntax:
for k below 10
for p from 10 to 100 by 5 
for var {in | on} list [by function]
Sets var to successive elements or tails of list and stops process when iteration is done.
  • in maps var over successive elements in list.
  • on maps var over successive tails of list.
  • by specifies an optional stepping function. Defaults to cdr.

Example clause syntax:
for k in '(c4 d4 ef5 fs)

Actions

output object [to io]
Outputs object to an open output stream. If to is is not specified the default open output stream is used. The Lisp function output is available for use inside a do clause definition.
wait seconds
Causes the process to wait seconds amount of time before running again. The Lisp function wait is available for use inside a do clause definition.
sprout object [at time]
Inserts object into the currently running scheduling queue at an optional time. If the at time is not specified the object is inserted at the current time. The Lisp function sprout is available for use inside a do clause definition.
do {form}+
Introduces one or more Lisp forms as part of the process definition.
set var = form
Sets the variable var to the value of form. Set only sets the variable, i.e. it does not actually declare or bind the variable in the process.
each var {in | from} form [as ...] action
Defines an iteration over the action clause. Each supports the same stepping clauses that for does. The difference between for and each is that the former defines a process iteration while each defines an iterative action inside the process. The following two clause descriptions are equivalent:
each i in lst output ...
do (loop for i in lst do (output ...))

Conditionals

while test action
Triggers action clause as long as test is true otherwise stops process.
Example clause syntax:
while (< (now) end-time)
do ...
until test action
Triggers action clause as long as test is false otherwise stops process.
Example clause syntax:
until (= freq 440)
do ...
when test action
Triggers action clause whenever test is true.
unless test action
Triggers action clause whenever test is false.
if test [action {and action}*] [else action {and action}*]
Triggers one or more action clauses if test is true otherwise triggers one or more optional else action clauses.

Examples:

The file intro.cm contains numerous examples of process descriptions.