# sanctuary forth (working title)

sanctuary forth is a 64-bit subroutine threaded forth system
for amd64 linux systems.

## stack effect notation

- `a`: memory address
- `c`: one byte value
- `n`: signed integer
- `u`: unsigned integer
- `?`: boolean flag
- `xt`: execution token
- `""`: string in input buffer
- `|`: 'or'

## Glossary

the following is a list of words available in this forth.

### `#tib   ( -- a )`
variable containing the amount of characters in the input buffer.

### `>body   ( xt -- a )`
yield the code field of xt.

### `>in   ( -- a )`
variable containing the index of the first unparsed character
in the input buffer.

### `brk@   ( -- a )`
yields current program break.

### `bye   ( -- )`
exits the forth system.

### `dp   ( -- a )`
a variable that contains the lowest free byte of memory in user memory.

### `dp0   ( -- )`
a variable that contains the first byte of user memory.

### `dp$   ( -- )`
a variable that contains the last available byte of user memory.

### `dup   ( u -- u u )`
duplicate the value at the top of the stack.

### `executable   ( a u -- )`
marks the u bytes starting at address a as executable.
this is used primarily to mark the program break,
which is used as the user memory space.

### `find   ( a u -- a u 0 | xt -1 )`
look in the dictionary for the word a (of u characters).
a zero is returned along with the original given string
if no word was found. if a word was found,
its xt is returned along with the true flag.

### `grow   ( u -- )`
grows the user memory space by u bytes.

### `here   ( -- a )`
yields the address of the first available byte in user memory.

### `immediate?   ( xt -- ? )`
true if xt is marked immediate, false otherwise.

### `interpret   ( -- )`
interprets the contents of the terminal input buffer
until it runs out.

### `latest   ( -- a )`
a variable containing the execution token of
the most recently created word.

### `literal   ( n -- ) IMMEDIATE COMPILE-ONLY`
compile a push of the literal value n into the currently compiling word.

### `number   ( a u -- n 0 | -1 )`
convert given string into a number along with a flag.
if parsing a number fails then -1 (false) is returned
and no number is provided.

### `parse   ( "name<c>" c -- a u )`
parse one word from the input buffer,
separated by a newline or the character c,
and return as a string.

### `parse-name   ( "<ws>name<ws>" -- a u )`
parse one whitespace-separated word from the input buffer,
and return as a string.
tabs (ascii 0x09), newlines (ascii 0x10), and spaces (ascii 0x20)
are considered whitespace.

### `state   ( -- a )`
a variable containing a boolean value.
if 0 (false), the system is in interpreting mode,
if -1 (true), the system is in compiling mode.

### `tib   ( -- a )`
a variable containing the address of the current input buffer.

### `type   ( a u -- )`
write u characters at a to output.

## dictionary format

note that the string length of one byte limits a word's name to 255 characters.

| field | size |
| :---- | :--- |
| link to previous word | 8 bytes |
| flag field | 1 byte |
| string length | 1 byte |
| string | <256 bytes |
| code | variable length |

## reserved registers

the register `r15` is reserved for the parameter stack pointer.

## differences from standard forth

for the most part this forth intends to be in line with standards
but it diverges in a few notable places:

- the most visally obvious one by far,
    this forth uses lower case word names for core words.
- `find` takes `a u` instead of a counted string,
    and does not return 1 for immediate words.