Core Words                                                                                                                      These words are used to bootstrap the rest of RetroForth. We    currently define 26 words as being core, and also a few         variables.                                                                                                                                                                                                                                                      boot                                                                                                                            Use:     Initial interpreter loop                               Stack:   --                                                     Notes:   This is a vectored word, so it can be replaced by the           startup code. In general, it should be, as it only              provides a very barebones, minimal interpreter prompt                                                                  key                                                                                                                             Use:     Read a key from an input source                        Stack:   -- c                                                   Notes:   This word reads a key from the standard input source.           It is vectored to allow redefinition at any time.                                                                                                                                      emit                                                                                                                            Use:     Display a character on the standard output device      Stack:   c --                                                   Notes:   This is used to show a character on the standard                output device. It is vectored to allow redefinition             at any time.                                                                                                           type                                                                                                                            Use:     Display a string on the standard output device         Stack:   a c --                                                 Notes:   Type is normally used to display a string. It is a              vectored word, allowing redefinition at any time.                                                                                                                                      forth   macro                                                                                                                   Use:     Switch the active dictionary for compilation           Stack:   --                                                     Notes:                                                                                                                                                                                                                                                          find   mfind                                                                                                                    Use:     Find a word in either the forth (find) or macro                 (mfind) dictionaries.                                  Stack:   a c -- n | a c                                         Notes:   Returns TRUE if found, FALSE if not found.                                                                                                                                             >number                                                                                                                         Use:     Convert a string to an integer on the stack            Stack:   a c -- n | a c                                         Notes:   Returns TRUE if the conversion worked; FALSE if it              failed.                                                                                                                                                                                interpret                                                                                                                       Use:     Process input from the TIB                             Stack:   --                                                     Notes:   'eval' also uses this internally                                                                                                                                                                                                                       eval                                                                                                                            Use:     Evaluate a string                                      Stack:   a c --                                                 Notes:                                                                                                                                                                                                                                                          1,   2,   3,   ,                                                                                                                Use:     Inline 1, 2, 3, or 4 bytes to HERE                     Stack:   n --                                                   Notes:                                                                                                                                                                                                                                                          entry                                                                                                                           Use:     Create a new dictionary entry from a string            Stack:   a c --                                                 Notes:   This does not define a body for the entry, it just              creates an entry pointed to HERE                                                                                                                                                       ]                                                                                                                               Use:     The compiler                                           Stack:   --                                                     Notes:   This is where the compilation of a word actually                takes place                                                                                                                                                                            compile                                                                                                                         Use:     Compile a CALL to a word                               Stack:   a --                                                   Notes:   The CALL is relative, not absolute                                                                                                                                                                                                                     [                                                                                                                               Use:     Stop a compile, drop back to the interpreter           Stack:   --                                                     Notes:   Does not terminate the definition, use ; for that.                                                                                                                                                                                                     ;;                                                                                                                              Use:     compile an exit to a definition                        Stack:   --                                                     Notes:   If the last thing compiled was a call, change to a              jmp. Otherwise just compiles in a ret.                                                                                                                                                 ;                                                                                                                               Use:     End a definition                                       Stack:   --                                                     Notes:   Calls ;; and then jumps to [                                                                                                                                                                                                                           :                                                                                                                               Use:     Main compiler wrapper                                  Stack:   --                                                     Notes:   Creates an entry (saving the old state of HERE and              LAST), then jumps to ]                                                                                                                                                                 literal                                                                                                                         Use:     Compiles a literal into a definition                   Stack:   n --                                                   Notes:                                                                                                                                                                                                                                                          #                                                                                                                               Use:     Display the unsigned value of the TOS                  Stack:   n --                                                   Notes:   . and u. are written around this. # does not leave a            trailing space.                                                                                                                                                                        parse                                                                                                                           Use:     Parse input stream                                     Stack:   n -- a c                                               Notes:   Parses TIB until it encounters <char> or the end of a           line.                                                                                                                                                                                  reset                                                                                                                           Use:     Reset the stack to the default starting point          Stack:   ... --                                                 Notes:   Also replaces all values on the stack with 0's                                                                                                                                                                                                         create                                                                                                                          Use:     create a named stub for a data structure               Stack:   --                                                     Notes:   parses the input stream for the name                                                                                                                                                                                                                   does>                                                                                                                           Use:     Modify the runtime behavor of a 'create'd word         Stack:   -- a                                                   Notes:   changes 'call dovar' to 'call <code after does>'                Adds some code to push the address of the data part             to the stack.                                                                                                          last                                                                                                                            Use:     Returns the address of the last dictionary entry       Stack:   -- a                                                   Notes:                                                                                                                                                                                                                                                          there                                                                                                                           Use:     Returns the address of the block buffer                Stack:   -- a                                                   Notes:                                                                                                                                                                                                                                                          tib                                                                                                                             Use:     Push the address of the TIB                            Stack:   -- a                                                   Notes:                                                                                                                                                                                                                                                          word?                                                                                                                           Use:     Vectored error handler                                 Stack:   --                                                     Notes:                                                                                                                                                                                                                                                          h0       Pointer to HERE                                        base     The current numeric base                               >in      Pointer to the current location in the input stream    word?    Pointer to a word that handles errors when words                aren't found                                                                                                                                                                                                                                           Compiler Macros                                                                                                                 These are special words that are executed by the compiler       when they are found in a definition. Some of them also have     counterparts in the forth dictionary for use at the interpreter.                                                                                                                                                                                                1+   1-                                                                                                                         Use:     Increment (1+) or Decrement (1-) the TOS.              Stack:   ( x -- y )                                             Notes:   Inlines to "inc eax" or "dec eax"                      Example: 1+ ( 10 -- 11 ) 1- ( 10 -- 9 )                                                                                                                                                         swap                                                                                                                            Use:     swap the top two items on the stack                    Stack:   ( xy -- yx )                                           Notes:   inlined to "xchg eax, [esi]"                           Example: ( 5 10 -- 10 5 )                                                                                                                                                                       drop                                                                                                                            Use:     drop the tos, setting nos as the new tos               Stack:   ( n -- )                                               Notes:   inlines to "lodsd"                                     Example: 10 20 drop ( 10 20 -- 10 )                                                                                                                                                             nip                                                                                                                             Use:     drop the nos                                           Stack:   ( xy -- y )                                            Notes:   inlines to ""                                          Example: 10 20 nip ( 10 20 -- 20 )                                                                                                                                                              true   false                                                                                                                    Use:     set the value of the flag                              Stack:   ( -- )                                                 Notes:   On x86 this uses the carry flag and can be used with            ?if for conditionals.                                                                                                                                                                  f:   m:                                                                                                                         Use:     Force the compiler to compile a call to a forth word            (f:) or macro (m:).                                    Stack:   ( -- )                                                 Notes:   This can be useful if you need to call a macro at               runtime, or if you have a forth word with the same              name as a macro.                                       [']                                                                                                                             Use:     Compile the address of a word into the definition      Stack:   ( -- )                                                 Notes:   This only searches the forth dictionary, not macros                                                                                                                                                                                                    s"                                                                                                                              Use:     Compile a string into a definition                     Stack:   ( -- a# )                                              Notes:   The string is placed in a special memory buffer and             the address/count is stored in the definition.                                                                         Example: : foo s" hello, world!" type cr ;                      ."                                                                                                                              Use:     Same as s" but also compiles in a call to 'type'       Stack:   ( -- )                                                 Notes:   Basically this is provided to make displaing strings            easier. It is a parsing word.                                                                                                                                                          :                                                                                                                               Use:     Define a new entry point                               Stack:   ( -- )                                                 Notes:   Define a new entry point into a definition. This can            be used in definitions or to start a new one.                                                                                                                                          (                                                                                                                               Use:     Comments in definitions                                Stack:   ( -- )                                                 Notes:   Allow things like stack comments. Comments are                  terminiated by a ) character.                          Example: : foo ( x -- x+2 )  2 + ;                                                                                              >r                                                                                                                              Use:     Place a value on the return stack                      Stack:   ( n -- )                                               Notes:   Drops the TOS                                                                                                                                                                                                                                          r>                                                                                                                              Use:     Take the top of the return stack and place on data              stack                                                  Stack:   ( -- n )                                               Notes:   Drops the TORS                                                                                                                                                                         r                                                                                                                               Use:     Place a copy of the TORS on the data stack             Stack:   ( -- n )                                               Notes:   Does not drop the TORS. This is the macro form of "r"           It is unrelated to the forth form used in the editor.                                                                                                                                  repeat                                                                                                                          Use:     Start a structured loop                                Stack:   ( -- )                                                 Notes:                                                                                                                                                                                                                                                          again                                                                                                                           Use:     Repeat an unconditional loop                           Stack:   ( -- )                                                 Notes:                                                          Example: : foo 0 repeat dup . 1+ again ;                                                                                                                                                        for                                                                                                                             Use:     Start a counted loop                                   Stack:   ( n-- )                                                Notes:   This is the same as 'repeat >r'                                                                                                                                                                                                                        next                                                                                                                            Use:     Repeat a counted loop                                  Stack:   ( -- )                                                 Notes:   The counter is on the return stack, not the data                stack.                                                 Example: : foo 10 for r . next cr ;                                                                                             =if                                                                                                                             Use:     Conditional                                            Stack:   ( xy -- )                                              Notes:   Continue execution if x and y are equal, otherwise              skip to after 'then'                                                                                                                                                                   <>if                                                                                                                            Use:     Conditional                                            Stack:   ( xy -- )                                              Notes:   Continue execution if x and y are not equal, else               skip to after 'then'                                                                                                                                                                   >if                                                                                                                             Use:     Conditional                                            Stack:   ( xy -- )                                              Notes:   Continue execution if x is greater than y,                      otherwise skip to after 'then'                                                                                                                                                         <if                                                                                                                             Use:     Conditional                                            Stack:   ( xy -- )                                              Notes:   Continue execution if x is less than y,                         otherwise skip to after 'then'                                                                                                                                                         ?if                                                                                                                             Use:     Conditional                                            Stack:   ( -- )                                                 Notes:   Continue execution if the flag is true, otherwise               skips to after 'then'                                                                                                                                                                  (if)                                                                                                                            Use:     Conditional (not to be called directly!)               Stack:   ( x -- )                                               Notes:   This is used to implement other conditionals.                                                                                                                                                                                                          Forth Words                                                                                                                     Most words exist in the Forth dictionary. We will show you the  majority of the ones we define here. Note that the rapid        development cycle of RetroForth means that some additions or    slight changes may have taken place. Most of the words should   be here though.                                                                                                                 swap                                                                                                                            Use:     Swap the TOS and NOS                                   Stack:   ( xy -- yx )                                           Notes:   This is also a macro                                                                                                                                                                                                                                   drop                                                                                                                            Use:     Drop the TOS                                           Stack:   ( n -- )                                               Notes:   This is also a macro                                                                                                                                                                                                                                   nip                                                                                                                             Use:     Drop the NOS                                           Stack:   ( xy -- y )                                            Notes:   This is also a macro                                                                                                                                                                                                                                   dup                                                                                                                             Use:     Duplicate the TOS                                      Stack:   ( x -- xx )                                            Notes:                                                                                                                                                                                                                                                          and                                                                                                                             Use:     Bitwise AND                                            Stack:   ( xy -- z )                                            Notes:                                                                                                                                                                                                                                                          or                                                                                                                              Use:     Bitwise OR                                             Stack:   ( xy -- z )                                            Notes:                                                                                                                                                                                                                                                          xor                                                                                                                             Use:     Bitwise XOR                                            Stack:   ( xy -- z )                                            Notes:                                                                                                                                                                                                                                                          not                                                                                                                             Use:     Bitwise NOT                                            Stack:   ( x -- y )                                             Notes:                                                                                                                                                                                                                                                          @   w@   c@                                                                                                                     Use:     Fetch a value                                          Stack:   ( a -- n )                                             Notes:   Fetch a cell (@), word (w@), or byte (c@) from the              address provided                                                @ ( 32-bit fetch )  w@ ( 16 bits )  c@ ( 8 bits )                                                                      !   w!   c!                                                                                                                     Use:     Store a value                                          Stack:   ( na -- )                                              Notes:   Store a cell (!), word (w!), or byte (c!) to the                provided address                                                ! ( 32-bit store )  w! ( 16 bits )  c! ( 8 bits )                                                                      hex                                                                                                                             Use:     Change the base to hexadecimal                         Stack:   ( -- )                                                 Notes:   Base 16                                                                                                                                                                                                                                                decimal                                                                                                                         Use:     Change the base to decimal                             Stack:   ( -- )                                                 Notes:   Base 10                                                                                                                                                                                                                                                binary                                                                                                                          Use:     Change the base to binary                              Stack:   ( -- )                                                 Notes:   Base 2                                                                                                                                                                                                                                                 octal                                                                                                                           Use:     Change the base to octal                               Stack:   ( -- )                                                 Notes:   Base 8                                                                                                                                                                                                                                                 +                                                                                                                               Use:     Add TOS and NOS                                        Stack:   ( xy -- z                                              Notes:   x + y                                                                                                                                                                                                                                                  -                                                                                                                               Use:     Subtract NOS from TOS                                  Stack:   ( xy -- z                                              Notes:   x - y                                                                                                                                                                                                                                                  *                                                                                                                               Use:     Multiply TOS and NOS                                   Stack:   ( xy -- z                                              Notes:   x*y                                                                                                                                                                                                                                                    /mod                                                                                                                            Use:     Divide and determine remainder                         Stack:   ( xy -- dr                                             Notes:                                                                                                                                                                                                                                                          /                                                                                                                               Use:     Divide NOS by TOS                                      Stack:   ( xy -- z )                                            Notes:   x/y                                                                                                                                                                                                                                                    mod                                                                                                                             Use:     Divide NOS by TOS and return the remainder             Stack:   ( xy -- z )                                            Notes:                                                                                                                                                                                                                                                          negate                                                                                                                          Use:     Negate the TOS                                         Stack:   ( x -- y )                                             Notes:   The same as doing  -1 *                                                                                                                                                                                                                                1+                                                                                                                              Use:     Add 1 to TOS                                           Stack:   ( x -- y )                                             Notes:   This is also a macro                                                                                                                                                                                                                                   1-                                                                                                                              Use:     Subtract 1 from TOS                                    Stack:   ( x--y )                                               Notes:   This is also a macro                                                                                                                                                                                                                                   |                                                                                                                               Use:     Comments                                               Stack:   ( -- )                                                 Notes:   This parses until the end of the line and ignores the           parsed code.                                                                                                                    This type of comment does not work in definitions      wsparse                                                                                                                         Use:     Parse ahead until the next whitespace                  Stack:   ( -- ac )                                              Notes:   Whitespace is either a space, tab, or EOL character                                                                                                                                                                                                    lnparse                                                                                                                         Use:     Parse ahead until the end of the line                  Stack:   ( -- ac )                                              Notes:   EOL can be a cr or lf character                                                                                                                                                                                                                        >>                                                                                                                              Use:     Shift right                                            Stack:   ( xy -- z )                                            Notes:                                                                                                                                                                                                                                                          <<                                                                                                                              Use:     Shift left                                             Stack:   ( xy -- z )                                            Notes:                                                                                                                                                                                                                                                          here                                                                                                                            Use:     Return the top of the heap                             Stack:   ( -- a )                                               Notes:   h0 is a variable pointing to the top of the heap. So            'here' is the same as doing 'h0 @'                                                                                                                                                     allot                                                                                                                           Use:     Allocate memory on the heap                            Stack:   ( n -- )                                               Notes:   Allocate X bytes of memory                                                                                                                                                                                                                             cells                                                                                                                           Use:     Convert a number of cells to the size in bytes         Stack:   ( x -- y )                                             Notes:   Cells are 4 bytes (a dword on x86) in size                                                                                                                                                                                                             cell+                                                                                                                           Use:     Increase TOS by the size of a cell                     Stack:   ( x -- y                                               Notes:   Cells are 4 bytes (a dword on x86) in size                                                                                                                                                                                                             cell-                                                                                                                           Use:     Decrease TOS by the size of a cell                     Stack:   ( x -- y                                               Notes:   Cells are 4 bytes (a dword on x86) in size                                                                                                                                                                                                             later                                                                                                                           Use:     Delay execution of a word until the caller finishes    Stack:   ( -- )                                                 Notes:   This is tricky to learn, but very powerful                                                                                                                                                                                                             exit,                                                                                                                           Use:     Compile an exit instruction                            Stack:   ( -- )                                                 Notes:   Compiles a RET ($c3) on x86                                                                                                                                                                                                                            create:                                                                                                                         Use:     Create a new dictionary entry                          Stack:   ( -- )                                                 Notes:   Does a 'wsparse entry' to create the entry                                                                                                                                                                                                             variable                                                                                                                        Use:     Create a variable                                      Stack:   ( -- )                                                 Notes:   This creates a variable with an initial value of 0                                                                                                                                                                                                     variable:                                                                                                                       Use:     Create a variable                                      Stack:   ( x -- )                                               Notes:   This creates a variable with an initial value of 'x'                                                                                                                                                                                                   rot                                                                                                                             Use:     Rotate the stack                                       Stack:   ( xyz -- yzx )                                         Notes:                                                                                                                                                                                                                                                          -rot                                                                                                                            Use:     Rotate the stack twice                                 Stack:   ( xyz -- zxy )                                         Notes:                                                                                                                                                                                                                                                          tuck                                                                                                                            Use:     Tuck a copy of the TOS under the NOS                   Stack:   ( xy -- yxy )                                          Notes:                                                                                                                                                                                                                                                          over                                                                                                                            Use:     Place a copy of the NOS over the TOS                   Stack:   ( xy -- xyx )                                          Notes:                                                                                                                                                                                                                                                          2drop                                                                                                                           Use:     Drop the top two entries on the stack                  Stack:   ( xy -- )                                              Notes:                                                                                                                                                                                                                                                          2dup                                                                                                                            Use:     Duplicate the top two entries on the stack             Stack:   ( xy -- xyxy )                                         Notes:   The same as doing 'over over'                                                                                                                                                                                                                          '                                                                                                                               Use:     Obtain the address of a word                           Stack:   ( -- a )                                               Notes:   This does not recognize macros                                                                                                                                                                                                                         alias                                                                                                                           Use:     Bind an address to a name                              Stack:   ( a -- )                                               Notes:   Using this with loc: and ;loc allows localized                  fatoring                                                                                                                                                                               execute                                                                                                                         Use:     Execute the provided address                           Stack:   ( a -- )                                               Notes:   The address is passed on the stack. No validation is            performed, so be careful when using this                                                                                                                                               literal,                                                                                                                        Use:     Compile a literal to HERE                              Stack:   ( n -- )                                               Notes:                                                                                                                                                                                                                                                          constant                                                                                                                        Use:     Create a symbolic constant                             Stack:   ( n -- )                                               Notes:   Essentially the same as ": name value ;"                                                                                                                                                                                                               0;                                                                                                                              Use:     Exit a word if the TOS is 0                            Stack:   ( x -- y| )                                            Notes:   Useful in loops                                                                                                                                                                                                                                        list                                                                                                                            Use:     Array holding the addresses of 'last' during a loc:             and ;loc pairing                                       Stack:   ( -- a )                                               Notes:   Not intended for use by words other than loc: and               ;loc                                                                                                                   loc:                                                                                                                            Use:     Start a locally factored definition                    Stack:   ( -- )                                                 Notes:   You can nest up to four levels deep.                                                                                                                                                                                                                   ;loc                                                                                                                            Use:     End a locally factored definition                      Stack:   ( -- )                                                 Notes:   This removes all word names between the prior loc:              and this. The definitions are left behind.                                                                                                                                             fill                                                                                                                            Use:     Fill memory with a specified byte                      Stack:   ( acb -- )                                             Notes:   b is the byte to fill memory with                                                                                                                                                                                                                      move                                                                                                                            Use:     Copy a region of memory from one location to another   Stack:   ( sdc -- )                                             Notes:   s is source, d is dest, # is the number of bytes to             move                                                                                                                                                                                   pad                                                                                                                             Use:     Return the address of the PAD                          Stack:   ( -- a )                                               Notes:   Strings are initially placed in PAD                                                                                                                                                                                                                    >pad                                                                                                                            Use:     Copy a string to the PAD                               Stack:   ( ac -- ac )                                           Notes:   Destroys the original contents of PAD                                                                                                                                                                                                                  "                                                                                                                               Use:     Create a temporary string                              Stack:   ( -- ac )                                              Notes:   The string is placed in PAD using >PAD                                                                                                                                                                                                                 ."                                                                                                                              Use:     Display a string                                       Stack:   ( -- )                                                 Notes:   The string is placed in PAD before displaying it                                                                                                                                                                                                       $,                                                                                                                              Use:     Inline a string into the definition of the current              word.                                                  Stack:   ( ac -- )                                              Notes:   This compiles in the address and count, then a jump,            then the definition. The string is inlined into the             body of the definition.                                zt                                                                                                                              Use:     Make a temporary zero-terminated string                Stack:   ( ac -- a )                                            Notes:   This replaces zt-make and zt-free from the 7.x series                                                                                                                                                                                                  cr                                                                                                                              Use:     Next output will be on the next line                   Stack:   ( -- )                                                 Notes:                                                                                                                                                                                                                                                          space                                                                                                                           Use:     Display a space                                        Stack:   ( -- )                                                 Notes:                                                                                                                                                                                                                                                          .                                                                                                                               Use:     Display a signed number                                Stack:   ( n -- )                                               Notes:                                                                                                                                                                                                                                                          u.                                                                                                                              Use:     Display an unsigned number                             Stack:   ( n -- )                                               Notes:                                                                                                                                                                                                                                                          words                                                                                                                           Use:     Display all currently defined words in the current              dictionary                                             Stack:   ( -- )                                                 Notes:                                                                                                                                                                                          ui                                                                                                                              Use:     A pointer to a word to execute during the interpret             cycle.                                                 Stack:   ( -- a )                                               Notes:   "exit" resets this to the default (no-op) state                                                                                                                                        exit                                                                                                                            Use:     Reset the "ui" to the default                          Stack:   ( -- )                                                 Notes:                                                                                                                                                                                                                                                          vector                                                                                                                          Use:     Make a word vectored for is                            Stack:   ( -- )                                                 Notes:   Vectors have an initial value, and can be redirected            with is, or reset with devector.                       Example: : foo vector ." This is the initial value." ;                                                                          is                                                                                                                              Use:     Changes a vectored word to point to a given function   Stack:   ( a-- )                                                Notes:   Takes an address from stack and puts a jump in the              following word to that address.  See vector.           Example: ' words is foo                                                  here ] ." Hello world, this is a vector!" cr ; is foo  devector                                                                                                                        Use:     Sets vectored words back to their default              Stack:   ( -- )                                                 Notes:   Opposite of is.  Resets back to default value.         Example: : exit < devector ui > ;                                                                                                                                                               <  >                                                            Use:     from a macro func, evaluate at runtime                 Stack:   ( -- )                                                 Notes:   Since macros evaluate at compile time you may wish to           delay some code til runtime.  this is much like                 s" ..... " eval  within a macro.                       Example: : annoy < ' words is ui > ;                                     : exit < devector ui > ;                               