Cycling & Selection

These words all share a pattern: push values onto the stack, then select one. If the selected item is a quotation, it gets executed. If it is a plain value, it gets pushed. All of them support [ ] brackets for auto-counting.

cycle / pcycle

Sequential rotation through values.

cycle advances based on runs — how many times this particular step has played:

60 64 67 3 cycle note sine s .    ;; 60, 64, 67, 60, 64, 67, ...

pcycle advances based on iter — the pattern iteration count:

kick snare 2 pcycle s .    ;; kick on even iterations, snare on odd

The distinction matters when patterns have different lengths or when multiple steps share the same script. cycle gives each step its own independent counter. pcycle ties all steps to the same global pattern position.

bounce / pbounce

Ping-pong instead of wrapping. With 4 values the sequence is 0, 1, 2, 3, 2, 1, 0, 1, 2, ...

60 64 67 72 4 bounce note sine s .    ;; ping-pong by step runs
60 64 67 72 4 pbounce note sine s .   ;; ping-pong by pattern iteration

Same runs vs iter split as cycle / pcycle.

choose

Uniform random selection:

kick snare hat 3 choose s .    ;; random drum hit each time

Unlike the cycling words, choose is nondeterministic — every evaluation picks independently.

wchoose

Weighted random. Push value/weight pairs, then the count:

kick 0.5  snare 0.3  hat 0.2  3 wchoose s .

Kick plays 50% of the time, snare 30%, hat 20%. Weights are normalized automatically — they don't need to sum to 1.

index

Direct lookup by an explicit index. The index wraps with modulo, so it never goes out of bounds. Negative indices count from the end:

[ c4 e4 g4 ] step index note sine s .    ;; step number picks the note
[ c4 e4 g4 ] iter index note sine s .    ;; pattern iteration picks the note

This is useful when you want full control over which value is selected, driven by any expression you like.

Using with brackets

All these words take a count argument n. Square brackets compute that count for you:

[ 60 64 67 ] cycle note sine s .      ;; no need to write "3"
[ kick snare hat ] choose s .
[ c4 e4 g4 b4 ] bounce note sine s .

Without brackets: 60 64 67 3 cycle. With brackets: [ 60 64 67 ] cycle. Same result, less counting.

Quotations

When any of these words selects a quotation, it executes it instead of pushing it:

[ ( c4 note ) ( e4 note ) ( g4 note ) ] cycle
sine s .

On the first run the quotation ( c4 note ) executes, setting the note to C4. Next run, E4. Then G4. Then back to C4.

This works with all selection words. Mix plain values and quotations freely:

[ ( hat s 0.3 gain . ) ( snare s . ) ( kick s . ) ] choose

2.8 KiB Raw Blame History