3.0 KiB
Brackets
Cagire uses three bracket forms. Each one behaves differently.
( ... ) — Quotations
Parentheses create quotations: deferred code. The contents are not executed immediately — they are pushed onto the stack as a single value.
( dup + )
This pushes a block of code. You can store it in a variable, pass it to other words, or execute it later. Quotations are what make Cagire's control flow work.
Words that consume quotations
Many built-in words expect a quotation on the stack:
| Word | Effect |
|---|---|
? |
Execute if condition is truthy |
!? |
Execute if condition is falsy |
ifelse |
Choose between two quotations |
select |
Pick the nth quotation from a list |
apply |
Execute unconditionally |
times |
Loop n times |
cycle / pcycle |
Rotate through quotations |
choose |
Pick one at random |
every |
Execute on every nth iteration |
chance / prob |
Execute with probability |
bjork / pbjork |
Euclidean rhythm gate |
When a word like cycle or choose selects a quotation, it executes it. When it selects a plain value, it pushes it.
Nesting
Quotations nest freely:
( ( c4 note ) ( e4 note ) coin ifelse ) 4 every
The outer quotation runs every 4th iteration. Inside, a coin flip picks the note.
The mute trick
Wrapping code in a quotation without consuming it is a quick way to disable it:
( kick s . )
Nothing will execute this quotation — it just sits on the stack and gets discarded. Useful for temporarily silencing a line while editing.
[ ... ] — Square Brackets
Square brackets execute their contents immediately, then push a count of how many values were produced. The values themselves stay on the stack.
[ 60 64 67 ]
After this runs, the stack holds 60 64 67 3 — three values plus the count 3. This is useful with words that need to know how many items precede them:
[ 60 64 67 ] cycle note sine s .
The cycle word reads the count to know how many values to rotate through. Without brackets you would write 60 64 67 3 cycle — the brackets save you from counting manually.
Square brackets work with any word that takes a count:
[ c4 e4 g4 ] choose note saw s . ;; random note from the list
[ 60 64 67 ] note sine s . ;; 3-note chord (note consumes all)
Nesting
Square brackets can nest. Each pair produces its own count:
[ [ 60 64 67 ] cycle [ 0.3 0.5 0.8 ] cycle ] choose
Expressions inside brackets
The contents are compiled and executed normally, so you can use any Forth code:
[ c4 c4 3 + c4 7 + ] note sine s . ;; root, minor third, fifth
{ ... } — Curly Braces
Curly braces are ignored by the compiler. They do nothing. Use them as a visual aid to group related code:
{ kick s } { 0.5 gain } { 0.3 verb } .
This compiles to exactly the same thing as:
kick s 0.5 gain 0.3 verb .
They can help readability in dense one-liners but have no semantic meaning.