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

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:

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.