109 lines
3.0 KiB
Markdown
109 lines
3.0 KiB
Markdown
# 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.
|
|
|
|
```forth
|
|
( 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:
|
|
|
|
```forth
|
|
( ( 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:
|
|
|
|
```forth
|
|
( 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.
|
|
|
|
```forth
|
|
[ 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:
|
|
|
|
```forth
|
|
[ 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:
|
|
|
|
```forth
|
|
[ 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:
|
|
|
|
```forth
|
|
[ [ 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:
|
|
|
|
```forth
|
|
[ 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:
|
|
|
|
```forth
|
|
{ kick s } { 0.5 gain } { 0.3 verb } .
|
|
```
|
|
|
|
This compiles to exactly the same thing as:
|
|
|
|
```forth
|
|
kick s 0.5 gain 0.3 verb .
|
|
```
|
|
|
|
They can help readability in dense one-liners but have no semantic meaning.
|