93 lines
2.8 KiB
Markdown
93 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```forth
|
|
60 64 67 3 cycle note sine snd . ;; 60, 64, 67, 60, 64, 67, ...
|
|
```
|
|
|
|
`pcycle` advances based on `iter` — the pattern iteration count:
|
|
|
|
```forth
|
|
kick snare 2 pcycle snd . ;; 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, ...
|
|
|
|
```forth
|
|
60 64 67 72 4 bounce note sine snd . ;; ping-pong by step runs
|
|
60 64 67 72 4 pbounce note sine snd . ;; ping-pong by pattern iteration
|
|
```
|
|
|
|
Same `runs` vs `iter` split as `cycle` / `pcycle`.
|
|
|
|
## choose
|
|
|
|
Uniform random selection:
|
|
|
|
```forth
|
|
kick snare hat 3 choose snd . ;; 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:
|
|
|
|
```forth
|
|
kick 0.5 snare 0.3 hat 0.2 3 wchoose snd .
|
|
```
|
|
|
|
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:
|
|
|
|
```forth
|
|
[ c4 e4 g4 ] step index note sine snd . ;; step number picks the note
|
|
[ c4 e4 g4 ] iter index note sine snd . ;; 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:
|
|
|
|
```forth
|
|
[ 60 64 67 ] cycle note sine snd . ;; no need to write "3"
|
|
[ kick snare hat ] choose snd .
|
|
[ c4 e4 g4 b4 ] bounce note sine snd .
|
|
```
|
|
|
|
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:
|
|
|
|
```forth
|
|
[ ( c4 note ) ( e4 note ) ( g4 note ) ] cycle
|
|
sine snd .
|
|
```
|
|
|
|
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:
|
|
|
|
```forth
|
|
[ ( hat snd 0.3 gain . ) ( snare snd . ) ( kick snd . ) ] choose
|
|
```
|