strum.lsp
 Version 1.00    31 October 2004
 Author Steven Jones

 Contact jones57@swbell.net include the word "nyquist" in subject line

 The contents of this file are released under the terms of the GNU General
 Public License. See the file LICENSE.txt

 Initially a method for simulating strummed strings, strum.lsp has since
 evolved (degenerated?) into a general purpose arpeggiator.

function

 (strum:copies plist n [mode])
 Generate list by appending multiple copies of a source list together.

 plist  - list. The source list

 n      - integer. Number of copies used.

 mode   - symbol. The method used to copy source list. 
          For the following examples the source list is '(A B C D)
          'REV   - Reverse  --> (D C B A ... )
          'LOOP  -          --> (A B C D C B ... )
          'LOOP2 -          --> (A B C D D C B A ... )
          'PERM  -          --> n random permutations of source list
          'RND   -          --> n * (length plist) random elements from plist
          'F     - Forward  --> (A B C D ... ) The default mode

 return - list.

function

 (strum plist dur n time [:stfn][:stmood][args...])
 Arpeggiate note list
 
 plist   - list. A list of MIDI key numbers to be produced.
 
 dur     - flonum. The duration value is not used directly by strum but is
           passed as the second argument to sound generating function. With 
           the default function it is the pluck decay time.

 n       - integer. Number of times to iterate over plist.

 time    - flonum. The temporal value between notes. 

 :stfn   - closure. A sound generating function which must have the lambda
           list  (lambda (pitch dur [args ...]))

 :stmood - symbol. The iteration mood. Six moods are recognized
           Let plist have the form (A B C D) for the following examples:
           'F     - Forward. Play (A B C D ... ). This is the default
           'REV   - Revers. Play  (D C B A ...)
           'LOOP  - Loop with out repeating endpoints   (A B C D C B ....)
           'LOOP2 - Loop with repeating endpoints   (A B C D D C B A ...)
           'PERM  - Each iteration over plist is a random permutation of plist
                    All elements of plist are used.
           'RND   - Pick elements from plist at random. 

 args..  - any. Additional arguments are aggregated to a list and passed
           to stfn

 return  - sound.

;; strum.lsp
;; Version 1.00    31 October 2004
;; Author Steven Jones
;;
;; Contact jones57@swbell.net include the word "nyquist" in subject line
;;
;; The contents of this file are released under the terms of the GNU General
;; Public License. See the file LICENSE.txt
;;
;; Initially a method for simulating strummed strings, strum.lsp has since
;; evolved (degenerated?) into a general purpose arpeggiator.
;; 

(require 'math)
(provide 'strum)
(current-file "strum")


;; Appends reversed copy of a list to itself minus endpoints.
;; 
;;        (A B C D) ---> (A B C D C B)
;;

(defun strum:gnomon (plist)
  (butlast (append plist (cdr (reverse plist)))))


;; @doc function strum:copies
;; (strum:copies plist n [mode])
;; Generate list by appending multiple copies of a source list together.
;;
;; plist  - list. The source list
;;
;; n      - integer. Number of copies used.
;;
;; mode   - symbol. The method used to copy source list. 
;;          For the following examples the source list is '(A B C D)
;;          'REV   - Reverse  --> (D C B A ... )
;;          'LOOP  -          --> (A B C D C B ... )
;;          'LOOP2 -          --> (A B C D D C B A ... )
;;          'PERM  -          --> n random permutations of source list
;;          'RND   -          --> n * (length plist) random elements from plist
;;          'F     - Forward  --> (A B C D ... ) The default mode
;;
;; return - list.
;;

(defun strum:copies (plist n &optional (mood 'F))
  (flatten
   (cond ((eq mood 'REV)(copies n (reverse plist)))
	 ((eq mood 'LOOP)(copies n (strum:gnomon plist)))
	 ((eq mood 'LOOP2)(copies n (append plist (reverse plist))))
	 ((eq mood 'PERM)(let ((acc '()))
			  (dotimes (i n)
			    (setf acc (append acc (permute plist))))
			  acc))
	 ((eq mood 'RND)(let (acc '())
			  (dotimes (i n)
			    (dotimes (j (length plist))
			      (setf acc (cons (pick plist) acc))))
			  acc))
	 (t (copies n plist)))))


;; @doc function strum
;; (strum plist dur n time [:stfn][:stmood][args...])
;; Arpeggiate note list
;; 
;; plist   - list. A list of MIDI key numbers to be produced.
;; 
;; dur     - flonum. The duration value is not used directly by strum but is
;;           passed as the second argument to sound generating function. With 
;;           the default function it is the pluck decay time.
;;
;; n       - integer. Number of times to iterate over plist.
;;
;; time    - flonum. The temporal value between notes. 
;;
;; :stfn   - closure. A sound generating function which must have the lambda
;;           list  (lambda (pitch dur [args ...]))
;;
;; :stmood - symbol. The iteration mood. Six moods are recognized
;;           Let plist have the form (A B C D) for the following examples:
;;           'F     - Forward. Play (A B C D ... ). This is the default
;;           'REV   - Revers. Play  (D C B A ...)
;;           'LOOP  - Loop with out repeating endpoints   (A B C D C B ....)
;;           'LOOP2 - Loop with repeating endpoints   (A B C D D C B A ...)
;;           'PERM  - Each iteration over plist is a random permutation of plist
;;                    All elements of plist are used.
;;           'RND   - Pick elements from plist at random. 
;;
;; args..  - any. Additional arguments are aggregated to a list and passed
;;           to stfn
;;
;; return  - sound.
;;

(defun strum (plist dur n time &rest args &key stfn stmood)
  (let ((stfn (or stfn #'(lambda (p d &rest dummy)(pluck p d)))))
    (setf plist (strum:copies plist n stmood))
    (setf args (cons dur args))
    (simrep (index (length plist))
	    (at (* index time)
		(cue (apply stfn (cons (nth index plist) args)))))))