# jewelforth

it's a subroutine threaded forth for linux x86\_64.
mostly made for personal stuff.
it does not conform to any standards, i just implement what i want.
if you use it and it breaks, too bad

public domain

## dictionary
the dictionary follows a fairly standard format.

| field | size | forth name |
| :---- | :--- | :--------- |
| link to previous | 8 bytes | LFA (link field address) |
| flag | 1 byte | FFA (flag field address) |
| string length | 2 bytes | NFA (name field address) |
| string | variable length | still NFA |
| code | variable length | CFA (code field address) |

## non-standard forth

this does not follow any standards. here are some things to keep in mind

- the string output word is called `say` instead of `type` (i may change this)
- `create` can't be used for arrays and stuff. use `make` instead
- `:noname` is called `:>` (based on duskos). it also just creates a word called `_` and pushes its xt to the stack
- an `include` discards the rest of the input line

## the one reserved register

the working stack pointer is `r14`.
the other registers are used as general purpose registers;
`r11` in particular is the standard register used in
compiling calls.

## Some Links

- jonesforth, public domain forth tutorial implementation which was significantly cribbed from and studied: http://git.annexia.org/?p=jonesforth.git;a=tree
- jonesforth nasm port: http://ratfactor.com/repos/nasmjf/
- pforth, also public domain, alsos useful for Yoinking and Sploinking stuff: https://github.com/philburk/pforth
- starting forth part 1: http://www.bradrodriguez.com/papers/moving1.htm
- page describing `<BUILDS`: https://amforth.sourceforge.net/TG/recipes/Builds.html
- page describing pictured numeric output: http://www.jimbrooks.org/web/forth/forthPicturedNumericOutput.php

## error codes
in order to have Good Error Handling anywhere, the error handler's xt
is stored in the `handler` variable and is then called by loading its value
and `execute`ing it. the actual description of the error comes from the
`error` variable (in case the stack is fucked)

the error codes are:

- 1: stack underflow
- 2: word not found
- 3: compilation only
- 4: interpret only
- 5: includes too recursed

## TODO

- testing
- `DEPTH`
- more terminal control words
- `s\"`
- `DO` + `LOOP`
- `<BUILDS` and `DOES>`
- better documentation?
- turnkey executable generation from current dict?