# 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) |

## 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.

## miscellaneous notes and stuff

### COMPILE,
this is an STC forth so when we compile a call we have to
write the bytes of a `call` in manually.
x86\_64 does not allow absolute jumps from an immediate address,
so a wonky but hopefully not too slow solution is to compile
`literal address → W` and then `call W`. It'll Be Fine?

- `mov r11, [cfa]` = `94 BB [CFA]`
- `call r11` = `41 FF D3`

### 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

## silly little plans

### in-forth assembler
this would reap the most benefits from STC.
probably look at dusk's assemblers for how it should look like
or liek something liek dusk's lib/bm?
idk something to do stuff Fast if u need. would be fun

### DOES>
ah yes, the infamous `DOES>`. i don't have a DOCOL segment so i'm not
sure how exactly to implement this?

https://news.ycombinator.com/item?id=44231594 top comment here discusses
the forth `<BUILDS` which i've never heard of elsewhere. in fact if i look up
`forth "<BUILDS"` on duckduckgo that link is the only result.
i debased myself and looked it up on google too, and found a few more results.
maybe i can do something with that because i like `DOES>` and i wanna use it

maybe this sucks shit but my idea is that i compile in a relative jmp with
`<BUILDS` and fill it in with `DOES>`

### PNO
'pictured numeric output'. its forth's numeric output functionality.
note that this forth doesn't have double numbers
(i don't think it's necessary, since cells are 64 bit)
so PNO works on single cell values.

## 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:

- 0: nothing.
- 1: stack underflow
- 2: word not found
- 3: compilation only
- 4: interpret only