Instruction set

data stack

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

return stack

push        x — ; — x
pop         — x ; x —
i           — x        top of rs
j           — x        2nd of rs
k           — x        3rd of rs
quit        — ; xxx —

arithmetic

+           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)
kilo        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
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
==          x y — x y  compare two numbers

constant

nil         — 0
false       — 0
true        — -1
-1..9       — n        digits

pointer

?           a — x      fetch
!           x a —      store
,           x —        compile
?_          a —        fetch byte
!_          x a —      store byte
,_          x —        compile byte
+!          n a —      add n to content of a
cells       n — (n*4)  convert to bytes
allot       n —        move compiler pointer by n bytes
zfill       n —        clear n cells
aligned     a — a'     align address
align                  align compiler pointer (here)
@           a n — a'   offset (4 * +)
1@          a — a'     next cell (4 +)
-1@         a — a'     previous cell (4 -)

definition

:           a n —      add definition
;                      set definition length
::                     rebind latest definition
constant    n —        new value
pointer                new variable
lexicon     a n —      new dictionary
{                      enter scope
}                      leave scope
also                   add to search order
sans                   remove from search order
only                   reset search order
core                   core lexicon
user                   user lexicon
search      a n — st f search token and flag
lookup      xt — nt    name token or 0

compilation

[                      push compiler handler
]                      pop compiler handler
macro                  mark symbol immediate
load,       x —        compile load number/address
call,       xt —       compile enter routine
exit,                  compile leave routine

control

Note : zero, not zero, signed, not signed, are cpu status flags.

noop                   do nothing
^                      leave
^^                     yield
[^                     branch always
[0                     branch if not zero
[1                     branch if zero
[-                     branch if not signed
[+                     branch if signed
][                     else
]]                     resolve branch
0]                     decrement, loop if not zero
-]                     decrement, loop if not signed
?]                     loop until iterator returns zero
eval        a n —      evalute string
cdecl       xxx —      call c function
bye                    exit program
exit        n —        exit process with code n

task

task        xt —       create task (round-robin multitasking)
switch                 remember ip, go to next task
suspend                rewind ip, go to next task

special

'                      get execution token
~                      reverse semantics (execute/compile)

string

"..."       — a n      new string (address length)
$?          a — a n    of length prefixed string
$0?         a — a n    of null terminated string
$,          a n —      compile length prefixed string
$0,         a n —      compile null terminated string
$           a n — a'   compile length prefixed string in pad
$0          a n — a'   compile null terminated string in pad
$>          a1 a2 n —  copy n characters from src to dest

comment

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

debugging

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

variable

disk        — a        start of disk
here        — a        position of compiler pointer
last        — a        latest definition
pad         — a        temporary string buffer
word        — a        parsing word buffer
ip          — a        virtual instruction pointer

hook

&??         — a        pointer to not_found routine
&in         — a        pointer to input converter
&out        — a        pointer to output converter
&+          xt —       push handler
&-          xt —       drop handler
panic                  clear stacks, print error

word register

>a          a —        set address
a>          — a        get address
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?          — 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+          n —        increment by n
c-          n —        decrement by n
c=          x — x      compare top to c

internal register

ds          — a        get base of data stack
d>          — a        get data stack pointer
>d          a —        set data stack pointer
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

system

Notes on system-independent implementation.

input/output

keyhit      — f        true if stdin not empty else false
key         — c        get character
.           x —        print top using current radix
.h          x —        print top in hexadecimal
.d          x —        print top in decimal
..                     print stack
space                  print blank (32)
spaces      n —        print n blanks
emit        c —        print ascii character
type        a n —      print string
.eol                   print newline (13 10)
hexa                   hexadecimal input
deci                   decimal input
.hexa                  hexadecimal output
.deci                  decimal output

runtime

argc        — n        get number of command line arguments
argv        — a        address of command line arguments

library

dlopen      a — h      open library
dlsym       h — a      get symbol
dlclose     h — f      close library
dlerror     TODO       check library error

memory

malloc      n — h      allocate memory
mfree       h — f      free memory
mcode       n a — f    set protection to read/execute
mdata       n a — f    set protection to read/write
mpage+      a n —      add page of size n to list a
mpage-      a —        remove page from list a
mpage@      a n —      get nth page of list a

file

fexist      TODO       check file
fcreate     a — h      create file
fopen       a — h      open file
fsize       h — n      size of file
fseek       TODO       set file offset
fread       n a h — n' read n bytes in buffer a from h
fwrite      n a h — n' write n bytes in buffer a from h
fclose      h — f      close file
fdelete     TODO       delete file
ferror      TODO       check file error
include     a —        open file, get size, allocate buffer
                       read file to buffer, close file
                       eval buffer, release buffer

time

ticks       — n        milleseconds in clock
sleep       n —        wait n milliseconds