Instruction set

data stack

dup            x — x x
over           x y — x y x
drop           x —
clear          xxx —
swap           x y — y x
nip            x y — y
tuck           x y — y x y
<rot           x y z — y z x
rot>           x y z — z x y

return stack

push           x — ; — x       put top of data stack on return stack
pop            — x ; x —       put top of return stack on data stack
i              — x             get top of return stack
j              — x             get 2nd of return stack
k              — x             get 3rd of return stack

arithmetic

+              x y — (x+y)
-              x y — (x-y)
*              x y — (x*y)
**             x y — (x**y)
/              x y — (x mod y) (x div y)
*/             x y z — (x*y/z)
1+             x — (x+1)
1-             x — (x-1)
neg            x — (-x)
abs            x — (x | -x)
min            x y — (x | y)
max            x y — (x | y)
mega           x — (x*1000000)
kilo           x — (x*1000)
milli          x — (x/1000)
micro          x — (x/1000000)

bitwise

and            x y — z         bitwise and
+or            x y — z         inclusive or
xor            x y — z         exclusive or
inv            x — y           biwise inverse
2*             x — y           lshift
3*             x — y           dup lshift add
4*             x — y           lshift lshift
5*             x — y           dup lshift lshift add
8*             x — y           lshift lshift lshift
10*            x — y           dup lshift lshift add lshift
16*            x — y           lshift lshift lshift lshift
2/             x — y           rshift
4/             x — y           rshift rshift 
8/             x — y           rshift rshift rshift
16/            x — y           rshift rshift rshift rshift
<<             x y — z         (x<<y)
>>             x y — z         (x>>y)
bswap          x — y           change endianness

comparison

0=             x — x           compare top to zero (cpu flag)
==             x y — x y       compare two numbers (cpu flag)
between        x y z — f       (x <= z <= y)

constant

nil            — 0
false          — 0
true           — -1

number

-1..9          — n             pre-defined small integers
f.00           x — y           convert integer to Q32.00 float
f.16           x — y           convert integer to Q16.16 float

memory

?              a — x           fetch
?+             a — a' x        fetch auto-increment
?-             a — a' x        fetch auto-decrement
?_             a —             fetch byte
?_+            a — a' x        fetch byte auto-increment
?_-            a — a' x        fetch byte auto-decrement
!              x a —           store
!_             x a —           store byte
+!             n a —           add n to content of a
1+!            a —             increment content of a
1-!            a —             decrement content of a
2?             a — x x         fetch pair
2!             x x a —         store pair
xchg           a b —           swap cell contents
,              x —             compile cell
,_             x —             compile byte
allot          n —             move compiler pointer by n bytes
zfill          n —             clear n cells with zeros
align          —               align compiler pointer (here)
aligned        a — a'          align address
cells          x — y           convert to bytes (n*4)
@              a n — a'        offset (4 * +)
1@             a — a'          next cell (4 +)
2@             a — a'          +2 cells (8 +)
3@             a — a'          +3 cells (12 +)
-1@            a — a'          previous cell (4 -)

word register

>a             a —             set address
a>             — a             get address
a++            —               auto-increment
a--            —               auto-decrement
a?             — x             fetch at address
a!             x —             store at address
a?+            — x             fetch auto-increment
a?-            — x             fetch auto-decrement
a!+            x —             store auto-increment
a!-            x —             store auto-decrement
a?@            n — x           fetch at index
a!@            x n —           store at index

byte register

>b             a —             set address
b>             — a             get address
b++            —               auto-increment
b--            —               auto-decrement
b?             — x             fetch at address
b!             x —             store at address
b?+            — x             fetch auto-increment
b?-            — x             fetch auto-decrement
b!+            x —             store auto-increment
b!-            x —             store auto-decrement
b?@            n — x           fetch at index
b!@            x n —           store at index

counter register

>c             x —             set value
c>             — x             get value
c++            —               auto-increment
c--            —               auto-decrement
c+!            n —             increment by n
c-!            n —             decrement by n
c=             x — x           compare to c

internal register

ip             — a             virtual instruction pointer
ds             — a             get base of data stack
d>             — a             get data stack pointer
>d             a —             set data stack pointer
d?@            n — x           fetch data stack at index n
rs             — a             get base of return stack
r>             — a             get return stack pointer
>r             a —             set return stack pointer
r?@            n — x           fetch return stack at index n

input / output

getchar        — c             get character (from stdin)
putchar        c —             print character (to stdout)
newline        —               print newline (13 10)
spaces         n —             print n blank characters (32)
print          a n —           print string
println        a n —           print string with newline
.$             a —             print counted string
.$0            a —             print null-terminated string
.              n —             print number using current radix
.d             n —             print number in decimal
.x             n —             print number in hexadecimal
.o             n —             print number in octal
.b             n —             print number in binary
.s             —               print data stack
deci           —               decimal input
hexa           —               hexadecimal input
octa           —               octal input
bina           —               binary input
.hexa          —               hexadecimal output
.deci          —               decimal output
.octa          —               octal output
.bina          —               binary output

conversion

#>$            n — a n         convert number to string
$>#            a n — n         convert string to number
#!             n —             set input radix
#?             — n             get input radix
.#!            n —             set output radix
.#?            — n             get output radix

define / search

order means search order, scope means definition scope

:              a n —           define symbol
;              —               end definition of symbol
{              —               duplicate order
}              —               drop order
>:             —               set order as scope
:>             — lt            get scope (lexicon token)
<:             a n —           search and rebind existing symbol
<;             xt —            bind latest symbol to execution token
native         xt —            define latest symbol as native and bind to token
marker         —               define a bookmark (compile code to restore state)
forget         a n —           remove a bookmark (execute code to restore state)
pointer        —               new variable (address)
constant       n —             new variable (value)
assign         n xt —          override value of constant
lexicon        —               new lexicon
global         —               set default lexicon as current
search         a n — st f      search in normal order
search_one     a n — st f      search in current lexicon
search_all     a n — st f      search in all lexicons
symbols        —               list symbols in normal order
symbols_one    —               list symbols in current lexicon (TODO)
symbols_all    —               list symbols in all lexicons (TODO)
core           —               reset search order
>order         lt —            set lexicon token as top of search order
order>         — lt            get top of search order as lexicon token
st>xt          st — xt         get execution token from search token
st>nt          st — nt         get name token from search token

compile

[              —               push compiler handler
]              —               drop compiler handler
load,          x —             compile load number (or address) instruction
call,          xt —            compile enter instruction
exit,          —               compile leave instruction

control

zero (0), not zero (1), signed (-), not signed (+), are cpu status flags.
op is an operation that updates cpu status flags (like 0=, ==, +, -, etc).

noop           —               no operation (do nothing)
^              —               leave
^^             —               yield
[^             —               branch always
[0             —               branch if not zero
[1             —               branch if zero
[0=            —               short for `op` [0
[1=            —               short for `op` [1
[==            —               short for == [0
>[0=           x —             short for `op` drop [0
>[1=           x —             short for `op` drop [1
>[==           x y — x         short for == drop [0
[-             —               branch if signed (negative)
[+             —               branch if not signed
][             —               else
]]             —               resolve branch
[[             n —             push n on return stack, start of loop
0]             —               decrement top of return stack, loop if not zero
-]             —               decrement top of return stack, loop if not signed
?]             —               loop until iterator returns zero
try            —               create execption context
catch          xt —            execute token
throw          n —             throw numbered exception (restore context)
repeat         xt n —          execute token n times
eval           a n —           evalute string
cdecl          xxx —           call c function
bye            —               exit program with code 0
exit           n —             exit program with code n

callback

cb#            — a             callback table (define with n @ !)
cb0            — a             pointer to 1st function
cb1            — a             pointer to 2nd function
cb2            — a             pointer to 3rd function
cb3            — a             pointer to 4th function

special

'name          — xt            get execution token

trace / debug

dump           a n —           print memory content (n cells)
.+             —               execution tracer on (symbol name, stack content)
.-             —               execution tracer off
.[             —               compilation tracer

variable

bp             — a             body variable
hp             — a             head variable
pp             — a             pad variable
here           — a             body value (bp ?)
latest         — a             head value (hp ?)
disk           — a             start of disk
pad            — a             start of temporary buffer
pad_cycle      —               check if pad nearly full (reset pp to origin)

string

"..."          — a n           new string (address length)
$              a n — a'        put counted string in pad
$?             a — a' n        get length of counted string
$!             a1 n a2 —       store counted string
$,             a1 n —          compile counted string
$+             a1 a2 — a       concatenate counted string
$0             a n — a'        put null terminated string in pad
$0?            a — a n         get length of null terminated string
$0!            a1 n a2 —       store null terminated string
$0,            a1 n —          compile null terminated string
$0+            a1 a2 — a       concatenate null terminated string
$$             a1 a2 n —       copy n characters from src to dest
$=             a1 a2 n — f     compare n characters between src and dest

comment

\              —               comment until end of line
(%             —               start multi-line comment
%)             —               end multi-line comment
(0             n —             execute if top of data stack is zero
(1             n —             execute if top of data stack is not zero
)(             —               else (execute or ignore)

task

task           xt —            create task (round-robin multitasking)
switch         —               remember ip, go to next task
suspend        —               rewind ip, go to next task
resume         xt —            restore suspended task (TODO task status flag)

hook

&in            — a             input converter
&out           — a             output converter
&unknown       — a             not_found routine
&set           xt —            push handler
&unset         xt —            drop handler

runtime

argc           — n             get number of command line arguments
argv           — a             address of first command line argument
os_name        — a             operating system name (null-terminated)

memory

maligned       n x — a         allocate memory with alignment x
malloc         n — a           allocate memory
mfree          h — f           free memory
mprot          p n a — 0|err   change memory protection

library

dlopen         a — h           open library
dlsym          h — a           get symbol
dlclose        h — f           close library

file

fexist         a — f           check if file exists
fcreate        a — h           create file
fopen          a — h           open file
fsize          h — n           size of file
fseek          m n h — n'      set file pointer offset
fread          n a h — n'      read n bytes from h to buffer a
fwrite         n a h — n'      write n bytes from buffer a to h
fflush         h — 0|eof       force unwritten data to update
fclose         h — f           close file
fileno         h — n           get file descriptor (fd) from h
fdelete        a — 0|err       delete file
include        a n —           open file, get size, allocate buffer
                               read file to buffer, close file
                               eval buffer, release buffer
.include       a n —           print file name during include

directory

opendir        a — h           open directory
readdir        h — 0|ent       directory entry
closedir       h — 0|err       close directory
dirname        — a             entry name
dirtype        — n             entry type (0 = file, 1 = directory)

command

shell          a n —           execute shell command
popen          a a — h         open pipe (mode command)
pclose         h — n           close pipe (returns exit code)

time

ticks          — n             get time in milleseconds
sleep          n —             wait n milliseconds