[Class]
join

Defines a merging of two or more sub-patterns. The joined patterns are read in parallel and their elements are returned as list elements with the same ordering as the sub-patterns in the join.

join supports the following slot initializations:

:format list

Specifies the method for merging data from the individual patterns. If the initialization is not specified then each sub-pattern will be read each time the join is read and the join pattern will be at end-of-period when the all of the sub-patterns are concurrently at end-of-period. Otherwise list is of the format

({:eop | true | false}+)

where there are as many elements in list as their are joined patterns and each entry in the list determines how its corresponding sub-pattern (in left-to-right-order in the pattern data) is treated by the join. The value :eop means that the corresponding pattern is read each time the join is read and it determines when the join is at end-of-period. If the value is true then the corresponding pattern is read each time the join is read but it does not contribute to the period length of the join. If the value is false then the corresponding pattern is read only once per period of the join. A false entry will therefore "spread" one element from the corresponding sub-pattern over all the other joined elements returned in the period.

See generic pattern initializations for documentation on additional keyword initializations to the pattern.

Examples:

Example 1. Generating random notes with consistent rhythmic identities. 

(define pat1
  (new random 
       :of (list (new join :of `(,(new random :of '(c4 g4) :for 1)
                                  h))
                 (new join :of `(,(new random :of '(d4 f4) :for 1)
                                  q))
                 (new join :of `(,(new random :of '(cs4 ds4 fs4) :for 1)
                                  e)))))
(define (play-pat reps pat tempo)
  (process repeat reps
           for m = (next pat)
           output (new midi :time (now)
                            :keynum (first m)
                            :duration (rhythm (second m) tempo))
           wait (rhythm (second m) tempo)))

(events (play-pat 40 pat1 120) "test.mid")
⇒ "test.mid"

Example 2. Three dimensional motives with random variation. 

(define pat1
  (new cycle 
    :of (list (new join 
                :of (list (new cycle
                               :of `(,(new random :of '(ef5 bf4 bf3)
                                                 :for 1)
                                     e4 r))
                          (new cycle :of '(s s q) )
                          'ff))
              (new join
                :of (list (new heap :of '(g4 fs4 fn5 b5))
                          (new cycle 
                            :of (list (new heap :of '(e q e))
                                      'h))
                          'p))
              (new join 
                :of (list (new cycle :of '(af5 f5 a4 cs4 c5))
                          (new heap :of '(e s q) :for 5)
                          (new cycle :of '(pp p mp mf f)))))))

(define (play-pat reps pat tempo)
  (process repeat reps
           for m = (next pat)
           output (new midi :time (now)
                            :keynum (first m)
                            :amplitude (amplitude (third m))
                            :duration (rhythm (second m) tempo))
           wait (rhythm (second m) tempo)))

(events (play-pat 80 pat1 120) "test.mid")
⇒ "test.mid"

See also: