BuboBubo/Cagire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix: update docs about snd

Browse Source
This commit is contained in:
Raphaël Forment
2026-03-06 08:40:41 +01:00
parent f273470eaf
commit d055d2bfc6
23 changed files with 228 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/forth/about_forth.md
View File

@@ -78,7 +78,7 @@ Because parentheses defer execution, wrapping code in `( ... )` without a consum
.
```
Any word that is not recognized as a built-in or a user definition becomes a string on the stack. This means `kick s` and `"kick" s` are equivalent. You only need quotes when the string contains spaces or when it conflicts with an existing word name.
Any word that is not recognized as a built-in or a user definition becomes a string on the stack. This means `kick snd` and `"kick" snd` are equivalent. You only need quotes when the string contains spaces or when it conflicts with an existing word name.
## The Command Register
@@ -94,7 +94,7 @@ kick sound ;; sets the sound name
. ;; emits the command and clears the register
```
The word `sound` (or its shorthand `s`) sets what sound to play. Parameter words like `gain`, `freq`, `decay`, or `verb` add key-value pairs to the register. Nothing happens until you emit with `.` (dot). At that moment, the register is packaged into a command and sent to the audio engine.
The word `sound` (or its shorthand `snd`) sets what sound to play. Parameter words like `gain`, `freq`, `decay`, or `verb` add key-value pairs to the register. Nothing happens until you emit with `.` (dot). At that moment, the register is packaged into a command and sent to the audio engine.
This design lets you build sounds incrementally:
@@ -110,14 +110,14 @@ c4 note
Each line adds something to the register. The final `.` triggers the sound. You can also write it all on one line:
```forth
"sine" s c4 note 0.5 gain 0.3 decay 0.4 verb .
"sine" snd c4 note 0.5 gain 0.3 decay 0.4 verb .
```
The order of parameters does not matter. You can even emit multiple times in a single step. If you need to discard the register without emitting, use `clear`:
```forth
"kick" s 0.5 gain clear ;; nothing plays, register is emptied
"hat" s . ;; only the hat plays
"kick" snd 0.5 gain clear ;; nothing plays, register is emptied
"hat" snd . ;; only the hat plays
```
This is useful when conditionals might cancel a sound before it emits.

14
docs/forth/brackets.md
View File

@@ -47,7 +47,7 @@ The outer quotation runs every 4th iteration. Inside, a coin flip picks the note
Wrapping code in a quotation without consuming it is a quick way to disable it:
```forth
( kick s . )
( kick snd . )
```
Nothing will execute this quotation — it just sits on the stack and gets discarded. Useful for temporarily silencing a line while editing.
@@ -63,7 +63,7 @@ Square brackets execute their contents immediately, then push a count of how man
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 .
[ 60 64 67 ] cycle note sine snd .
```
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.
@@ -71,8 +71,8 @@ The `cycle` word reads the count to know how many values to rotate through. With
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)
[ c4 e4 g4 ] choose note saw snd . ;; random note from the list
[ 60 64 67 ] note sine snd . ;; 3-note chord (note consumes all)
```
### Nesting
@@ -88,7 +88,7 @@ Square brackets can nest. Each pair produces its own count:
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
[ c4 c4 3 + c4 7 + ] note sine snd . ;; root, minor third, fifth
```
## { ... } — Curly Braces
@@ -96,13 +96,13 @@ The contents are compiled and executed normally, so you can use any Forth code:
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 } .
{ kick snd } { 0.5 gain } { 0.3 verb } .
```
This compiles to exactly the same thing as:
```forth
kick s 0.5 gain 0.3 verb .
kick snd 0.5 gain 0.3 verb .
```
They can help readability in dense one-liners but have no semantic meaning.

4
docs/forth/control_flow.md
View File

@@ -112,7 +112,7 @@ Reads naturally: "c3 or c5, depending on the coin."
```forth
( 0.8 gain ) ( 0.3 gain ) fill ifelse
tri s c4 note 0.2 decay .
tri snd c4 note 0.2 decay .
```
Loud during fills, quiet otherwise.
@@ -123,7 +123,7 @@ Choose the nth quotation from a list. The index is 0-based:
```forth
( c4 ) ( e4 ) ( g4 ) ( b4 ) 0 3 rand select
note sine s 0.5 decay .
note sine snd 0.5 decay .
```
Four notes of a major seventh chord picked randomly. Note that this is unnecessarily complex :)

26
docs/forth/cycling.md
View File

@@ -9,13 +9,13 @@ 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 s . ;; 60, 64, 67, 60, 64, 67, ...
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 s . ;; kick on even iterations, snare on odd
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.
@@ -25,8 +25,8 @@ The distinction matters when patterns have different lengths or when multiple st
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 s . ;; ping-pong by step runs
60 64 67 72 4 pbounce note sine s . ;; ping-pong by pattern iteration
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`.
@@ -36,7 +36,7 @@ Same `runs` vs `iter` split as `cycle` / `pcycle`.
Uniform random selection:
```forth
kick snare hat 3 choose s . ;; random drum hit each time
kick snare hat 3 choose snd . ;; random drum hit each time
```
Unlike the cycling words, `choose` is nondeterministic — every evaluation picks independently.
@@ -46,7 +46,7 @@ Unlike the cycling words, `choose` is nondeterministic — every evaluation pick
Weighted random. Push value/weight pairs, then the count:
```forth
kick 0.5 snare 0.3 hat 0.2 3 wchoose s .
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.
@@ -56,8 +56,8 @@ Kick plays 50% of the time, snare 30%, hat 20%. Weights are normalized automatic
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 s . ;; step number picks the note
[ c4 e4 g4 ] iter index note sine s . ;; pattern iteration picks the note
[ 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.
@@ -67,9 +67,9 @@ This is useful when you want full control over which value is selected, driven b
All these words take a count argument `n`. Square brackets compute that count for you:
```forth
[ 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 .
[ 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.
@@ -80,7 +80,7 @@ When any of these words selects a quotation, it executes it instead of pushing i
```forth
[ ( c4 note ) ( e4 note ) ( g4 note ) ] cycle
sine s .
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.
@@ -88,5 +88,5 @@ On the first run the quotation `( c4 note )` executes, setting the note to C4. N
This works with all selection words. Mix plain values and quotations freely:
```forth
[ ( hat s 0.3 gain . ) ( snare s . ) ( kick s . ) ] choose
[ ( hat snd 0.3 gain . ) ( snare snd . ) ( kick snd . ) ] choose
```

8
docs/forth/definitions.md
View File

@@ -24,7 +24,7 @@ When you define a word in one step, it becomes available to all other steps. Thi
Step 0:
```forth
: bass "saw" s 0.8 gain 800 lpf ;
: bass "saw" snd 0.8 gain 800 lpf ;
```
Step 4:
@@ -75,7 +75,7 @@ This only affects words you defined with `:` ... `;`. Built-in words cannot be f
**Synth definitions** save you from repeating sound design:
```forth
: pad "sine" s 0.3 gain 2 attack 0.5 verb ;
: pad "sine" snd 0.3 gain 2 attack 0.5 verb ;
```
**Transpositions** and musical helpers:
@@ -90,8 +90,8 @@ This only affects words you defined with `:` ... `;`. Built-in words cannot be f
A word can contain `.` to emit sounds directly:
```forth
: kick "kick" s . ;
: hat "hat" s 0.4 gain . ;
: kick "kick" snd . ;
: hat "hat" snd 0.4 gain . ;
```
Then a step becomes trivial:

2
docs/forth/dictionary.md
View File

@@ -33,4 +33,4 @@ Each word entry shows:
- **Description**: What the word does
- **Example**: How to use it
Press `/` to search across all words. The search matches word names, aliases, and descriptions. Press `Esc` to clear and return to browsing. Use the dictionary while writing scripts to check stack effects and study their behavior. Some words also come with shorter aliases (e.g., `sound` → `s`). You will learn aliases quite naturally, because aliases are usually reserved for very common words.
Press `/` to search across all words. The search matches word names, aliases, and descriptions. Press `Esc` to clear and return to browsing. Use the dictionary while writing scripts to check stack effects and study their behavior. Some words also come with shorter aliases (e.g., `sound` → `snd`). You will learn aliases quite naturally, because aliases are usually reserved for very common words.

34
docs/forth/oddities.md
View File

@@ -35,8 +35,8 @@ Cagire supports this syntax but also provides quotation-based conditionals:
The words `?` and `!?` execute a quotation based on a condition:
```forth
( "kick" s . ) coin ? ;; execute if coin is 1
( "snare" s . ) coin !? ;; execute if coin is 0
( "kick" snd . ) coin ? ;; execute if coin is 1
( "snare" snd . ) coin !? ;; execute if coin is 0
```
## Strings
@@ -56,7 +56,7 @@ Cagire has first-class strings:
This pushes a string value onto the stack. Strings are used for sound names, sample names, and variable keys. You often do not need quotes at all. Any unrecognized word becomes a string automatically:
```forth
kick s . ;; "kick" is not a word, so it becomes the string "kick"
kick snd . ;; "kick" is not a word, so it becomes the string "kick"
myweirdname ;; pushes "myweirdname" onto the stack
```
@@ -110,8 +110,8 @@ Cagire uses a quotation-based loop with `times`:
The loop counter is stored in the variable `i`, accessed with `@i`. This fits Cagire's style where control flow uses quotations.
```forth
4 ( @i 4 / at hat s . ) times ;; hat at 0, 0.25, 0.5, 0.75
4 ( c4 @i + note sine s . ) times ;; ascending notes
4 ( @i 4 / at hat snd . ) times ;; hat at 0, 0.25, 0.5, 0.75
4 ( c4 @i + note sine snd . ) times ;; ascending notes
```
For generating sequences without side effects, use `..` or `gen`:
@@ -155,11 +155,11 @@ These have no equivalent in classic Forth. They connect your script to the seque
Classic Forth is deterministic. Cagire has built-in randomness:
```forth
( "snare" s . ) 50 prob ;; 50% chance
( "clap" s . ) 0.25 chance ;; 25% chance
( "hat" s . ) often ;; 75% chance
( "rim" s . ) sometimes ;; 50% chance
( "tom" s . ) rarely ;; 25% chance
( "snare" snd . ) 50 prob ;; 50% chance
( "clap" snd . ) 0.25 chance ;; 25% chance
( "hat" snd . ) often ;; 75% chance
( "rim" snd . ) sometimes ;; 50% chance
( "tom" snd . ) rarely ;; 25% chance
```
These words take a quotation and execute it probabilistically.
@@ -169,9 +169,9 @@ These words take a quotation and execute it probabilistically.
Execute a quotation on specific iterations:
```forth
( "snare" s . ) 4 every ;; every 4th pattern iteration
( "hat" s . ) 3 8 bjork ;; Euclidean: 3 hits across 8 step runs
( "hat" s . ) 5 8 pbjork ;; Euclidean: 5 hits across 8 pattern iterations
( "snare" snd . ) 4 every ;; every 4th pattern iteration
( "hat" snd . ) 3 8 bjork ;; Euclidean: 3 hits across 8 step runs
( "hat" snd . ) 5 8 pbjork ;; Euclidean: 5 hits across 8 pattern iterations
```
`every` checks the pattern iteration count. On iteration 0, 4, 8, 12... the quotation runs. On all other iterations it is skipped.
@@ -183,13 +183,13 @@ Execute a quotation on specific iterations:
Parameter words like `note`, `freq`, and `gain` consume the entire stack. If you push multiple values before a param word, you get polyphony:
```forth
60 64 67 note sine s . ;; emits 3 voices with notes 60, 64, 67
60 64 67 note sine snd . ;; emits 3 voices with notes 60, 64, 67
```
This works for any param and for the sound word itself:
```forth
440 880 freq sine tri s . ;; 2 voices: sine at 440, tri at 880
440 880 freq sine tri snd . ;; 2 voices: sine at 440, tri at 880
```
When params have different lengths, shorter lists cycle:
@@ -197,7 +197,7 @@ When params have different lengths, shorter lists cycle:
```forth
60 64 67 note ;; 3 notes
0.5 1.0 gain ;; 2 gains (cycles: 0.5, 1.0, 0.5)
sine s . ;; emits 3 voices
sine snd . ;; emits 3 voices
```
Polyphony multiplies with `at` deltas:
@@ -205,7 +205,7 @@ Polyphony multiplies with `at` deltas:
```forth
0 0.5 at ;; 2 time points
60 64 note ;; 2 notes
sine s . ;; emits 4 voices (2 notes × 2 times)
sine snd . ;; emits 4 voices (2 notes × 2 times)
```
## Summary