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

[BREAKING] Feat: quotation is now using ()

Browse Source
This commit is contained in:
Raphaël Forment
2026-02-28 20:25:59 +01:00
parent ec98274dfe
commit 651ed1219d
24 changed files with 182 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/forth/oddities.md
View File

@@ -22,10 +22,10 @@ Everything after `;;` until the end of the line is ignored.
Classic Forth has no quotations. Code is not a value you can pass around.
Cagire has first-class quotations using curly braces:
Cagire has first-class quotations using parentheses:
```forth
{ dup + }
( dup + )
```
This pushes a block of code onto the stack. You can store it, pass it to other words, and execute it later. Quotations enable conditionals, probability, and cycling.
@@ -41,14 +41,14 @@ x 0 > IF 1 ELSE -1 THEN
Cagire supports this syntax but also provides quotation-based conditionals:
```forth
{ 1 } { -1 } x 0 > ifelse
( 1 ) ( -1 ) x 0 > ifelse
```
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" s . ) coin ? ;; execute if coin is 1
( "snare" s . ) coin !? ;; execute if coin is 0
```
## Strings
@@ -116,21 +116,21 @@ Classic Forth has `DO ... LOOP`:
Cagire uses a quotation-based loop with `times`:
```forth
4 { @i . } times ;; prints 0 1 2 3
4 ( @i . ) times ;; prints 0 1 2 3
```
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 s . ) times ;; hat at 0, 0.25, 0.5, 0.75
4 ( c4 @i + note sine s . ) times ;; ascending notes
```
For generating sequences without side effects, use `..` or `gen`:
```forth
1 5 .. ;; pushes 1 2 3 4 5
{ dup * } 4 gen ;; pushes 0 1 4 9 (squares)
( dup * ) 4 gen ;; pushes 0 1 4 9 (squares)
```
## The Command Register
@@ -167,11 +167,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" 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
```
These words take a quotation and execute it probabilistically.
@@ -181,9 +181,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" 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
```
`every` checks the pattern iteration count. On iteration 0, 4, 8, 12... the quotation runs. On all other iterations it is skipped.
@@ -203,7 +203,7 @@ Each time the step runs, a different note is selected. The `3` tells `cycle` how
You can also use quotations if you need to execute code:
```forth
{ c4 note } { e4 note } { g4 note } 3 cycle
( c4 note ) ( e4 note ) ( g4 note ) 3 cycle
```
When the selected value is a quotation, it gets executed. When it is a plain value, it gets pushed onto the stack.