- [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:
- Initializations and finalizations:
with
declares and initializes local process variables initially
performs an action before iteration starts finally
performs a final action immediately after process stops - Iterations
repeat
sets the number of times the process runs for
defines a variable over a range of values, stops process when done - Actions
do
evaluates one or more Lisp statements each
iterates action clause output
outputs an event into the open output stream sprout
inserts a new object into the scheduling queue wait
process waits a specified amount of time before running again - Conditionals
while
evaluates an action if a test is true or stops the process if false until
evaluates an action if a test is or stops the process if true when
evaluates an action if a test is true unless
evaluates an action if a test is false if
evaluates 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 thewith
clause can be specified as either:- the name of the variable.
- the name of the variable and an initial value separated by
=
.
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 tocdr
.
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 functionoutput
is available for use inside ado
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 ado
clause definition. sprout
object [at
time]-
Inserts object into the currently running scheduling queue
at
an optional time. If theat
time is not specified the object is inserted at the current time. The Lisp functionsprout
is available for use inside ado
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 thatfor
does. The difference betweenfor
andeach
is that the former defines a process iteration whileeach
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.