process

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
   initially	performs an action before iteration starts
   finally	performs a final action immediately after process stops

2. Iterations

   repeat	sets the number of times the process runs
   for	defines a variable over a range of values, stops process when done

3. 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
   ms:output	outputs a foreign entity to a Midishare stream
   pm:output	outputs a foreign entity to a Portmidi stream

4. 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 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 terminates.
Example clause syntax:

do ...
finally (print 'all-done!)

Iterations

repeat form

Causes the process to run form number of times and then terminate.
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 terminates 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 then terminates then process when the iteration is complete.

• 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)

for var over pattern [by length]

Sets var to successive elements read from pattern, the process terminates if the pattern ever reaches end of data. If by a number that many elements are read at a time and returned to var as a list. If the length is or boolean true a whole period's worth of items are read when var is incremented.
Example clause syntax:

for k over (pattern heap of keynums c4 d e f g repeat 3)

Actions

output object [to io] [at time]

Outputs object to an open output stream. If to is not specified the default open output stream is used. Use at to output the current value of now for objects such as midi messages that do not have a method defined for object-time. 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 ...))

ms:output object [to stream]

Outputs a foreign Midishare object directly to Midishare. See ms:output for more information.

pm:output object [to stream] [at msec] [raw {boolean | length}]

Outputs a foreign Portmidi object directly to Portmidi. See pm:output for more information.