# lang/forth

Interpret ANS Forth-style programs from ZuzuScript.

This trial distribution provides a pure-Zuzu Forth interpreter intended
for embedding Forth snippets and small scripts. It implements a practical
ANS Forth Core-style surface: data and return stacks, dictionary lookup,
colon definitions, variables, constants, values, memory cells, arithmetic,
comparisons, output words, string literals, base switching, and structured
control flow for definitions.

The distribution contains:

- `modules/lang/forth.zzm`: tokenizer, system object, dictionary, and
  interpreter.
- `scripts/forth.zzs`: command-line Forth runner.
- `tests/lang/forth.zzs`: interpreter and tokenizer tests.
- `tests/runner.zzs`: author-only command-line runner test.

The distribution is licensed under the Artistic License 1.0 or the GNU
General Public License version 2. See `LICENCE`.

## Module API

```zzs
from lang/forth import forth, forth_system;

say( forth(": square dup * ; 9 square .") );  // 81 

let system := forth_system();
system.evaluate("variable x 41 x ! x @ 1+ .");
say( system.output() );  // 42 
```

`forth(source, options?)` evaluates `source` in a new `ForthSystem` and
returns captured output. `options{output_callback}` may be a function
called with each output string fragment, and `options{source_name}` is
used in diagnostics.

`forth_system(options?)` returns a fresh `ForthSystem` with the standard
dictionary installed.

`parse_forth(source, source_name?)` tokenizes source into `ForthToken`
objects and understands Forth comments, `."..."`, `S"..."`, `C"..."`, and
`ABORT"..."` string forms.

## Language Support

The initial dictionary includes:

- stack words such as `DROP`, `DUP`, `?DUP`, `SWAP`, `OVER`, `ROT`,
  `-ROT`, `NIP`, `TUCK`, `DEPTH`, `2DROP`, `2DUP`, `2OVER`, and `2SWAP`;
- return-stack words `>R`, `R>`, and `R@`;
- arithmetic and comparison words including `+`, `-`, `*`, `/`, `MOD`,
  `/MOD`, `1+`, `1-`, `2*`, `2/`, `NEGATE`, `ABS`, `MIN`, `MAX`, `=`,
  `<>`, `<`, `>`, `<=`, `>=`, `0=`, `0<`, `0>`, and `WITHIN`;
- logical flag words `AND`, `OR`, `XOR`, and `INVERT`;
- output words `.`, `.S`, `EMIT`, `CR`, `SPACE`, `SPACES`, and `TYPE`;
- memory words `VARIABLE`, `CONSTANT`, `VALUE`, `TO`, `!`, `@`, `+!`,
  `C!`, `C@`, `HERE`, `ALLOT`, `,`, `CELLS`, `CELL+`, `CHARS`, and
  `CHAR+`;
- base words `DECIMAL`, `HEX`, and `BASE`;
- colon definitions with `IF`, `ELSE`, `THEN`, `BEGIN`, `UNTIL`, `AGAIN`,
  `WHILE`, `REPEAT`, `DO`, `LOOP`, `+LOOP`, `I`, `J`, and `LEAVE`.

This is an ANS Forth-oriented hosted interpreter, not a native Forth
system. Addresses are managed cell indexes inside the interpreter, and
implementation-defined native behaviours are intentionally not exposed.

## Runner

`scripts/forth.zzs` is executable:

```sh
forth.zzs hello.fs
forth.zzs -e ': square dup * ; 9 square .'
forth.zzs program.fs > output.txt
```

Options:

- `-e, --eval SOURCE`: run source supplied on the command line.
- `-o, --output FILE`: write output to a file instead of STDOUT.
- `-h, --help`: show usage.
