From 8f76c163e577393bda45d9c98745bb4670f27f10 Mon Sep 17 00:00:00 2001 From: kitty Date: Sat, 21 Mar 2026 01:30:36 +1100 Subject: quite a lot the documentation descriptions Leave a Lot to be Desired --- readme.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 16 deletions(-) (limited to 'readme.md') diff --git a/readme.md b/readme.md index 4613d21..b3eefce 100644 --- a/readme.md +++ b/readme.md @@ -10,6 +10,7 @@ sanctuary is a 64-bit subroutine threaded forth for amd64 linux systems. - `u`: unsigned integer - `?`: boolean flag - `xt`: execution token +- `ht`: header token - `""`: string in input buffer - `|`: 'or' @@ -31,15 +32,12 @@ have a closing bracket: ). ### `(0handler) ( -- )` the very early error handler, which simply quits the program. -### `(execute) ( a -- )` -call the function at the address. - -### `(header) ( a u -- xt )` +### `(header) ( a u -- ht )` create a dictionary header for a word named the provided string. this word does not set the code field. -this word returns an incompleted xt and does not update latest. +this word does not update latest. -### `* ( u1 u2 -- u)` +### `* ( u1 u2 -- u )` multiply u1 and u2. ### `*/mod ( n1 n2 n3 -- n4 n5 )` @@ -98,22 +96,34 @@ return true if n1 is less than or equal to n2. ### `<> ( n1 n2 -- ? )` return true if n1 and n2 are not equal. +### ` ( n1 n2 -- ? )` return true if n1 is greater than n2. ### `>= ( n1 n2 -- ? )` return true if n1 is greater than or equal to n2. -### `>body ( xt -- a )` -yield the code field of xt. +### `>body ( ht -- xt )` +yield the code field of header token. ### `>in ( -- a )` variable containing the index of the first unparsed character in the input buffer. +### `>mark ( -- a )` +mark the source of a forward branch. + ### `>r ( u -- ) ( R: -- u )` move a value from the working stack to the return stack. +### `>resolve ( a -- )` +mark the destination of a forward branch. + ### `?branch ( -- )` compile into user memory an incomplete conditional branch. if the value on the stack is zero the branch is taken. @@ -153,6 +163,12 @@ duplicate the two topmost values on the stack. call the error handler (the address of which is in the variable `handler`) +### `again ( -- ) IMMEDIATE` +complete an infinite loop began by the word `begin`. + +### `allot ( u -- )` +reserve u bytes of user memory. + ### `and ( u1 u2 -- u )` perform bitwise AND on u1 and u2. @@ -160,6 +176,10 @@ perform bitwise AND on u1 and u2. a variable containing the current numeric input/output base. by default this is 10. +### `begin ( -- ) IMMEDIATE` +mark the beginning of a begin-again, begin-until, +or begin-while-repeat loop. + ### `binary ( -- )` set current base to binary. @@ -196,6 +216,9 @@ bytes are copied in high memory to low memory order. ### `d, ( n -- )` write a 32 bit value to user memory and increment the user memory pointer. +### `d! ( u a -- )` +store the 32 bit value u into the memory address a. + ### `decimal ( -- )` set current base to decimal. @@ -214,6 +237,11 @@ remove the value at the top of the stack. ### `dup ( u -- u u )` duplicate the value at the top of the stack. +### `else ( -- ) IMMEDIATE` +update the current if statement to branch here +when the flag is false, +and skip to `then` if the corresponding `if` was true. + ### `executable ( a u -- )` marks the u bytes starting at address a as executable. this is used primarily to mark the program break, @@ -222,11 +250,11 @@ which is used as the user memory space. ### `execute ( xt -- )` call the word xt. -### `find ( a u -- a u 0 | xt -1 )` +### `find ( a u -- a u 0 | a -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. +its link field address is returned along with the true flag. ### `grow ( u -- )` grows, and marks as executable, the user memory space by u bytes. @@ -240,11 +268,15 @@ yields the address of the first available byte in user memory. ### `hex ( -- )` set current base to hexadecimal. +### `if ( ? -- ) IMMEDIATE` +if the flag is true, execute the following if statement, +terminated by `else` or `then`. + ### `immediate ( -- )` mark the most recently defined word as immediate. -### `immediate? ( xt -- ? )` -true if xt is marked immediate, false otherwise. +### `immediate? ( ht -- ? )` +true if ht is marked immediate, false otherwise. ### `interpret ( -- )` interprets the contents of the terminal input buffer @@ -265,9 +297,15 @@ convert given string into a number along with a flag. if parsing a number fails then 0 (false) is returned and no number is provided. +### `octal ( -- )` +set current base to octal. + ### `or ( u1 u2 -- u )` perform bitwise OR on u1 and u2. +### `over ( u1 u2 -- u1 u2 u1 )` +copy the second-highest value on the stack and move it to the top of the stack. + ### `parse ( "name" c -- a u )` parse one word from the input buffer, separated by a newline or the character c, @@ -285,6 +323,9 @@ move a value from the return stack to the working stack. ### `rdrop ( R: u -- )` remove the value at the top of the return stack. +### `repeat ( -- ) IMMEDIATE` +in a begin-while-repeat loop, loop back to the condition. + ### `rot ( u1 u2 u3 -- u2 u3 u1 )` rotate the top three values on the stack so that the third highest value is moved to the top. @@ -318,17 +359,21 @@ perform the syscall with the id in `rax`, taking three parameters placed in `rdi`, `rsi` and `rdx`, and push the value of the `rax` register to the stack. +### `then ( -- ) IMMEDIATE` +conclude an if statement. + ### `tib ( -- a )` a variable containing the address of the current input buffer. ### `type ( a u -- )` write u characters at a to output. -### `octal ( -- )` -set current base to octal. +### `until ( ? -- ) IMMEDIATE` +if the given flag is true, loop back to `begin`. -### `over ( u1 u2 -- u1 u2 u1 )` -copy the second-highest value on the stack and move it to the top of the stack. +### `while ( ? -- ) IMMEDIATE` +if given flag is true, continue the current begin-while-repeat loop, +otherwise branch to after. ### `xor ( u1 u2 -- u )` perform bitwise XOR on u1 and u2. -- cgit v1.2.3