Function | Stack | Notes | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
1+ | n-n | Increment TOS by 1 [1] | ||||||||||
1- | n-n | Decrement TOS by 1 [1] | ||||||||||
swap | xy-yx | Exchange positions of TOS and NOS [1] | ||||||||||
drop | n- | Drop TOS from the stack [1] | ||||||||||
and | xy-n | Bitwise AND [1] | ||||||||||
or | xy-n | Bitwise OR [1] | ||||||||||
xor | xy-n | Bitwise XOR [1] | ||||||||||
@ | a-n | Fetch a value from a memory location [1] | ||||||||||
! | na- | Store a value to a memory location [1] | ||||||||||
+ | xy-n | Add two values (x+y) [1] | ||||||||||
- | xy-n | Subtract two values (x-y) [1] | ||||||||||
* | xy-n | Multiply two values (x*y) [1] | ||||||||||
/mod | xy-rq | Divide and Remainder [1]
This performs symmetric division
|
||||||||||
<< | xy-n | Shift bits left (x<<y) [1] [2] | ||||||||||
>> | xy-n | Shift bits right (x>>y) [1] [2] | ||||||||||
tib | -a | Returns address of text input buffer | ||||||||||
dup | n-nn | Duplicate TOS [1] | ||||||||||
in | p-n | Read a value from an I/O port [1] | ||||||||||
out | np- | Write a value to an I/O port [1] | ||||||||||
accept | c- | Read a string, ending with the specified character. The string is returned in tib | ||||||||||
here | -a | Next free address in heap | ||||||||||
, | n- | Place TOS here and increment heap by 1 | ||||||||||
create | "- | Parse for a name and call header | ||||||||||
: | "- | Calls create, changes class to .word, and turns compiler on. | ||||||||||
header | $- | Given a name, create a new header with a class of .data | ||||||||||
cr | - | Display a newline character | ||||||||||
putc | c- | Display a character | ||||||||||
remapKeys | c-c | Remap one ASCII value to another | ||||||||||
<puts> | $- | Helper; default way to display strings | ||||||||||
over | xy-xyx | Place a copy of NOS over TOS | ||||||||||
quote | -a | Helper function for quotations | ||||||||||
]] | - | Turn compiler on | ||||||||||
not | x-y | Same as -1 xor; invert TOS and subtract 1. | ||||||||||
on | a- | Set a variable to -1 (true) | ||||||||||
off | a- | Set a variable to 0 (false) | ||||||||||
/ | xy-q | Divide two numbers (x/y) | ||||||||||
mod | xy-r | Modulus of two numbers (x%y) | ||||||||||
negate | x-y | Invert sign of TOS | ||||||||||
do | a- | Call a function by address | ||||||||||
numbers | -a | Function returning address of string containing all valid numeric characters | ||||||||||
wait | - | Wait for an I/O event | ||||||||||
' | "-a | Interpret time: return the address ("xt") of a name | ||||||||||
@+ | a-ac | Fetch a value from an address, return the next address and the value | ||||||||||
!+ | ca-a | Store a value to an address, return next address | ||||||||||
keepString | a-a | Move the string to a permanent location | ||||||||||
getLength | a-n | Return the length of a string | ||||||||||
withLength | a-an | Same as dup getLength | ||||||||||
withClass | ac- | Execute a function via the specified class handler | ||||||||||
.word | a- | Class for normal functions | ||||||||||
.macro | a- | Class for immediate functions | ||||||||||
.data | a- | Class for data (variables, literals, etc) | ||||||||||
d->class | a-a | Given a dictionary header, return the address of the class handler. Use @ to get the class handler. | ||||||||||
d->xt | a-a | Given a dictionary header, return the address of the function start ("xt"). Use @ to get the actual xt. | ||||||||||
d->name | a-a | Given a dictionary header, return the address of the name. This is the actual start of the name. | ||||||||||
boot | - | Called when the image first loads; use for custom startup routines | ||||||||||
toNumber | $-n | Convert a string to a number | ||||||||||
isNumber? | $-f | See if a string is a valid number in the current base | ||||||||||
ok | - | Displays the "ok" prompt | ||||||||||
listen | - | Top level interpreter. Reads and process input. | ||||||||||
getc | -c | Read a keypress and return the ASCII value on the stack | ||||||||||
find | $-af | Search for a name in the dictionary. Returns a dictionary header and a flag | ||||||||||
notFound | - | Called when a name is not found. Calls <notFound> and displays an error message if necessary | ||||||||||
<notFound> | -f | Called by notFound; hook for custom error handling. Used by the prefix system. Returns a flag of 0 if the error is cleared, or -1 if not | ||||||||||
puts | $- | Display a string [3] | ||||||||||
compare | $$-f | Compare two strings for equality | ||||||||||
redraw | - | Update the display. Can be disabled temporarily by update | ||||||||||
if | fqq- | Execute first quote if flag is true, second if false | ||||||||||
ifTrue | fq- | Execute quote if flag is true | ||||||||||
ifFalse | fq- | Execute quote if flag is false | ||||||||||
dip | nq-n | Call a quote while temporarily hiding the top item on the stack | ||||||||||
sip | nq-n | Call a quote with an item on the stack, restoring that item after the quote returns | ||||||||||
= | xy-f | Compare two values for equality | ||||||||||
<> | xy-f | Compare two values for inequality | ||||||||||
< | xy-f | Compare two values for less than | ||||||||||
> | xy-f | Compare two values for greater than | ||||||||||
<= | xy-f | Compare for less than or equal to | ||||||||||
>= | xy-f | Compare for greater than or equal to | ||||||||||
; | - | Compile an exit into a function and stop the compiler | ||||||||||
;; | - | Compile an exit into a function, but do not stop compilation | ||||||||||
repeat | - | Start an unconditional loop | ||||||||||
again | - | Jump to the code following the most recent repeat | ||||||||||
0; | n-n
or
n-
|
If TOS is not zero, do nothing
If TOS is zero, drop TOS and exit the
function
|
||||||||||
push | n- | Push a value to the address stack | ||||||||||
pop | -n | Pop a value off the address stack | ||||||||||
( | "- | Parse for ) and ignore everything it reads | ||||||||||
[ | - | Start a quote (code block) | ||||||||||
] | -a | End a quote (code block) | ||||||||||
[[ | - | Turn compiler off | ||||||||||
last | -a | Variable; pointer to most recent dictionary header | ||||||||||
compiler | -a | Variable; holds compiler state | ||||||||||
fb | -a | Variable; Is canvas present? [4] | ||||||||||
fw | -a | Variable; Framebuffer width [4] | ||||||||||
fh | -a | Variable; Framebuffer height [4] | ||||||||||
memory | -a | Variable; Holds amount of memory provided by the VM [4] | ||||||||||
cw | -a | Variable; Console width [4] | ||||||||||
ch | -a | Variable; Console height [4] | ||||||||||
heap | -a | Variable; Pointer to current free location in heap | ||||||||||
which | -a | Variable; Holds pointer to most recently looked up header | ||||||||||
remapping | -a | Variable; indicates whether CR, LF, and TAB should be treated as whitespace | ||||||||||
eatLeading? | -a | Variable; indicates whether accept should ignore leading delimiters | ||||||||||
base | -a | Variable; holds current base for numeric conversion and display | ||||||||||
update | -a | Variable; flag indicating whether or not redraw should update the display | ||||||||||
version | -$ | String holding version information | ||||||||||
build | -$ | String holding a build identifier | ||||||||||
tabAsWhitespace | -a | Variable; treat tab as whitespace? | ||||||||||
?dup | n-n
n-nn
|
Duplicate TOS if non-zero. If zero, leave alone | ||||||||||
nip | xy-y | Drop the NOS from the stack | ||||||||||
rot | xyz-yzx | Rotate the top three values on the stack | ||||||||||
tuck | xy-yxy | Put a copy of TOS under NOS | ||||||||||
+! | na- | Add value to value at address | ||||||||||
-! | na- | Subtract value from value at address | ||||||||||
++ | a- | Increment variable by 1 | ||||||||||
-- | a- | Decrement variable by 1 | ||||||||||
HEADERS | -n | Returns number of private headers permitted | ||||||||||
{{ | - | Start a namespace (private portion) | ||||||||||
---reveal--- | - | Switch to public portion of a namespace | ||||||||||
}} | - | Close a namespace, sealing off private symbols | ||||||||||
:devector | a- | Restore a function to its original state | ||||||||||
:is | aa- | Alter a function to point to a new function | ||||||||||
devector | "- | Same as :devector, but parses for name of function | ||||||||||
is | a"- | Same as :is, but parses for name of function | ||||||||||
default: | "- | Compile call to default definition of a function, ignoring any revectoring | ||||||||||
d' | "-a | Parse for a name and return the dictionary header corresponding to it | ||||||||||
xt->d | a-d | Given an address, return the corresponding dictionary header or 0 if not found | ||||||||||
:hide | a- | Remove a name from a dictionary. Specify the address of a function. Used by hide | ||||||||||
hide | "- | Remove a name from the dictionary | ||||||||||
reclass | a- | Change class of most recent function to specified class | ||||||||||
reclass: | a"- | Same as reclass, but parse for function to change class of | ||||||||||
__& | a-a | Prefix; returns address of a variable or function | ||||||||||
__@ | a-n | Prefix; execute function or data element and fetch from addres returned | ||||||||||
__! | na- | Prefix; execute function or data element and store value to address returned | ||||||||||
__+ | na- | Prefix; execute function or data element and add value to value at address returned | ||||||||||
__- | na- | Prefix; execute function or data element and subtract value from value at address returned | ||||||||||
__2 | a- | Prefix; execute function twice | ||||||||||
.primitive | a- | Class for functions corresponding to VM opcodes; used for simple optimizations | ||||||||||
.compiler | a- | Class for functions that can only be used inside a definition | ||||||||||
immediate | - | Set the most recent function to .macro class | ||||||||||
compile-only | "- | Set the most recent function to .compiler class | ||||||||||
` | "- | Either execute a function, or compile the xt and a call to the corresponding class handler. This will also work with numbers | ||||||||||
jump: | "- | Compile a jump to another function | ||||||||||
[] | - | Empty quote | ||||||||||
while | q- | Execute quote until quote returns a flag of 0 | ||||||||||
until | q- | Execute quote until quote returns a flag of -1 | ||||||||||
curry | nq-q | 5 [ . ] = [ 5 [ . ] do ] | ||||||||||
take | qq-q | 5 [ . ] = [ [ . ] do 5 ] | ||||||||||
bi | xqq- | Apply each quote to a copy of x | ||||||||||
bi* | xyqq- | Apply q1 to x and q2 to y | ||||||||||
bi@ | xyq- | Apply q to x and y | ||||||||||
tri | xqqq- | Apply each quote to a copy of x | ||||||||||
tri* | xyzqqq- | Apply q1 to x, q2 to y, and q3 to z | ||||||||||
tri@ | xyzq- | Apply q to x, y, and z | ||||||||||
cons | ab-q | Create a quote returning two data elements | ||||||||||
preserve | aq- | Given a variable (a) and a quote (q),
preserve the contents of (a) while executing
the quote, and restore the original contents
of (a) after execution completes.
(a) is removed from the stack before (q) is
executed.
|
||||||||||
when | nqq-n | Execute q1, with a copy of n on the stack. If q1 returns a true flag, run q2 and exit the caller. If not, discard q2 and return to the caller. q2 is permitted to discard n, which will alter the stack effect. | ||||||||||
whend | nqq-? | Execute q1, with a copy of n on the stack. If q1 returns a true flag, drop n, run q2 and exit the caller. If not, discard q2 and return to the caller. | ||||||||||
times | nq- | Run quote (n) times | ||||||||||
iterd | nq- | Run quote (n) times and push counter to stack each time. Counts down. | ||||||||||
iter | nq- | Run quote (n) times and push counter to stack each time. Counts up. | ||||||||||
<each@> | ...t- | Hook into each@ for adding additional types | ||||||||||
each@ | ...t- | Supercombinator for applying quote to each item in various data structures. Also provide on the stack:
For LIST, l should be a variable pointing to the actual list. The quote is given the address of the current element each time it is invoked. |
||||||||||
copy | aan- | Copy n values from source (a1) to dest (a2) | ||||||||||
fill | ann- | Fill (n2) memory locations starting at (a) with value (n1) | ||||||||||
ahead | -a | Used in conditionals; compiles a branch to be patched in later | ||||||||||
if; | f- | Exit function if TOS is a non-zero flag | ||||||||||
within | xlu-f | Is (x) within lower (l) and upper (u) bounds? | ||||||||||
variable: | n"- | Create a new variable with an initial value | ||||||||||
variable | "- | Create a new variable with an initial value of 0 | ||||||||||
constant | n"- | Create a numeric constant | ||||||||||
string | $"- | Create a string constant | ||||||||||
allot | n- | Allocate space in the heap | ||||||||||
elements | n"- | Create a series of variables | ||||||||||
decimal | - | Switch base to 10 | ||||||||||
hex | - | Switch base to 16 | ||||||||||
octal | - | Switch base to 8 | ||||||||||
binary | - | Switch base to 2 | ||||||||||
toString | n-$ | Convert a number into a string | ||||||||||
clear | - | Clear the display | ||||||||||
space | - | Display a space character (ASCII 32) | ||||||||||
putn | n- | Display a number | ||||||||||
.parse | a- | Class for parsing prefixes | ||||||||||
parsing | - | Set most recent function to .parse class | ||||||||||
__$ | $-n | Prefix; treat number as hexadecimal (base 16) | ||||||||||
__# | $-n | Prefix; treat number as decimal (base 10) | ||||||||||
__% | $-n | Prefix; treat number as binary (base 2) | ||||||||||
__' | $-n | Return character following ' | ||||||||||
dicts | -a | Array; used by chained vocabularies and search order code | ||||||||||
%% | - | Close a vocabulary. Use with caution | ||||||||||
<%> | a- | Open a vocabulary. Use with caution | ||||||||||
.chain | a- | Class for vocabularies | ||||||||||
chain: | "- | Create a new vocabulary | ||||||||||
;chain | - | End a vocabulary | ||||||||||
:with | a- | Add a vocabulary to the search order (by pointer) | ||||||||||
with | "- | Add a vocabulary to the search order (parses for name) | ||||||||||
without | - | Remove a vocabulary from the search order | ||||||||||
global | - | Remove all vocabularies from the search order, leaving just the global dictionary | ||||||||||
findInChain | $a-df | Open a chain (using :with) and search for a name. Closes the chain when done. | ||||||||||
with| | "- | Open a series of vocabularies, ending when | is encountered | ||||||||||
rename: | a"- | Rename a function | ||||||||||
STRING-LENGTH | -n | Return the max length for a string | ||||||||||
STRING-BUFERS | -n | Return number of temporary string buffers | ||||||||||
tempString | a-a | Move a string to a temporary buffer | ||||||||||
__" | "-$ | Prefix; parse and return a string | ||||||||||
" | "-$ | Parse and return a string | ||||||||||
formatted | -a | Variable; toggles whether puts uses escape sequences or not | ||||||||||
depth | -n | Return number of items on stack | ||||||||||
reset | ...- | Remove all items from stack | ||||||||||
.s | - | Display all items on stack | ||||||||||
words | - | List all names in dictionary | ||||||||||
save | - | Save the image | ||||||||||
bye | - | Exit Retro | ||||||||||
getToken | "-$ | Read a string, stopping at first whitespace | ||||||||||
getNumber | "-n | Read a number from the input stream | ||||||||||
:include | $- | Include a file | ||||||||||
include | "- | Same as :include, but parse for file name | ||||||||||
time | -n | Return the current unix time | ||||||||||
delay | n- | Delay for (approximately) n seconds | ||||||||||
getEnv | a$- | Get a copy of environment variable $ in buffer | ||||||||||
later | - | Defer execution of caller until a later time | ||||||||||
__^ | "- | Allow direct access to functions in a chain | ||||||||||
needs | "- | Load a vocabulary from the library if it is not already loaded [5] | ||||||||||
doc{ | "- | Parse tokens up to }doc and ignore. This is intended as a means of embedding docs into libraries. | ||||||||||
variables| | "- | Create a series of variables |
Function | Stack | Notes |
---|---|---|
start | -a | Get starting address of buffer |
end | -a | Address at end of buffer |
add | c- | Add value to end of buffer |
get | -c | Read and remove value from buffer |
empty | - | Remove everything from the buffer |
size | -n | Number of values in buffer |
set | a- | Set buffer to memory address and empty it |
Function | Stack | Notes |
---|---|---|
search | $$-f | Search for a string (2) within a string (1); return string starting with substring |
findChar | $c-a | Search for a character within a string; return string starting at the character |
chop | $-$ | Return a new string, with the last byte removed |
getSubset | $nn-$ | Return a subset of ($) starting at (n1) with length of (n2) |
trimLeft | $-$ | Trim whitespace from left side of string |
trimRight | $-$ | Trim whitespace from right side of string |
append | $$-$ | Append second string to first |
appendChar | $c-$ | Append character to a string |
prepend | $$-$ | Append first string to second |
toLower | $-$ | Convert a string to all lower case |
toUpper | $-$ | Convert a string to all upper case |
reverse | $-$ | Reverse the characters in a string; returns a new string |
split | $n-$$ | Split a string into two parts |
splitAtChar | $c-$$ | Search for a character and return two strings (up to and including (c), and after ($2)) |
splitAtChar: | $"-$$ | Parse for a character and call splitAtChar |
Function | Stack | Notes |
---|---|---|
ARRAY | -n | Type constant for arrays |
BUFFER | -n | Type constant for buffers |
STRING | -n | Type constant for strings |
LIST | -n | Type constant for linked lists |
[1] | (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18) This corresponds to an Ngaro instruction. |
[2] | (1, 2) Shifting by a negative amount is undefined behavior. Don't do it. |
[3] | puts supports escape sequences which alter the stack usage. |
Sequence | Stack | Used For |
---|---|---|
%s | $- | Display a string |
%d | n- | Display a number (decimal) |
%x | n- | Display a number (hexadecimal) |
%o | n- | Display a number (octal) |
%c | c- | Display a character |
\n | - | Newline |
\' | - | Display a double quote (") |
\[ | - | Start an ANSI escape sequence |
[4] | (1, 2, 3, 4, 5, 6) These are updated each time the image is loaded. |
[5] | This parses for a vocabulary name, which should end in a single apostrophe. The apostrophe will be cut, and the a suffix of .rx added. The system will attempt to load the file from the library subdirectory in the current working directory. |