# About Forth

Forth is a _stack-based_ programming language created by Charles H. Moore in the early 1970s. It was designed with simplicity, directness, and interactive exploration in mind. Forth has been used for scientific work and embedded systems: it controlled telescopes and even ran on hardware aboard space missions. It evolved into many implementations targeting various architectures, but none of them really caught on. Nonetheless, the ideas behind Forth continue to attract people from very different, often unrelated fields. Today, Forth languages are used by hackers and artists for their unconventional nature. Forth is simple, direct, and beautiful to implement. Forth is an elegant, minimal language, easy to understand, extend, and tailor to a specific task. The Forth we use in Cagire is specialized in making live music. It is used as a DSL: a _Domain Specific Language_.

**TLDR:** Forth is a really nice language to play music with.

## Why Forth?

Most programming languages rely on a complex syntax of `variables`, `expressions` and `statements` like `x = 3 + 4` or `do_something(()=>bob(4))`. Forth works differently. It has almost no syntax at all. Instead, you push values onto a `stack` and apply `words` that transform them:

```forth
3 4 + print
```

The program above leaves the number `7` on the stack. There are no variables, no parentheses, no syntax to remember. You just end up with words and numbers separated by spaces. For live coding music, this directness is quite exciting. All you do is think in terms of transformations and add things to the stack: take a note, shift it up, add reverb, play it.

## The Stack

The stack is where values live. When you type a number, it goes on the stack. When you type a word, it usually takes values off and puts new ones back.

```forth
3 ;; stack: 3
4 ;; stack: 3 4
+ ;; stack: 7
print 
```

The stack is `last-in, first-out`. The most recent value is always on top. This means that it's often better to read Forth programs from right to left, bottom to top.

## Words

Everything in Forth is either a `number` or a `word`. Words are like functions but conceptually simpler. They have no arguments or return values in the traditional sense. They just manipulate the stack directly.

```forth
dup ;; duplicate the top value
drop ;; discard the top value
swap ;; swap the top two values
```

Words compose naturally on the stack. To double a number:

```forth
;; 3 3 +
3 dup + print
```

Forth has a large vocabulary, so Cagire includes a `Dictionary` directly in the application. You can also create your own words. They will work just like existing words. The only difference is that these words will not be included in the dictionary. There are good reasons to create new words on-the-fly:

- To make synth definitions.
- To abstract _some piece of code_ that you use frequently.
- To share data and processes between different steps.

## Values

Four basic types of values can live on the stack:

- **Integers**: `42`, `-7`, `0`
- **Floats**: `0.5`, `3.14`, `-1.0`
- **Strings**: `"kick"`, `"hello"`
- **Quotations**: `( dup + )` (code as data)

Floats can omit the leading zero: `.25` is the same as `0.25`, and `-.5` is `-0.5`.

Parentheses are used to "quote" a section of a program. The code inside does not run immediately — it is pushed onto the stack as a value. A quotation only runs when a consuming word decides to execute it. This is how conditionals and loops work:

```forth
( 60 note 0.3 verb ) 1 ?
```

Here `?` pops the quotation and the condition. The code inside runs only when the condition is truthy. Words like `?`, `!?`, `times`, `cycle`, `choose`, `ifelse`, `every`, `chance`, and `apply` all consume quotations this way.

Because parentheses defer execution, wrapping code in `( ... )` without a consuming word means it never runs. Quotations are transparent to sound and parameter words — they stay on the stack untouched. This is a useful trick for temporarily disabling part of a step:

```forth
( 0.5 gain )         ;; this quotation is ignored
"kick" sound
0.3 decay
.
```

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

Traditional Forth programs print text to a terminal. Cagire's Forth builds sound commands instead. This happens through an internal accumulator called the command register. The command register has two parts:
- a **sound name** (what instrument to play)
- a list of **parameters** (how to play it)

Three kinds of words interact with it:

```forth
kick sound      ;; sets the sound name
0.5 gain        ;; adds a parameter
.               ;; emits the command and clears the register
```

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:

```forth
"sine" sound
c4 note
0.5 gain
0.3 decay
0.4 verb
.
```

Each line adds something to the register. The final `.` triggers the sound. You can also write it all on one line:

```forth
"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" 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.
