| Class Name | Stack | Usage |
| .word | a -- | At compile time, compile a call to the word. At interpret time, execute the word. |
| .macro | a -- | Execute the word. The word may compile code or add data to the heap based on any form of state. |
| .data | a -- a | At compile time, lay down code to return the address of a data element. At interpret time, return the address of the data. |
| .inline | a -- | At compile time copy the first instruction of the word's default definition into the target word. At interpret time, execute the word. If revectored, use .word semantics. |
| Location | Description |
| 0 | Holds the address of the previous entry. Set to 0 if there are no previous entries. |
| 1 | Holds the class identifier of the word. |
| 2 | Holds the address that the definition starts at. |
| 3 .... n | String holding the name of the word. One character per cell, ending with a numeric value of 0. |
| Name | Data Stack | Address Stack | Description |
| here | -- a | -- | Return the address of the top of the heap |
| , | n -- | -- | Write a cell to the top of the heap; increase heap pointer. |
| ] | -- | -- | Turn compiler on |
| create | "name" -- | -- | Create a new dictionary entry with a class of data. |
| : | "name" -- | -- | Create a new dictionary entry with a class of word and call ]. |
| macro | "name" -- | -- | Create a new dictionary entry with a class of macro and call ]. |
| cr | -- | -- | Move the text cursor to the start of the next line |
| emit | n -- | -- | Display a character |
| home | -- | -- | Position the text cursor to the top left corner of the screen |
| type | $ptr -- | -- | Display a string |
| words | -- | -- | Display a list of all named words |
| save | -- | -- | Save the image |
| clear | -- | -- | Clear the display |
| key | -- n | -- | Read a value from the keyboard |
| accept | delim -- | -- | Read a string delimited by delim into the tib. |
| dup | n -- n n | -- | Duplicates TOS |
| 1+ | x --y | -- | Increment TOS |
| 1- | x -- y | -- | Decrement TOS |
| swap | x y -- y x | -- | Exchange TOS and NOS |
| drop | x y -- x | -- | Drop TOS |
| and | x y -- z | -- | Bitwise AND |
| or | x y -- z | -- | Bitwise OR |
| xor | x y -- z | -- | Bitwise XOR |
| @ | a -- n | -- | Fetch a value from address |
| ! | n a -- | -- | Store a value to address |
| + | x y -- z | -- | Add two numbers |
| - | x y -- z | -- | Subtract two numbers |
| * | x y -- z | -- | Multiply two numbers |
| /mod | x y -- z q | -- | Divide and get remainder |
| << | x y -- z | -- | Bitwise left shift |
| >> | x y -- z | -- | Bitwise right shift |
| nip | x y -- y | -- | Drop NOS |
| over | x y -- x y x | -- | Put a copy of NOS on top of the stack |
| 2drop | x y -- | -- | Drop TOS and NOS |
| not | x -- y | -- | Same as -1 xor. |
| rot | x y z -- y z x | -- | Rotate top three items on the stack |
| -rot | x y z -- z x y | -- | Rotate top three items on stack twice |
| tuck | x y -- y x y | -- | Put a copy of TOS under NOS |
| 2dup | x y -- x y x y | -- | Duplicate both TOS and NOS |
| on | a -- | -- | Set an address to -1 |
| off | a -- | -- | Set an address to 0 |
| / | x y -- z | -- | Divide two numbers |
| mod | x y -- z | -- | Divide and get remainder only |
| neg | x -- y | -- | Invert the sign of a number |
| execute | a -- | -- a | Call a function at address |
| . | n -- | -- | Display a number |
| " | "string" -- a | -- | Parse for a string |
| compare | $ptr $ptr -- flag | -- | Compare two strings |
| in | p -- n | -- | Read a value from a port |
| out | n p -- | -- | Write a value to a port |
| wait | -- | -- | Wait for a hardware event |
| ' | "name" -- a | -- | Get the address of a named word |
| @+ | a -- a+1 n | -- | Fetch a value from address a, return the value n and increment the address by 1 |
| !+ | n a -- a+1 | -- | Store n into address a, increment the address by 1 |
| +! | n a -- | -- | Add n to the value at address a, storing the results in a. |
| -! | n a -- | -- | Subtract n from the value at address a, storing the results in a. |
| :is | a xt -- | -- | Assign vector at xt to address a |
| :devector | xt -- | -- | Remove the vector from xt |
| is | a "name" -- | -- | Set vector name to address a. |
| devector | "name" -- | -- | Restore a vector to its default state. |
| compile | a -- | -- | Compile a call to address |
| literal, | n -- | -- | Compile a value as a literal |
| redraw | -- | -- | Update the display |
| getLength | $ptr -- n | -- | Get the length of a string |
| tempString | $ptr -- $ptr2 | -- | Mark a string as temporary |
| keepString | $ptr -- $ptr2 | -- | Mark a string as permanent |
| bye | -- | -- | Shutdown Ngaro VM |
| (remap-keys) | n -- n | -- | Vector which allows replacing one key value with another. |
| .word | a -- | -- | Class handler for normal words. (Class id = 1) |
| .macro | a -- | -- | Class handler for macros. (Class id = 2) |
| .data | a -- a | -- | Class handler for data structures. (Class id = 3) |
| .inline | a -- | -- | Class handler for inline words (Class id = 4) |
| with-class | a n -- | -- | Class dispatcher. N is the class id. |
| boot | -- | -- | Hook for custom startup code for turnkey applications. |
| depth | -- n | -- | Return the current depth of the data stack |
| reset | ... -- | -- | Remove all items on the data stack |
| notfound | -- | -- | Handler called when a word is not found |
| s" | "string" -- a | -- | Compile a string into a definition |
| [ | -- | -- |
Turn the compiler off |
| ; | -- | -- | End a definition |
| ;; | -- | -- | Compile an exit point into a definition |
| =if | x y -- | -- | Compare two number for equality. Jump to then if condition not met. |
| >if | x y -- | -- | Compare two number for greater than. Jump to then if condition not met. |
| <if | x y -- | -- | Compare two number for less than. Jump to then if condition not met. |
| !if | x y -- | -- | Compare two number for inequality. Jump to then if condition not met. |
| then | -- | -- | End a conditional |
| repeat | -- | -- | Begin an unconditional loop |
| again | -- | -- | Close an unconditional loop. Branch back to previous repeat. |
| 0; | n -- n -- n | -- | Exit a word if TOS is 0. If 0, drops TOS. Otherwise leaves TOS alone. |
| ( | "... )"-- | -- | Start a comment. |
| push | n -- | -- n | Push TOS to TORS. |
| pop | -- n | n -- | Pop TORS back to TOS |
| vector | -- | -- | Make a word a vector. Must be the first word in the definition. |
| for | n -- | -- a | Start a counted loop |
| next | -- n -- | a -- | End a counted loop. Decreases counter by 1. If counter is 0, exit the loop. Otherwise jump back to for. Drops the counter on exiting. |
| ['] | "name" -- a | -- | Get the address of a word. |
| d->class | d -- a | -- | Dictionary: Get class slot |
| d->xt | d -- a | -- | Dictionary: Get XT slot |
| d->name | d -- a | -- | Dictionary: Get name slot |
| tx | -- a | -- | Text X coordinate (graphics mode) |
| ty | -- a | -- | Text Y coordinate (graphics mode) |
| last | -- a | -- | Pointer to the most recent dictionary entry |
| compiler | -- a | -- | Holds compiler state |
| tib | -- a | -- | Pointer to the text input buffer |
| update | -- a | -- | Variable telling Retro to force a screen update. |
| fb | -- a | -- | Address of framebuffer |
| fw | -- a | -- | Width of framebuffer |
| fh | -- a | -- | Height of framebuffer |
| #mem | -- a | -- | Amount of memory |
| Word | Stack | Description |
| last | -- a | Pointer to the most recent dictionary entry |
| init-chain | -- a | Pointer to the most recent entry in the initialization chain |
| dup | x -- x x | Duplicates TOS |
| 1+ | x -- y | Increment TOS |
| 1- | x -- y | Decrement TOS |
| swap | x y -- y x | Exchange TOS and NOS |
| drop | x -- | Drop TOS |
| and | x y -- z | Bitwise AND |
| or | x y -- z | Bitwise OR |
| xor | x y -- z | Bitwise XOR |
| @ | a -- n | Fetch data from memory |
| ! | n a -- | Store data to memory |
| + | x y -- z | Add |
| - | x y -- z | Subtract |
| * | x y -- z | Multiply |
| /mod | x y -- z n | Divide and get remainder |
| << | x y -- z | Bitwise left shift |
| >> | x y -- z | Bitwise right shift |
| out | x y -- | Send a value to a port |
| in | x -- n | Read a value from a port |
| wait | -- | Wait for an input event |
| nip | x y -- y | Drop the NOS |
| over | x y -- x y x | Put a copy of NOS on the top of the stack |
| 2drop | x y -- | Drop TOS and NOS |
| rot | x y z -- y z x | Rotate the top three values on the stack |
| -rot | x y z -- z x y | Rotate the top three values on the stack twice |
| tuck | x y -- y x y | Put a copy of TOS under the NOS |
| 2dup | x y -- x y x y | Duplicate TOS and NOS |
| on | a -- | Turn a variable on (set to -1) |
| off | a -- | Turn a variable off (set to 0) |
| / | x y -- z | Divide |
| mod | x y -- z | Get remainder only |
| neg | x -- y | Negate TOS |
| execute | a -- | Execute the code at address a |
| @+ | a -- a+1 n | Fetch a value from address a, return the value n and increment the address by 1 |
| !+ | n a -- a+1 | Store n into address a, increment the address by 1 |
| +! | n a -- | Add n to the value at address a, storing the results in a. |
| -! | n a -- | Subtract n from the value at address a, storing the results in a. |
| tx | -- a | Text X coordinate (for framebuffer) |
| ty | -- a | Text Y coordinate (for framebuffer) |
| fb | -- a | Holds the address of the framebuffer |
| update | -- a | Enable/Disable video update (used by redraw) |
| redraw | -- | Force video update (for framebuffer) |
| fb:cr | -- | Move cursor to the next line (for framebuffer) |
| move | -- | Move the cursor by one character (for framebuffer) |
| fb:emit | n -- | Display a character (for framebuffer) |
| fb:home | -- | Reset TX and TY to top-left corner of the display. This is used by fb:clear |
| (type) | a0 -- a1 | Internal loop for type |
| type | a -- | Display a string |
| (clear) | -- | Internal loop for fb:clear (for framebuffer) |
| fb:clear | -- | Clear the screen (for framebuffer) |
| tty:emit | c -- | Display a character (for tty) |
| tty:cr | -- | Move the cursor to the next line (for tty) |
| tty:home | -- | Move the cursor to the top-left corner of the display (for tty) |
| tty:clear | -- | Clear the screen (for tty) |
| emit | c -- | Display a character |
| cr | -- | Move the cursor to the next line |
| clear | -- | Clear the display |
| home | -- | Move the cursor to the top-left corner of the display |
| save | -- | Save the image |
| bye | -- | Shutdown RETRO |
| words | -- | Display a list of all defined words |
| tib | -- a | Text Input Buffer |
| >in | -- a | Pointer into the tib |
| break-char | -- a | Holds the character used as a delimiter by accept. |
| (remap-keys) | -- | Hook to remap key values before they can be processed. Called by key right before returning the value. |
| key | -- n | Read a single keypress |
| >tib | n -- | Add a character to the tib |
| ++ | -- | Increment >in |
| (eat-leading) | -- | Eat leading keystrokes matching break-char. This is used by accept to ignore extra spaces at the start of a token. |
| (accept) | -- c | Internal loop used by accept. |
| accept | c -- | Read a string delimited by c. Modifies break-char. |
| state | -- a | Compiler state (can be either on or off) |
| heap | -- a | Current memory location to compile code and/or data to |
| compiling? | -- | Exit the word if the compiler state is true. |
| t-here | -- a | Return the current memory location |
| t-, | n -- | Compile a value into the current memory location |
| t-] | -- | Start the compiler |
| t-[ | -- | Suspend the compiler |
| t-;; | -- | Compile a ; instruction |
| t-; | -- | Compile a ; instruction and stop compiling |
| ($,) | a0 -- a1 | Internal loop used by $ |
| $ | a -- | Compile a string into the definitions |
| create | "name" -- | Create a new dictionary entry |
| (:) | -- | Common code for t-: and t-macro: |
| t-: | "name" -- | Start a new definition (word class) |
| t-macro: | "name" -- | Start a new definition (macro class) |
| t-( | "comment)" -- | Start a comment |
| t-push | n -- | Compile a push instruction |
| t-pop | -- n | Compile a pop instruction |
| $flag | -- a | Flag used by various string words |
| n=n | x y -- | Sets $flag to 0 if the values do not match |
| get-set | a0 a1 -- x y | Get values from two strings |
| next-set | a0 a1 -- a2 a3 | Increment two string pointers |
| (skim) | a0 a1 -- a2 a3 | Internal loop used by compare |
| compare | a1 a2 -- f | Compare two strings |
| (strlen) | -- | Internal loop used by getLength |
| getLength | -- | Get the length of a string |
| STRINGS | -- a | Starting address for the permanent string buffer |
| SAFE | -- a | Used during creation of temporary strings. On invoking " this points to the temporary string buffer. It is incremented for each character in the string. |
| LATEST | -- a | Start address of the most recent permanent string |
| (reset-$) | -- | Reset SAFE to the start of the temporary string buffer |
| (next) | -- | Increment SAFE |
| (copy) | a0 -- a1 | Copy a string into the temporary string buffer. |
| tempString | a0 -- a1 | Move a string to the temporary buffer |
| keepString | a0 -- a1 | Move a string to the permanent string buffer |
| t-" | "text" -- a | Get a string (interpret) |
| t-s" | "text" -- a | Get a string (compiler) and compile a pointer to it into the current defintion |
| #value | -- a | Internal value used for numeric words |
| #flag | -- a | Internal value used for numeric words |
| num | -- a | Internal value used for numeric words |
| num-ok | -- a | Internal value used for numeric words |
| negate? | -- a | Internal value used for numeric words |
| isdigit? | c -- f | Returns true if the character is a number. False if not. |
| char>digit | c -- n | Convert an ASCII character to a number |
| digit>char | n -- c | Convert a number to an ASCII character |
| isNegative? | a -- a+1 | Sets negate? to true if the number starts with a - character |
| (convert) | a0 -- a1 | Internal loop used by >number |
| >number | a -- n | Convert a string to a number |
| (isnumber) | a0 -- a1 | Internal loop used by isnumber? |
| isnumber? | a -- f | Returns true if string a is a valid number. |
| number>digits | n -- c0 ... cN | Break a number into individual characters. Used by . |
| digits>screen | c0 ... cN -- | Display a sequence of characters. Used by . |
| . | n -- | Display a number |
| found | -- a | Search result flag |
| which | -- a | Pointer to the found dictionary header |
| d->class | d -- a | Dictionary: Get Class slot |
| d->xt | d -- a | Dictionary: Get XT slot |
| d->name | d -- a | Dictionary: Get Name slot |
| (search) | -- | Internal loop used by search |
| search | a -- | Search for a word in the dictionary. |
| t-=if | x y -- | Compile a !jump instruction |
| t->if | x y -- | Compile a <jump instruction |
| t-<if | x y -- | Compile a >jump instruction |
| t-!if | x y -- | Compile a =jump instruction |
| t-then | -- | Patch the last conditional jump |
| t-repeat | -- | Start an unconditional loop |
| t-again | -- | Close an unconditional loop |
| t-0; | n -- n || n -- | Compile a 0; instruction. Leaves n alone if n is non-zero, otherwise drops n. |
| t-' | "name" -- a | Return the address of a word. If the word is not found, display an error and return 0. |
| t-['] | "name" -- a | Get the address of a word and compile it into the current definition. |
| devector | "name" -- | Remve the vector from name |
| is | a "name" -- | Assign the vector named name to address a |
| :devector | xt -- | Remove the vector from xt |
| :is | a xt -- | Assign vector at xt to address a |
| compile | xt -- | Compile a call to xt into the current definition |
| literal, | n -- | Compile n into the current definition as a literal |
| depth | -- n | Return the current depth of the data stack |
| reset | ... -- | Remove all items on the data stack |
| cold | -- a | Variable determining whether or not to display the copytag. |
| copytag | -- a | Copyright / Bootup message. Used only by runonce. |
| boot | -- | Hook for turnkey applications. |
| runonce | -- | Runs when the image is loaded. Performs initializations, then calls boot. |
| nomatch | -- a | String to display when no match could be found. Used by notfound. |
| okmsg | -- a | String to display as the "ok" prompt |
| .word | a -- | Word class handler |
| .macro | a -- | Macro class handler |
| .data | n -- n | Data class handler |
| .inline | a -- | Inline class handler |
| with-class | a -- | Execute an XT with the proper class handler |
| notfound | -- | Called when a lookup fails. Will display the nomatch string. |
| find-word | -- | Search for a word in the dictionary. Used by listen. |
| find-number | -- | Attempt to convert a token to a number. Used by listen. |
| ok | -- | Display the ok prompt if not compiling. Used by listen. |
| listen | -- | The main interpreter loop |
| initialize | -- | Run each word in the initialization chain once |
| fw | -- a | Height of framebuffer |
| fh | -- a | Width of framebuffer |
| #mem | -- a | Amount of memory |
| Opcode | Name | Data Stack | Address Stack | Description |
| 0 | NOP | -- | -- | Does nothing. Used for padding |
| 1 |value| | LIT | -- n | -- | Push a literal to the stack |
| 2 | DUP | n -- n n | -- | Duplicate the top value on the stack |
| 3 | DROP | n -- | -- | Drop the top value off the stack |
| 4 | SWAP | x y -- y x | -- | Exchange the top and second item on the stack |
| 5 | PUSH | n -- | -- n | Push the top item on the data stack to the address stack |
| 6 | POP | -- n | n -- | Pop the top item on the address stack to the data stack |
| 7 |address| | CALL | -- | -- a | Call a subroutine |
| 8 |address| | JUMP | -- | -- | Branch unconditionally to a memory location |
| 9 | ; | -- | a -- | Return from a subroutine |
| 10 |address| | >JUMP | -- | -- | Conditional branch, if NOS is greater than TOS |
| 11 |address| | <JUMP | -- | -- | Conditional branch, if NOS is less than TOS |
| 12 |address| | !JUMP | -- | -- | Conditional branch, if NOS is not equal to TOS |
| 13 |address| | =JUMP | -- | -- | Conditional branch, if NOS is equal to TOS |
| 14 | @ | a -- n | -- | Fetch the value at the memory address in TOS |
| 15 | ! | n a -- | -- | Store the value on the second stack location to the address in TOS |
| 16 | + | x y -- z | -- | Add the top two values on the stack |
| 17 | - | x y -- z | -- | Subtract the top two values on the stack |
| 18 | * | x y -- z | -- | Multiply the top two values on the stack |
| 19 | /MOD | x y -- z q | -- | Divide and get the remainder of the top two values on the stack |
| 20 | AND | x y -- z | -- | Bitwise AND operation |
| 21 | OR | x y -- z | -- | Bitwise OR operation |
| 22 | XOR | x y -- z | -- | Bitwise XOR operation |
| 23 | << | x y -- z | -- | Shift bits left |
| 24 | >> | x y -- z | -- | Shift bits right |
| 25 | 0; | n -- n n -- | -- | Exit a subroutine and drop TOS if TOS is 0. If TOS is not 0, do nothing. |
| 26 | 1+ | x -- y | -- | Increase the value on the stack by 1 |
| 27 | 1- | x -- y | -- | Decrease the value on the stack by 1 |
| 28 | IN | p -- n | -- | Read a value from a port |
| 29 | OUT | n p -- | -- | Send a value to a port |
| 30 | WAIT | -- | -- | Wait for the hardware to process an event. |
| Word | Stack | Description |
| heap | -- a | Pointer into the target memory |
| origin | -- a | Address of the target memory |
| fid | -- n | File ID |
| log | -- n | Memory Map / Build Log File ID |
| lastop | -- n | Last compiled opcode (for optimizer) |
| $log | "string" -- | Append "string" to the map/log file |
| \n | -- | Append a newline to the map/log file |
| , | n -- | Compile a value into the target memory |
| vm: | n "name" -- | Create a new word that compiles its value into target memory |
| here | -- a | Return the value of the current location in the target memory. |
| nop, | -- | Ngaro Instruction |
| lit, | -- | Ngaro Instruction |
| dup, | -- | Ngaro Instruction |
| drop, | -- | Ngaro Instruction |
| swap, | -- | Ngaro Instruction |
| push, | -- | Ngaro Instruction |
| pop, | -- | Ngaro Instruction |
| call, | -- | Ngaro Instruction |
| jump, | -- | Ngaro Instruction |
| ; | -- | Ngaro Instruction |
| >jump, | -- | Ngaro Instruction |
| <jump, | -- | Ngaro Instruction |
| !jump, | -- | Ngaro Instruction |
| =jump, | -- | Ngaro Instruction |
| @, | -- | Ngaro Instruction |
| !, | -- | Ngaro Instruction |
| +, | -- | Ngaro Instruction |
| -, | -- | Ngaro Instruction |
| *, | -- | Ngaro Instruction |
| /mod, | -- | Ngaro Instruction |
| and, | -- | Ngaro Instruction |
| or, | -- | Ngaro Instruction |
| xor, | -- | Ngaro Instruction |
| <<, | -- | Ngaro Instruction |
| >>, | -- | Ngaro Instruction |
| 0; | -- | Ngaro Instruction |
| 1+, | -- | Ngaro Instruction |
| 1-, | -- | Ngaro Instruction |
| in, | -- | Ngaro Instruction |
| out, | -- | Ngaro Instruction |
| wait, | -- | Ngaro Instruction |
| halt, | -- | Bogus instruction which causes Ngaro to cease execution of the image. |
| begin | "name" -- | Begin compilation of target image |
| end | -- | End compilation of target image |
| main: | -- | Main entry point in target |
| label: | "label" -- | Create a label |
| # | n -- | Compile a number into the image (lit, followed by a value) |
| $, | string-ptr -- | Compile a string into the image |
| conditional | -- a | Common code for conditionals |
| =if | -- | Conditional (equality) |
| <if | -- | Conditional (less than) |
| >if | -- | Conditional (greater than) |
| !if | -- | Conditional (inequality) |
| then | a -- | Close the previous conditional |
| : | "name" -- | Begin a new word in the target image |
| ' | "name" -- | Get the address of a word in the target image. Compiles the address into the target image. |
| link | -- n | Link to the latest entry in the target dictionary |
| #entries | -- n | Number of entries in the target dictionary |
| word: | a "name" -- | Create a new word in the target dictionary using the word class |
| macro: | a "name" -- | Create a new word in the target dictionary using the macro class |
| data: | a "name" -- | Create a new word in the target dictionary using the data class |
| inline: | a "name" -- | Create a new word in the target dictionary using the inline class |
| repeat | -- a | Begin an unconditional loop |
| again | a -- | End an unconditional loop |
| variable: | n "name" -- | Create a variable with an initial value of n |
| variable | "name" -- | Create a variable with an initial value of 0 |
| patch-dictionary | -- | Adjust
the marked memory location to point to the most recent dictionary
entry. This should come after all of the initial entries are created. |
| mark-dictionary | -- | Mark the current location in the target image as the pointer to the most recent dictionary entry. |
| init-link | -- n | Link to the latest entry in the initialization chain |
| mark-init-chain | -- | Mark the current location in the target image as the pointer to the most recent item in the initialization chain. |
| patch-init-chain | -- | Adjust
the marked memory location to point to the most recent entry in the
initialization chain. This should come after all items have been added
to the chain. |
| +init | a -- | Add the word at address a to the initialization chain |
| TCE | -- n | Number of tail calls eliminated |
| +TCE | -- | Increment the number of tail calls elimintated |
| ; | -- | Extend the ; instruction to eliminate tail calls. |
| cross-summary | -- | Display a summary of the cross-compilation results. This does some very basic sanity checks (stack depth, etc) |
| MODULE: | "name" -- | Specify the name of a module |
| AUTHOR: | "name" -- | Specify the author of a module |
| NOTES: | "text" -- | Provide notes about a module |
Preparation:
The build script will display a menu of targets that can be built. Make a selection and press enter.
Prerequisites:
Process: