- [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:
withdeclares and initializes local process variables initiallyperforms an action before iteration starts finallyperforms a final action immediately after process stops - Iterations
repeatsets the number of times the process runs fordefines a variable over a range of values, stops process when done - 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 - 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
withvar [=form] {andvar2 [=form2]}*-
Declares local process variables and their optional initial values. The
forms in a
withclause are processed one time only immediately before process iteration starts. Each variable declaration in thewithclause can be specified as either:- the name of the variable.
- the name of the variable and an initial value separated by
=.
andto 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)
initiallyform-
Evaluates form when the process is created and before the process starts running.
Example clause syntax:initially (print 'initializing!)
finallyform-
Evaluates form immediately after the process stops.
Example clause syntax:do ... finally (print 'all-done!)
Iterations
repeatform-
Causes the process to run form number of times and then
stop.
Example clause syntax:repeat 23
forvar=form [thenform2]-
Sets var to the value of form on each iteration.
If
thenis 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))
forvar [fromform] [to|belowform] [byform]-
Iterates var over a range of numbers. If the sequence is bounded
the process stops once the last number has been reached.
fromsets the starting value ofvar, defaults to 0.toestablishes an inclusive ceiling on the iteration and stops the process once the value has been reached.belowsets an exclusive ceiling on the iteration and stops the process just before the value has been reached.byprovides an optional increment for var, defaults to 1.
Example clause syntax:for k below 10 for p from 10 to 100 by 5
forvar {in|on} list [byfunction]-
Sets var to successive elements or tails of list and
stops process when iteration is done.
inmaps var over successive elements in list.onmaps var over successive tails of list.byspecifies an optional stepping function. Defaults tocdr.
Example clause syntax:for k in '(c4 d4 ef5 fs)
Actions
outputobject [toio]-
Outputs object to an open output stream. If
tois is not specified the default open output stream is used. The Lisp functionoutputis available for use inside adoclause definition. waitseconds-
Causes the process to wait seconds amount of time before running again.
The Lisp function
waitis available for use inside adoclause definition. sproutobject [attime]-
Inserts object into the currently running scheduling queue
atan optional time. If theattime is not specified the object is inserted at the current time. The Lisp functionsproutis available for use inside adoclause definition. do{form}+- Introduces one or more Lisp forms as part of the process definition.
setvar = 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.
eachvar {in|from} form [as...] action-
Defines an iteration over the action clause.
Eachsupports the same stepping clauses thatfordoes. The difference betweenforandeachis that the former defines a process iteration whileeachdefines 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
whiletest action-
Triggers action clause as long as test is true otherwise stops process.
Example clause syntax:while (< (now) end-time) do ...
untiltest action-
Triggers action clause as long as test is false otherwise stops process.
Example clause syntax:until (= freq 440) do ...
whentest action- Triggers action clause whenever test is true.
unlesstest action- Triggers action clause whenever test is false.
iftest [action {andaction}*] [elseaction {andaction}*]-
Triggers one or more action clauses if test is true otherwise triggers
one or more optional
elseaction clauses.
Examples:
The file intro.cm
contains numerous examples of process descriptions.