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

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 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.