.. _RefCard:

Reference Card
==============

General
-------

AmForth is a 16bit ITC forth. It is almost compatible with
the forth standards from 1994 and 200x. It runs on the
bare metal controller with no further dependencies. 
The interpreter operates on whitespace delimited words.
The compiler is a single pass compiler that writes
directly to the flash based dictionary.

There are three distinct address spaces for flash, 
eeprom and RAM. Flash is addressed word wise (16 bits 
per address unit), RAM  and EEPROM is accessed byte 
wise (8bits per address unit). The standard return stack
has 40 cells, the data stack is limited by the available
RAM size.

Numbers can be prefixed by $ to indicate hexadecimal,
% for binary and \# for decimal numbers. A trailing
dot is used for double cell numbers.

Words not found here are not part of the compileable core
system. Their forth sources are in the :file:`/lib` directory,
usually named after the word name: e.g. :command:`2dup` is
defined in a file named :file:`2dup.frt`.


Arithmetics
-----------

* :command:`1-`
  ( n1 -- n2 )
  optimized decrement

* :command:`1+`
  ( n1|u1 -- n2|u2 )
  optimized increment

* :command:`2/`
  ( n1 -- n2 )
  arithmetic shift right

* :command:`2*`
  ( n1 -- n2 )
  arithmetic shift left, filling with zero

* :command:`abs`
  ( n1 -- u1 )
  get the absolute value

* :command:`><`
  ( n1 -- n2 )
  exchange the bytes of the TOS

* :command:`cell+`
  ( a-addr1 -- a-addr2 )
  add the size of an address-unit to a-addr1

* :command:`d2/`
  ( d1 -- d2 )
  shift a double cell value right

* :command:`d2*`
  ( d1 -- d2 )
  shift a double cell left

* :command:`dabs`
  ( d -- ud )
  double cell absolute value

* :command:`dinvert`
  ( d1 -- d2)
  invert all bits in the double cell value

* :command:`d-`
  ( d1 d2 -- d3 )
  subtract d2 from d1 

* :command:`dnegate`
  ( d1 -- d2 )
  double cell negation

* :command:`d+`
  ( d1 d2 -- d3)
  add 2 double cell values

* :command:`invert`
  ( n1 -- n2)
  1-complement of TOS

* :command:`log2`
  ( n1 -- n2 )
  logarithm to base 2 or highest set bitnumber

* :command:`lshift`
  ( n1 n2 -- n3)
  logically shift n1 left n2 times

* :command:`-`
  ( n1|u1 n2|u2 -- n3|u3 )
  subtract n2 from n1

* :command:`mod`
  ( n1 n2 -- n3)
  divide n1 by n2 giving the remainder n3

* :command:`m+`
  ( d1 n1 -- d2)
  add a number to a double cell

* :command:`m*`
  ( n1 n2 -- d)
  multiply 2 cells to a double cell

* :command:`+`
  ( n1 n2 -- n3)
  add n1 and n2

* :command:`+!`
  ( n a-addr -- )
  add n to content of RAM address a-addr

* :command:`popcnt`
  ( n1 -- n2 )
  count the Number of 1 bits (population count)

* :command:`rshift`
  ( n1 n2 -- n3 )
  shift n1 n2-times logically right

* :command:`/`
  ( n1 n2 -- n3)
  divide n1 by n2. giving the quotient

* :command:`/mod`
  ( n1 n2 -- rem quot)
  signed division n1/n2 with remainder and quotient

* :command:`*`
  ( n1 n2 -- n3 )
  multiply routine

* :command:`true`
  ( -- -1 )
  leaves the value -1 (true) on TOS

* :command:`ud/mod`
  ( d1 n -- rem ud2 )
  unsigned double cell division with remainder

* :command:`ud*`
  ( ud1 d2 -- ud3)
  multiply unsigned and double cells to unsigned double cell

* :command:`um/mod`
  ( ud u2 -- rem quot)
  unsigned division ud / u2 with remainder

* :command:`um*`
  ( u1 u2 -- d)
  multiply 2 unsigned cells to a double cell

* :command:`u/mod`
  (u1 u2 -- rem quot)
  unsigned division with remainder

* :command:`0`
  ( -- 0 )
  place a value 0 on TOS




Character IO
------------

* :command:`bl`
  ( -- 32 )
  put ascii code of the blank to the stack

* :command:`cr`
  ( -- )
  cause subsequent output appear at the beginning of the next line

* :command:`emit`
  ( c -- )
  fetch the emit vector and execute it. should emit a character from TOS

* :command:`emit?`
  ( -- f )
  fetch emit? vector and execute it. should return the ready-to-send condition

* :command:`key`
  ( -- c )
  fetch key vector and execute it, should leave a single character on TOS

* :command:`key?`
  ( -- f)
  fetch key? vector and execute it. should turn on key sender, if it is disabled/stopped

* :command:`space`
  ( -- )
  emits a space (bl)

* :command:`spaces`
  ( n -- )
  emits n space(s) (bl)

* :command:`type`
  ( addr n -- )
  print a RAM based string




Compare
-------

* :command:`d0>`
  ( d -- flag )
  compares if a double double cell number is greater 0

* :command:`d0<`
  ( d -- flag )
  compares if a double double cell number is less than 0

* :command:`=`
  ( n1 n2 -- flag )
  compares two values for equality

* :command:`>`
  ( n1 n2 -- flag )
  flag is true if n1 is greater than n2

* :command:`0>`
  ( n1 -- flag )
  true if n1 is greater than 0

* :command:`max`
  ( n1 n2 -- n1|n2 )
  compare two values, leave the bigger one

* :command:`min`
  ( n1 n2 -- n1|n2 )
  compare two values leave the smaller one

* :command:`<>`
  ( n1 n2 -- flag)
  true if n1 is not equal to n2

* :command:`0<>`
  ( n -- flag )
  true if n is not zero

* :command:`u>`
  ( u1 u2 -- flag )
  true if u1 > u2 (unsigned)

* :command:`u<`
  ( u1 u2 -- flasg)
  true if u1 < u2 (unsigned)

* :command:`within`
  ( n min max -- f)
  check if n is within min..max

* :command:`0=`
  ( n -- flag )
  compare with 0 (zero)

* :command:`0<`
  ( n1 -- flag)
  compare with zero




Compiler
--------

* :command:`2literal`
  ( -- x1 x2 )
  (C: x1 x2 -- )
  compile a cell pair literal in colon definitions

* :command:`again`
  ( -- )
  (C: dest -- )
  compile a jump back to dest

* :command:`ahead`
  ( f -- )
  (C: -- orig )
  do a unconditional branch

* :command:`\\`
  ( "ccc<eol>" -- )
  everything up to the end of the current line is a comment

* :command:`begin`
  ( -- )
  (C: -- dest )
  put the next location for a transfer of control onto the control flow stack

* :command:`[compile]`
  ( -- c )
  (C: "<space>name" -- )
  Append the compilation semantics of "name" to the dictionary, if any

* :command:`[']`
  ( -- xt )
  (C: "<space>name" -- )
  what ' does in the interpreter mode, do in colon definitions

* :command:`code`
  ( -- )
  (C: cchar -- )
  create named entry in the dictionary, XT is the data field

* :command:`:`
  ( -- )
  (C: "<spaces>name" -- )
  create a named entry in the dictionary, XT is DO_COLON

* :command:`:noname`
  ( -- xt )
  create an unnamed entry in the dictionary, XT is DO_COLON

* :command:`constant`
  ( -- x )
  (C: x "<spaces>name" -- )
  create a constant in the dictionary

* :command:`do`
  ( n1 n2 -- )
  (R: -- loop-sys )
  (C: -- do-sys )
  start do .. [+]loop

* :command:`(create)`
  ( --  )
  (C: "<spaces>name" -- )
  parse the input and create an empty vocabulary entry without XT and data field (PF)

* :command:`(create-in)`
  ( --  )
  (C: "<spaces>name" -- )
  parse the input and create an empty vocabulary entry without XT and data field (PF)

* :command:`does>`
  ( i*x -- j*y )
  (R: nest-sys1 -- )
  (C: colon-sys1 -- colon-sys2 )
  organize the XT replacement to call other colon code

* :command:`.''`
  ( -- )
  (C: "ccc<quote>" -- )
  compiles string into dictionary to be printed at runtime

* :command:`else`
  (C: orig1 -- orig2 )
  (C: orig1 -- orig2 )
  resolve the forward reference and place a new unresolved forward reference

* :command:`end-code`
  ( -- )
  finish a code definition

* :command:`exit`
  ( -- )
  (R: nest-sys -- )
  end of current colon word

* :command:`header`
  ( addr len wid -- nfa )
  creates the vocabulary header without XT and data field (PF) in the wordlist wid

* :command:`i`
  ( -- n )
  (R: loop-sys -- loop-sys)
  current loop counter

* :command:`i-cell+`
  ( addr -- addr' )
  skip to the next cell in flash

* :command:`if`
  ( f -- )
  (C: -- orig )
  start conditional branch

* :command:`immediate`
  ( -- )
  set immediate flag for the most recent word definition

* :command:`j`
  ( -- n )
  (R: loop-sys1 loop-sys2 -- loop-sys1 loop-sys2)
  loop counter of outer loop

* :command:`[`
  ( --  )
  enter interpreter mode

* :command:`leave`
  ( -- )
  (R: loop-sys -- )
  immediatly leave the current DO..LOOP

* :command:`literal`
  ( -- n )
  (C: n -- )
  compile a literal in colon defintions

* :command:`loop`
  (R: loop-sys -- )
  (R: loop-sys -- )
  (C: do-sys -- )
  compile (loop) and resolve the backward branch

* :command:`(`
  ( "ccc<paren>" -- )
  skip everything up to the closing bracket on the same line

* :command:`+loop`
  ( n -- )
  (R: loop-sys -- loop-sys| )
  (C: do-sys -- )
  compile (+loop) and resolve branches

* :command:`postpone`
  ( "<space>name" --  )
  Append the compilation semantics of "name" to the dictionary

* :command:`?do`
  ( n1|u1 n2|u2 -- )
  (C: -- do-sys)
  start a ?do .. [+]loop control structure

* :command:`?do`
  ( n1|u1 n2|u2 -- )
  (C: -- do-sys)
  start a ?do .. [+]loop control structure

* :command:`]`
  ( --  )
  enter compiler mode

* :command:`recurse`
  ( -- )
  compile the XT of the word currently being defined into the dictionary

* :command:`repeat`
  ( --  )
  (C: orig dest -- )
  continue execution at dest, resolve orig

* :command:`s,`
  ( addr len -- )
  compiles a string from RAM to Flash

* :command:`;`
  ( -- )
  finish colon defintion, compiles (exit) and returns to interpret state 

* :command:`s''`
  ( -- addr len)
  (C: <cchar> -- )
  compiles a string to flash, at runtime leaves ( -- flash-addr count) on stack

* :command:`then`
  ( -- )
  (C: orig -- )
  finish if

* :command:`unloop`
  ( -- )
  (R: loop-sys -- )
  remove loop-sys, exit the loop and continue execution after it

* :command:`until`
  ( f -- )
  (C: dest -- )
  finish begin with conditional branch, leaves the loop if true flag at runtime

* :command:`user`
  ( n cchar -- )
  create a dictionary entry for a user variable at offset n

* :command:`variable`
  ( cchar -- )
  create a dictionary entry for a variable and allocate 1 cell RAM

* :command:`while`
  ( f -- )
  (C: dest -- orig dest )
  at runtime skip until repeat if non-true

* :command:`wlscope`
  ( addr len -- addr' len' wid )
  dynamically place a word in a wordlist. The word name may be changed.




Conversion
----------

* :command:`s>d`
  ( n1 -- d1 )
  extend (signed) single cell value to double cell




Dictionary
----------

* :command:``
  ( n -- )
  compile 16 bit into flash at DP

* :command:`compile`
  ( -- )
  read the following cell from the dictionary and append it to the current dictionary position.

* :command:`create`
  ( -- a-addr )
  (C: "<spaces>name" -- )
  create a dictionary header. XT is (constant), with the address of the data field of name

* :command:`reveal`
  ( -- )
  makes an entry in a wordlist visible, if not already done.

* :command:`'`
  ( "<spaces>name" -- XT )
  search dictionary for name, return XT or throw an exception -13




Environment
-----------

* :command:`/hold`
  ( -- hldsize )
  size of the pictured numeric output buffer in bytes

* :command:`/pad`
  ( -- padsize )
  Size of the PAD buffer in bytes

* :command:`/user`
  ( -- usersize )
  size of the USER area in bytes

* :command:`wordlists`
  ( -- n )
  maximum number of wordlists in the dictionary search order

* :command:`cpu`
  ( -- faddr len )
  flash address of the CPU identification string

* :command:`forth-name`
  ( -- faddr len )
  flash address of the amforth name string

* :command:`version`
  ( -- n )
  version number of amforth

* :command:`mcu-info`
  ( -- faddr len )
  flash address of some CPU specific parameters




Exceptions
----------

* :command:`abort`
  ( i*x -- )
  (R: j*y -- )
  send an exception -1

* :command:`abort''`
  ( i*x x1 -- | i*x )
  (R: j*y -- | j*y )
  (C: "ccc<quote>" -- )
  check flag. If true display the parsed text and throw exception -2 

* :command:`catch`
  ( i*x xt -- j*x 0 | i*x n )
  execute XT and check for exceptions.

* :command:`handler`
  ( -- a-addr )
  USER variable used by catch/throw

* :command:`?abort`
  ( f c-addr u --  )
  abort & print msg

* :command:`throw`
  ( n -- )
  throw an exception




Extended VM
-----------

* :command:`a@`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`a@-`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`a@+`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`a!`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`a!-`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`a!+`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`a>`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`b@`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`b@-`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`b@+`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`b!`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`b!-`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`b!+`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`b>`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`na@`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`na!`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`nb@`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`nb!`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)

* :command:`>a`
  ( -- n2 )
  Read memory pointed to by register A (Extended VM)

* :command:`>b`
  ( -- n2 )
  Read memory pointed to by register B (Extended VM)




Interpreter
-----------

* :command:`rectype-dnum`
  ( -- addr )
  Method table for single cell integers

* :command:`rectype-null`
  ( -- addr )
  there is no parser for this recognizer, this is the default and failsafe part

* :command:`rectype-num`
  ( -- addr )
  Method table for single cell integers

* :command:`rectype-xt`
  ( addr len -- xt flags rectype-xt | rectype-null )
  search for a word

* :command:`rectype-xt`
  ( addr len -- xt flags rectype-xt | rectype-null )
  search for a word

* :command:`rectype-xt`
  ( addr len -- xt flags rectype-xt | rectype-null )
  search for a word

* :command:`rec-find`
  ( addr len -- xt flags rectype-xt | rectype-null )
  search for a word

* :command:`rec-num`
  ( -- addr )
  Method table for single cell integers




Interrupt
---------

* :command:`int@`
  ( i -- xt )
  fetches XT from interrupt vector i

* :command:`-int`
  ( -- )
  turns off all interrupts 

* :command:`+int`
  ( --  )
  turns on all interrupts

* :command:`int!`
  ( xt i -- )
  stores XT as interrupt vector i

* :command:`int-trap`
  ( i --  )
  trigger an interrupt

* :command:`irq[]#`
  ( i -- xt )
  fetches XT from interrupt vector i

* :command:`#int`
  ( -- n )
  number of interrupt vectors (0 based)




Logic
-----

* :command:`and`
  ( n1 n2 -- n3 )
  bitwise and

* :command:`negate`
  ( n1 -- n2 )
  2-complement

* :command:`not`
  ( flag -- flag' )
  identical to 0=

* :command:`or`
  ( n1 n2 -- n3 )
  logical or

* :command:`?dnegate`
  ( d1 n -- d2 )
  negate d1 if n negative

* :command:`?negate`
  ( n1 n2 -- n3 )
  negate n1 if n2 negative

* :command:`xor`
  ( n1 n2 -- n3)
  exclusive or




MCU
---

* :command:`!@spi`
  ( n1 -- n2 )
  SPI exchange of 2 bytes, high byte first

* :command:`bm-clear`
  ( bitmask byte-addr --  )
  clear bits set in bitmask on byte at addr

* :command:`bm-set`
  ( bitmask byte-addr --  )
  set bits from bitmask on byte at addr

* :command:`bm-toggle`
  ( bitmask byte-addr --  )
  toggle bits set in bitmask on byte at addr

* :command:`-jtag`
  ( -- )
  disable jtag at runtime

* :command:`n@spi`
  ( addr len -- )
  read len bytes from SPI to addr

* :command:`n!spi`
  ( addr len -- )
  read len bytes from SPI to addr

* :command:`rx?-poll`
  (c -- )
  wait for one character and read it from the terminal connection using register poll

* :command:`rx-poll`
  (c -- )
  wait for one character and read it from the terminal connection using register poll

* :command:`c!@spi`
  ( txbyte -- rxbyte)
  SPI exchange of 1 byte

* :command:`!wdc`
  ( n -- )
  timed write into watchdog control registers

* :command:`tx?-poll`
  (c -- )
  check availability and send one character to the terminal using register poll

* :command:`tx-poll`
  (c -- )
  check availability and send one character to the terminal using register poll

* :command:`ubrr`
  ( -- v)
  returns usart UBRR settings

* :command:`+usart`
  ( -- )
  initialize usart

* :command:`wdr`
  ( -- )
  calls the MCU watch dog reset instruction




Memory
------

* :command:`c@`
  ( a-addr - c1 )
  fetch a single byte from memory mapped locations

* :command:`cmove`
  (addr-from addr-to n -- )
  copy data in RAM, from lower to higher addresses

* :command:`cmove>`
  (addr-from addr-to n -- )
  copy data in RAM from higher to lower addresses.

* :command:`c!`
  ( c a-addr -- )
  store a single byte to RAM address

* :command:`(!i-nrww)`
  ( n f-addr -- )
  writes n to flash memory using assembly code (code to be placed in boot loader section)

* :command:`@`
  ( a-addr -- n )
  read 1 cell from RAM address

* :command:`@e`
  ( e-addr - n)
  read 1 cell from eeprom

* :command:`@i`
  ( f-addr -- n1 )
  read 1 cell from flash

* :command:`@u`
  ( offset -- n )
  read 1 cell from USER area

* :command:`fill`
  ( a-addr u c -- )
  fill u bytes memory beginning at a-addr with character c

* :command:`!`
  ( n addr -- )
  write n to RAM memory at addr, low byte first

* :command:`!e`
  ( n e-addr -- )
  write n (2bytes) to eeprom address

* :command:`!u`
  ( n offset -- )
  write n to USER area at offset




Multitasking
------------

* :command:`cas`
  ( new old addr -- f )
  Atomic Compare and Swap: store new at addr and set f to true if contents of addr is equal to old.

* :command:`pause`
  ( -- )
  Fetch pause vector and execute it. may make a context/task switch




Numeric IO
----------

* :command:`base`
  ( -- a-addr )
  location of the cell containing the number conversion radix

* :command:`bin`
  ( -- )
  set base for numeric conversion to 10

* :command:`d.`
  ( d -- )
  singed PNO with double cell numbers

* :command:`d.r`
  ( d w -- )
  singed PNO with double cell numbers, right aligned in width w

* :command:`decimal`
  ( -- )
  set base for numeric conversion to 10

* :command:`digit?`
  ( c -- (number|)
  tries to convert a character to a number, set flag accordingly

* :command:`.`
  ( n -- )
  singed PNO with single cell numbers

* :command:`.r`
  ( n w -- )
  singed PNO with single cell numbers, right aligned in width w

* :command:`hex`
  ( -- )
  set base for numeric conversion to 10

* :command:`hld`
  ( -- addr )
  pointer to current write position in the Pictured Numeric Output buffer

* :command:`hold`
  ( c -- )
  prepend character to pictured numeric output buffer

* :command:`<#`
  ( -- )
  initialize the pictured numeric output conversion process

* :command:`number`
  (addr len -- [n|d size] f)
  convert a string at addr to a number

* :command:`#`
  ( d1 -- d2 )
  pictured numeric output: convert one digit

* :command:`#>`
  ( d1 -- addr count )
  Pictured Numeric Output: convert PNO buffer into an string

* :command:`#s`
  ( d -- 0 )
  pictured numeric output: convert all digits until 0 (zero) is reached

* :command:`sign`
  ( n -- )
  place a - in HLD if n is negative

* :command:`>number`
  ( ud1 c-addr1 u1 -- ud2 c-addr2 u2 )
  convert a string to a number  c-addr2/u2 is the unconverted string

* :command:`ud.`
  ( ud -- )
  unsigned PNO with double cell numbers

* :command:`ud.r`
  ( ud w -- )
  unsigned PNO with double cell numbers, right aligned in width w

* :command:`u.`
  ( u -- )
  unsigned PNO with single cell numbers

* :command:`u.r`
  ( u w -- )
  unsigned PNO with single cells numbers, right aligned in width w




R( -- )
-------

* :command:`(i!)`
  ( n addr -- )
  writes a cell in flash




Search Order
------------

* :command:`cfg-order`
  ( -- wid-n .. wid-1 n)
  Get the current search order word list

* :command:`cfg-recs`
  ( -- wid-n .. wid-1 n)
  Get the current search order word list

* :command:`forth-wordlist`
  ( -- wid )
  get the system default word list

* :command:`get-current`
  ( -- wid)
  get the wid of the current compilation word list

* :command:`search-wordlist`
  ( c-addr len wid -- [ 0 ] | [ xt [-1|1]] )
  searches the word list wid for the word at c-addr/len

* :command:`search-wordlist`
  ( c-addr len wid -- [ 0 ] | [ xt [-1|1]] )
  searches the word list wid for the word at c-addr/len

* :command:`set-current`
  ( wid -- )
  set current word list to the given word list wid

* :command:`wordlist`
  ( -- wid )
  create a new, empty wordlist




Stack
-----

* :command:`2drop`
  ( x1 x2 --  )
  Remove the 2 top elements

* :command:`2dup`
  ( x1 x2 -- x1 x2 x1 x2 )
  Duplicate the 2 top elements

* :command:`2r@`
  ( -- d)
  (R: d -- d )
  fetch content of TOR

* :command:`2r>`
  ( -- x1 x2 )
  (R: x1 x2 --)
  move DTOR to TOS

* :command:`2swap`
  ( x1 x2 x3 x4 -- x3 x4 x1 x2 )
  Exchange the two top cell pairs

* :command:`2>r`
  ( x1 x2 -- )
  (R: -- x1 x2)
  move DTOS to TOR

* :command:`depth`
  ( -- n )
  number of single-cell values contained in the data stack before n was placed on the stack.

* :command:`drop`
  ( n -- )
  drop TOS

* :command:`dup`
  ( n -- n n )
  duplicate TOS

* :command:`lp0`
  ( -- addr)
  start address of leave stack

* :command:`nip`
  ( n1 n2 -- n2 )
  Remove Second of Stack

* :command:`nr>`
  ( -- x-n .. x-1 n )
  (R: x-n .. x-1 n -- )
  move n items from return stack to data stack

* :command:`n>r`
  ( x-n .. x-1 n -- )
  (R: -- x-n .. x-1 n)
  move n items from data stack to return stack

* :command:`over`
  ( x1 x2 -- x1 x2 x1 )
  Place a copy of x1 on top of the stack

* :command:`pick`
  ( xu ... x1 x0 u -- xu ... x1 x0 xu )
  access the stack as an array and fetch the u-th element as new TOS

* :command:`?dup`
  ( n1 -- [ n1 n1 ] | 0)
  duplicate TOS if non-zero

* :command:`rot`
  ( n1 n2 n3 -- n2 n3 n1)
  rotate the three top level cells

* :command:`rp0`
  ( -- addr)
  start address of return stack

* :command:`rp@`
  (  -- n)
  current return stack pointer address

* :command:`rp!`
  ( addr  -- )
  (R: -- x*y)
  set return stack pointer

* :command:`r@`
  ( -- n)
  (R: n -- n )
  fetch content of TOR

* :command:`r>`
  ( -- n )
  (R: n --)
  move TOR to TOS

* :command:`sp0`
  ( -- addr)
  start address of the data stack

* :command:`sp@`
  (  -- addr )
  current data stack pointer

* :command:`sp!`
  ( addr -- i*x)
  set data stack pointer to addr

* :command:`swap`
  ( n1 n2 -- n2 n1)
  swaps the two top level stack cells

* :command:`>r`
  ( n -- )
  (R: -- n)
  move TOS to TOR

* :command:`tuck`
  ( n1 n2 -- n2 n1 n2 )
  Copy the first (top) stack item below the second stack item. 




String
------

* :command:`compare`
  ( r-addr r-len f-addr f-len --  f)
  compares two strings in RAM

* :command:`cscan`
  ( addr1 n1 c -- addr1 n2 )
  Scan string at addr1/n1 for the first occurance of c, leaving addr1/n2, char at n2 is first non-c character

* :command:`cskip`
  ( addr1 n1 c -- addr2 n2 )
  skips leading occurancies in string at addr1/n1 leaving addr2/n2 pointing to the 1st non-c character

* :command:`parse`
  ( char "ccc<char>" -- c-addr u )
  in input buffer parse ccc delimited string by the delimiter char.

* :command:`parse-name`
  ( "<name>" -- c-addr u )
  In the SOURCE buffer parse whitespace delimited string. Returns string address within SOURCE.

* :command:`place`
  ( addr1 len1 addr2 -- )
  copy string as counted string

* :command:`/string`
  ( addr1 u1 n -- addr2 u2 )
  adjust string from addr1 to addr1+n, reduce length from u1 to u2 by n

* :command:`sliteral`
  (C: addr len -- )
  (C: addr len -- )
  compiles a string to flash, at runtime leaves ( -- flash-addr count) on stack

* :command:`tolower`
  ( C --  c)
  if C is an uppercase letter convert it to lowercase

* :command:`toupper`
  ( c -- C )
  if c is a lowercase letter convert it to uppercase




System
------

* :command:`accept`
  ( addr +n1 -- +n2 )
  receive a string of at most n1 characters at addr until n2 characters are reveived or cr/lf detected.

* :command:`allot`
  ( n -- )
  allocate or release memory in RAM

* :command:`cold`
  ( i*x -- )
  (R: j*y -- )
  start up amforth.

* :command:`defer@`
  ( xt1 -- xt2 )
  returns the XT associated with the given XT

* :command:`defer!`
  ( xt1 xt2 -- )
  stores xt1 as the xt to be executed when xt2 is called

* :command:`(defer)`
  ( i*x -- j*x )
  runtime of defer

* :command:`(value)`
  ( -- n )
  runtime of value

* :command:`Edefer@`
  ( xt1 -- xt2 )
  does the real defer@ for eeprom defers

* :command:`Edefer!`
  ( xt1 xt2 -- )
  does the real defer! for eeprom defers

* :command:`execute`
  ( xt -- )
  execute XT

* :command:`f_cpu`
  ( -- d )
  put the cpu frequency in Hz on stack

* :command:`interpret`
  (i*x - j*x )
  Interpret SOURCE word by word.

* :command:`nfa>lfa`
  ( nfa -- lfa )
  get the link field address from the name field address

* :command:`#tib`
  ( -- f )
  refills the input buffer

* :command:`.error`
  ( n -- )
  process the error prompt

* :command:`.input`
  ( -- )
  send the READY prompt to the command line

* :command:`ok`
  ( -- )
  send the READY prompt to the command line

* :command:`.ready`
  ( n -- )
  process the error prompt

* :command:`quit`
  ( -- )
  main loop of amforth. accept - interpret in an endless loop

* :command:`Rdefer@`
  ( xt1 -- xt2 )
  The defer@ for ram defers

* :command:`Rdefer!`
  ( xt1 xt2 -- )
  The defer! for ram defers

* :command:`recognize`
  (addr len recstack -- i*x rectype-sometype | rectype-null )
  walk the recognizer stack

* :command:`recognize`
  (addr len recstack -- i*x rectype-sometype | rectype-null )
  walk the recognizer stack

* :command:`refill`
  ( -- f )
  refills the input buffer

* :command:`refill-tib`
  ( -- f )
  refills the input buffer

* :command:`source`
  ( -- addr n )
  address and current length of the input buffer

* :command:`source-tib`
  ( -- f )
  refills the input buffer

* :command:`tib`
  ( -- f )
  refills the input buffer

* :command:`Udefer@`
  ( xt1 -- xt2 )
  does the real defer@ for user based defers

* :command:`Udefer!`
  ( xt1 xt2 -- )
  does the real defer! for user based defers

* :command:`warm`
  ( nx* -- )
  (R: ny* -- )
  initialize amforth further. executes turnkey operation and go to quit




System Value
------------

* :command:`dp`
  ( -- f-addr )
  address of the next free dictionary cell

* :command:`ehere`
  ( -- e-addr )
  address of the next free address in eeprom

* :command:`environment`
  ( -- wid)
  word list identifier of the environmental search list

* :command:`forth-recognizer`
  ( -- addr )
  address of the next free data space (RAM) cell

* :command:`here`
  ( -- addr )
  address of the next free data space (RAM) cell

* :command:`(marker)`
  ( -- e-addr )
  The eeprom address until which MARKER saves and restores the eeprom data.

* :command:`!i`
  ( n addr -- )
  Deferred action to write a single 16bit cell to flash

* :command:`turnkey`
  ( -- n*y )
  Deferred action during startup/reset




System Variable
---------------

* :command:`latest`
  ( -- addr )
  system state

* :command:`lp`
  ( -- addr )
  leave stack pointer

* :command:`newest`
  ( -- addr )
  system state

* :command:`pad`
  ( -- a-addr )
  Address of the temporary scratch buffer.

* :command:`state`
  ( -- addr )
  system state

* :command:`>in`
  ( -- a-addr )
  pointer to current read position in input buffer

* :command:`up@`
  ( -- addr )
  get user area pointer

* :command:`up!`
  ( -- addr )
  get user area pointer




Time
----

* :command:`1ms`
  ( -- )
  busy waits (almost) exactly 1 millisecond




Tools
-----

* :command:`bounds`
  ( addr len -- addr+len addr )
  convert a string to an address range

* :command:`[char]`
  ( -- c )
  (C: "<space>name" -- )
  skip leading space delimites, place the first character of the word on the stack

* :command:`char`
  ( "<spaces>name" -- c )
  copy the first character of the next word onto the stack

* :command:`cfolddepth`
  ( flagset -- n )
  constant fold depth

* :command:`.s`
  ( -- )
  stack dump

* :command:`ver`
  ( -- )
  print the version string

* :command:`ee>ram`
  ( e-addr r-addr len -- )
  copy len cells from eeprom to ram

* :command:`find-xt`
  ( c-addr len --  0 | xt -1 | xt 1 )
  search wordlists for an entry with the xt from c-addr/len

* :command:`find-xt`
  ( c-addr len --  0 | xt -1 | xt 1 )
  search wordlists for an entry with the xt from c-addr/len

* :command:`get-stack`
  ( e-addr -- item-n .. item-1 n)
  Get a stack from EEPROM

* :command:`icompare`
  ( r-addr r-len f-addr f-len --  f)
  compares string in RAM with string in flash. f is zero if equal like COMPARE

* :command:`icount`
  ( addr -- addr+1 n )
  get count information out of a counted string in flash

* :command:`init-ram`
  ( e-addr r-addr len -- )
  copy len cells from eeprom to ram

* :command:`itype`
  ( addr n --  )
  reads string from flash and prints it

* :command:`map-stack`
  ( i*x XT e-addr -- j*y true | i*x false )
  Iterate over a stack

* :command:`name>flags`
  ( nt -- f )
  get the flags from a name token

* :command:`nfa>cfa`
  ( nt -- xt )
  get the XT from a name token

* :command:`noop`
  ( -- )
  do nothing

* :command:`?stack`
  ( --  )
  check data stack depth and exit to quit if underrun

* :command:`set-stack`
  ( rec-n .. rec-1 n ee-addr -- )
  Write a stack to EEPROM

* :command:`show-wordlist`
  ( wid -- )
  prints the name of the words in a wordlist

* :command:`show-wordlist`
  ( wid -- )
  prints the name of the words in a wordlist

* :command:`to`
  ( n <name> -- )
  store the TOS to the named value (eeprom cell)

* :command:`unused`
  ( -- n )
  Amount of available RAM (incl. PAD)

* :command:`word`
  ( c -- addr )
  skip leading delimiter character and parse SOURCE until the next delimiter. copy the word to HERE

* :command:`words`
  ( -- )
  prints a list of all (visible) words in the dictionary




Tools Ext (2012)
----------------

* :command:`name>string`
  ( nt -- addr len )
  get a (flash) string from a name token nt

* :command:`traverse-wordlist`
  ( i*x xt wid -- j*x )
  call the xt for every member of the wordlist wid until xt returns false




unclassified
------------

* :command:`endloop`
  ( -- )
 

* :command:`l>`
  ( -- )
 

* :command:`-1`
  ( -- )
 

* :command:`1`
  ( -- )
 

* :command:`>l`
  ( -- )
 

* :command:`2`
  ( -- )
 

* :command:`umax`
  ( -- )
 

* :command:`umin`
  ( -- )