Cagire/docs/tutorials/variables.md

Using Variables

Variables let you name values and share data between steps. They are global -- any step can read what another step wrote.

Store and Fetch

!name stores the top of the stack into a variable. @name fetches it back. Variables spring into existence when you first store to them. Fetching a variable that was never stored returns 0.

10 !x        ;; store 10 in x
@x           ;; pushes 10
@y           ;; pushes 0 (never stored)

Store and Keep

,name stores just like !name but keeps the value on the stack. Useful when you want to name something and keep using it:

440 ,freq sine s .   ;; stores 440 in freq AND passes it to the pipeline

Without ,, you'd need dup:

440 dup !freq sine s .   ;; equivalent, but noisier

Sharing Between Steps

Variables are shared across all steps. One step can store a value that another reads:

;; step 0: pick a root note
c4 iter 7 mod + !root

;; step 4: read it
@root 7 + note sine s .

Every time the pattern loops, step 0 picks a new root. Step 4 always harmonizes with it.

Accumulators

Fetch, modify, store back. A classic pattern for evolving values:

@n 1 + !n              ;; increment n each time this step runs
@n 12 mod note sine s . ;; cycle through 12 notes

Reset on some condition:

@n 1 + !n
{ 0 !n } @n 16 > ?    ;; reset after 16

Naming Sounds

Store a sound name in a variable, reuse it across steps:

;; step 0: choose the sound
"sine" !synth

;; step 1, 2, 3...
c4 note @synth s .

Change one step, all steps follow.