119 lines
1.8 KiB
Markdown
119 lines
1.8 KiB
Markdown
# The Stack
|
|
|
|
Forth is a stack-based language. Instead of variables and expressions, you push values onto a stack and use words that consume and produce values.
|
|
|
|
## How It Works
|
|
|
|
The stack is a last-in, first-out (LIFO) structure. Values you type get pushed on top. Words pop values off and push results back.
|
|
|
|
```
|
|
3 4 +
|
|
```
|
|
|
|
Step by step:
|
|
1. `3` → push 3 onto stack: `[3]`
|
|
2. `4` → push 4 onto stack: `[3, 4]`
|
|
3. `+` → pop two values, add them, push result: `[7]`
|
|
|
|
## Values
|
|
|
|
Three types can live on the stack:
|
|
|
|
- **Integers**: `42`, `-7`, `0`
|
|
- **Floats**: `3.14`, `0.5`, `-1.0`
|
|
- **Strings**: `"kick"`, `"hello"`
|
|
|
|
## Stack Notation
|
|
|
|
Documentation uses stack effect notation:
|
|
|
|
```
|
|
( before -- after )
|
|
```
|
|
|
|
For example, `+` has effect `( a b -- sum )` meaning it takes two values and leaves one.
|
|
|
|
## Core Words
|
|
|
|
### dup
|
|
|
|
Duplicate the top value.
|
|
|
|
```
|
|
3 dup ( 3 3 )
|
|
```
|
|
|
|
### drop
|
|
|
|
Discard the top value.
|
|
|
|
```
|
|
3 4 drop ( 3 )
|
|
```
|
|
|
|
### swap
|
|
|
|
Swap the top two values.
|
|
|
|
```
|
|
3 4 swap ( 4 3 )
|
|
```
|
|
|
|
### over
|
|
|
|
Copy the second value to the top.
|
|
|
|
```
|
|
3 4 over ( 3 4 3 )
|
|
```
|
|
|
|
### rot
|
|
|
|
Rotate the top three values.
|
|
|
|
```
|
|
1 2 3 rot ( 2 3 1 )
|
|
```
|
|
|
|
### nip
|
|
|
|
Drop the second value.
|
|
|
|
```
|
|
3 4 nip ( 4 )
|
|
```
|
|
|
|
### tuck
|
|
|
|
Copy top value below second.
|
|
|
|
```
|
|
3 4 tuck ( 4 3 4 )
|
|
```
|
|
|
|
## Examples
|
|
|
|
Build a chord by duplicating and adding:
|
|
|
|
```
|
|
60 dup 4 + swap 7 + ( 64 67 60 )
|
|
```
|
|
|
|
Use `over` to keep a base value:
|
|
|
|
```
|
|
c4 over M3 swap P5 ( e4 g4 c4 )
|
|
```
|
|
|
|
## Words
|
|
|
|
| Word | Stack | Description |
|
|
|------|-------|-------------|
|
|
| `dup` | (a -- a a) | Duplicate top |
|
|
| `drop` | (a --) | Discard top |
|
|
| `swap` | (a b -- b a) | Swap top two |
|
|
| `over` | (a b -- a b a) | Copy second to top |
|
|
| `rot` | (a b c -- b c a) | Rotate three |
|
|
| `nip` | (a b -- b) | Drop second |
|
|
| `tuck` | (a b -- b a b) | Copy top below second |
|