RetroForth: Handbook

This is a dynamic version of the handbook that can be edited by anyone with a valid key. Please be aware that this uses a custom markup language that is not directly related to other markup languages.

reload | edit
Other Formats: ascii, ps

Key:

\author Charles R. Childers
\title RetroForth Handbook
\copyright (pd)2006

\comment -----------------------------------------------
\comment Some things on the todo list:
\comment  * pdf generation
\comment  * "discussion" capabilities on a per-section
\comment    basis
\comment -----------------------------------------------

\t Welcome to RetroForth

\p RetroForth is an implementation of the Forth programming language. It provides a flexible set of words, block editor, and interactive environment in one small package.

\p The implementation is built over the Rx Core; a very small library that provides the core functionality needed by a Forth system. The development of Rx Core and RetroForth are related. This handbook is based on the Rx Handbook, and some areas will reflect that.

\p RetroForth does not follow any of the various standards for Forth that have been created over the years. Rather, the words and their behaviour has evolved over a period of eight years to service those using it. The code is continually being refined; new things added, and obsolete things phased out. It is an active codebase.

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\t What are word classes?

\p A concept called \i word \i classes is at the heart of RetroForth. Word classes are a way to group related words, based on their compilation and execution behaviors. A special word, called a \i class \i handler, is defined to handle an execution token passed to it on the stack. The compiler uses a variable named class to set the default class when compiling a word. We'll take a closer look at class later. Rx provides several classes with differing behaviors:

\pre
\n .class ( xt -- )
\n The class handler for the provided classes. 
\n During compilation, a call to the xt is compiled. 
\n During interpretation, the xt is executed.
\n
\n .data ( xt -- )
\n .data is used for data structures and numbers. It 
\n will leave the xt on the stack during interpretation 
\n and compile the xt as a literal during compilation.
\n
\n .forth ( xt -- )
\n The class handler for forth words. 
\n Semantics are the same as with .class
\n
\n .self ( xt -- )
\n Words using this class are always called, unless used 
\n in a definition with a prefixing word immediately 
\n before them. Generally words using this class will 
\n need to be state-smart.
\n
\n .macro ( xt -- )
\n Used for compiler macros, words with a class of .macro 
\n are always called during compilation (unless preceded 
\n by a prefixing word). They are ignored during 
\n interpretation.
\n
\n .inline ( xt -- )
\n This is a special class used for certain primitives. 
\n It will copy the machine code (up to a hex value of 
\n $C3, the ret instruction) into the current definition 
\n during compilation. During interpretation the word 
\n is called normally. Only words that do not use $c3 
\n and have no calls to other words can use the .inline 
\n class.
\-pre

\p The class mechanism is not limited to these classes. You can write custom classes at any time. On entry the custom handler should take the XT passed on the stack and do something with it. Generally the handler should also check the compiler state to determine what to do in either interpretation or compilation. As a simple example, let's take a look at the \b .data hander, written in Forth:

\pre 
\n ( handler for data types )
\n ( This compiles the XT as a literal in a definition. If interpreting, just leave )
\n ( the XT on the data stack. )
\n ( For constants, we make use of a clever trick. We set the XT to the value of the )
\n ( constant and give it a class of .data allowing it to work without requiring any )
\n ( special code or create/does> constructs )
\n : .data ( xt -- xt | ) state @ if literal, then ;
\-pre

\p When writing programs in Rx, you will need to set the class of each word you write. There are numerous ways to do this. A look at the example below will show how each method appears in source. We'll use the \b .forth class in the examples, but the same approach applies to all of the classes.

\pre
\n ' .forth class ! ( set the default class to .forth )
\n ' .forth reclass ( set the class of the last defined word to .forth )
\n ' .forth reclass: wordname ( set wordname to the .forth class )
\-pre

\p Because changing the default class will be done regularly, the main classes also have wrapper functions provided. These wrappers are given a class of \b .forth and are listed below. In general, it's recommended to use these wrappers to set the default class for readability reasons.

\pre
\n forth  ( -- )
\n Set .forth as the active class
\n
\n macro  ( -- )
\n Set .macro as the active class
\n
\n self   ( -- )
\n Set .self as the active class
\n
\n inline ( -- )
\n Set .inline as the active class
\-pre

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\comment -----------------------------------------------
\comment Should we have a section on loops and a section
\comment on conditionals?
\comment -----------------------------------------------

\t Dictionary Headers

\p The Rx Core has a single dictionary consisting of a linked list of headers. The current form of a header is shown in the chart below. Pay special attention to the accessors. Each of these words corresponds to a field in the dictionary header. When dealing with dictionary headers, it is recommended that you use the accessors to access the fields since it is expected that the exact structure of the header will change over time.

\pre
\n accessor:  :link
\n offset:    0
\n Use:       Link to the previous header. If set to 0, 
\n            no prior entries are visible.
\n
\n accessor:  :xt
\n offset:    4
\n Use:       Link to the compiled code definition. For 
\n            constants, the value of the constant is stored 
\n            in this field.
\n
\n accessor:  :class
\n offset:    8
\n Use:       Link to the class handler.
\n
\n accessor:  :doc
\n offset:    12
\n Use:       Store a pointer to a documentation string, source, or
\n            other documentation source.
\n
\n accessor:  :name
\n offset:    16
\n Use:       The name of the word, stored as a packed string.
\-pre

\p Word names are stored in the dictionary as packed strings. Use \b unpack to obtain a counted string from it. In memory, a packed string looks like:

\pre
\n count (one byte)
\n actual string (a sequence of bytes)
\-pre

\p Because of the use of a single byte for the count, word names are limited to 255 characters.

\p The most recently created header can be accessed by using a variable named \b last. To access a specific header, you can use \b >entry to get the header that points to a specified XT. A special variable named \b which is also updated by find each time a word is looked up in the dictionary. This variable always points to the entry of the most recently found word.

\p Given only a single dictionary, it might seem limiting, however both vocabularies and lexical scope have been implemented on top of it. We will look at each of these now.

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\t Lexical Scope

\p There will be often be times you would like to "hide" some words that you only use once or twice to build other words. In Rx, the ability to do this is provided by the lexical scoping words \b loc: and \b ;loc

\p A typical use looks like:

\pre
\n loc:                     ( start a lexically scoped sequence )
\n   loc:                   ( start a lexically scoped sequence )
\n     10 constant ten
\n     20 constant twenty
\n     10 20 * constant two-hundred
\n     here ] two-hundred ; ( anonymous definition )
\n     words                ( debugging; show words in dictionary )
\n   ;loc is value          ( close the lexically scoped sequence and reveal )
\n                          ( the anonymous definition as "value" )
\n   words                  ( debugging; show words in dictionary )
\n   : a value 10 / ;
\n   : b value 20 / ;
\n   here ] a b * . cr ;    ( anonymous definition )
\n ;loc is foo              ( close the lexically scoped sequence and reveal )
\n                          ( the anonymous definition as "foo" )
\n words ( debugging; show words in dictionary )
\-pre

\p As you can see in the example above, when a lexically scoped definition is closed, the headers for all words inside the scoped region are removed. Only words explicitly revealed are kept in in the global dictionary. Also, as is shown in the example, you can nest lexically scoped sequences. Nesting is possible up to four levels deep.

\p Lexical scopes are used frequently by the developers of Rx and allow a good level of factoring without polluting the actual dictionary with words that are not needed outside a select few definitions.

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\t Handling Syntax Errors

\p By default, the Rx Core ignores syntax errors. This behavior can be altered freely by those using Rx by replacing the \b word? hook with a new definition. The \b word? hook is the "last chance" error handler. When the interpreter obtains a token it tries to process it in a defined order:

\pre
\n 1. Look up the token in the dictionary. If found, execute its class handler
\n 2. Attempt to convert the token to a number. If valid, execute the .data
\n    class handler to determine the course of action to take
\n 3. Call word? to hopefully resolve the problem.
\-pre

\p You can extend this or simply report errors by changing \b word? to point to a new definition. As a vectored word, this is easily done. A simple example is shown below.

\pre
\n ( Example of a custom error handler. )
\n here is word? ] ( ac-f ) ." could not identify: " type cr false ;
\-pre

\p This replaces the default definition of \b word? with a new handler that displays a nice error message.

\p Of course it is possible to write significantly more flexible error handlers. For instance, you could write a handler for entering floating point numbers, say \b >float, and hook that into \b word? to allow the user to enter floating point numbers directly at the interpreter.

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\t Vectored Words

\p Many words in Rx are defined as vectored words. These are similar to, but more flexible than, deferred words in ANS Forth. A vectored word will have vector as the first word in its definition. This is the only step necessary to make a word vectorable. Four words are provided for creating and working with vectors.

\pre
\n vector   ( - )
\n Put this as the first word in a definition to make it 
\n into a vectorable word.
\n
\n is       ( a"- )
\n Set the following wordname to point to the address on 
\n the stack. If the word does not exist, create it as a
\n vector defaulting to the passed address.
\n
\n devector ( "- )
\n Remove the vector set by is.
\n
\n default: ( a"- )
\n Used in a special form, e.g:
\n  : foo vector vector ;
\n This will set the *second* vector to the passed
\n address.
\-pre

\p As an example:

\pre
\n ( simple example of vectors )
\n : a vector 12 ;
\n : b vector 23 ;
\n : c vector a b * ;
\n : d a . ." times " b . ." equals " c . cr ;
\n d
\n here is a ] 23 ;
\n d
\n here is b ] 13 ;
\n d
\n here is c ] a b + ;
\n
\n d
\n devector a
\n d
\n devector b
\n d
\n devector c
\n d
\-pre

\p While a bit simplistic, this does show how to use vectors. Vectors can also be used with lexically scoped sequences to make revealing multiple words cleaner:

\pre
\n ( another example )
\n : a vector ;
\n : b vector ;
\n
\n loc:
\n 10 constant ten
\n 20 constant twenty
\n 
\n : * later prior * ;
\n : + later prior + ;
\n
\n 10 + 20 constant thirty
\n 20 * 20 constant four-hundred
\n 
\n here is a ] ." 10+20=" thirty . cr ;
\n here is b ] ." 20*20=" four-hundred . cr ;
\n ;loc
\-pre

\p Learning to use vectored words will allow you to explore new options in your programming.

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\t Word Prefixes

\p Release 9.2 of RetroForth introduced \i word \i prefixes, which are single character prefixes that can enhance readability and add new features. \b More \b to \b come.

\pre
\n ~name         -- return the xt of name
\n `name         -- compile a call to name
\n !name @name   -- store and fetch from a variable called name
\n +name -name   -- add to and subtract from the variable name's current contents
\-pre

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\t Quotes

\p \b coming \b soon

\p Can be nested up to four levels deep. Useful inside words or at the console.

\pre
\n [[
\n ]]
\-pre

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\t Appendix 1: Glossary of Words

\pre
\n .class ( xt -- ) .class
\n Class handler for the provided classes
\n
\n .forth ( xt -- ) .class
\n Class handler for Forth words
\n
\n .macro ( xt -- ) .class
\n Class handler for compiler macros
\n 
\n .inline ( xt -- ) .class
\n Class handler for Forth words that can be inlined
\n
\n .data ( xt -- ) .class
\n Class handler for basic data structures
\n 
\n forth ( -- ) .forth
\n Set the .forth class as the active class
\n
\n macro ( -- ) .forth
\n Set the .macro class as the active class
\n
\n self ( -- ) .forth
\n Set the .self class as the active class
\n 
\n inline ( -- ) .forth
\n Set the .inline class as the active class
\n 
\n entry ( addr count -- ) .forth
\n Create a dictionary entry pointing to here. A string containing the name
\n of the word to be created is passed on the stack. The word is created with
\n the current class.
\n 
\n lookup ( addr count --- xt flag | addr count flag ) .forth
\n Attempt to find a word in the dictionary. If successful, it returns the
\n address of the word and the true value. If unsuccessful, it leaves the
\n string containing the word to search for on the stack and returns a value
\n of false.
\n
\n >number ( addr count -- n flag | addr count flag ) .forth
\n Attempt to convert a string to a number in the current base. If successful,
\n leave the number and a value of true on the stack. If unsuccessful, leaves
\n the string containing the number on the stack and a return value of false.
\n 
\n ] ( -- ) .forth
\n Turn the compiler mode on. This sets state to -1.
\n 
\n compile ( xt -- ) .forth
\n Compile a call to the specified xt.
\n Technical note:
\n   The call instruction is relative. To obtain the address of a word
\n   from a compiled definition, try something like:
\n      : foo words ; ' foo 1+ @ here + 5 +
\n   This will adjust the first call (1+ skips over the call opcode) to
\n   point to the valid address for the function used. The "5 +" is the
\n   adjustment, based on the size of a call. Call opcodes on x86 are
\n   5 bytes long.
\n
\n , ( n -- ) .forth
\n Place a cell (4 byte) value into the heap
\n 
\n 1, ( n -- ) .forth
\n Place a single byte into the heap
\n
\n 2, ( n -- ) .forth
\n Place a word (2 bytes) into the heap
\n 
\n 3, ( n -- ) .forth
\n Place three bytes into the heap
\n
\n eval ( addr count -- ) .forth
\n Evaluate (using the current compiler state) the string. The results
\n of the evaluation are left on the stack.
\n 
\n parse ( delimiter -- addr count ) .forth
\n Search ahead in the tib for the delimiter. This skips leading whitespace
\n and, if not found, will return a string containing the rest of the
\n input line.
\n 
\n reset ( ... -- ) .forth
\n Remove all values from the stack
\n 
\n last ( -- addr ) .forth
\n Get the address of a pointer to the most recent dictionary entry
\n 
\n tib ( -- addr ) .forth
\n Get the address of the text input buffer
\n 
\n word? ( addr count -- flag ) .forth
\n Last-chance error handler for syntax errors. Receives a string
\n pointing to a token that was not located in the dictionary or converted
\n to a number. The returned flag should tell whether it was handled
\n successfully or not.
\n
\n not ( n -- n ) .forth
\n Perform a bitwise NOT operation on the TOS
\n 
\n @ ( addr -- n ) .forth
\n Fetch a cell-sized value from the address specified
\n 
\n ! ( n addr -- ) .forth
\n Store a cell-sized value into the address specified
\n 
\n w@ ( addr -- n ) .forth
\n Fetch a word-sized value from the address specified
\n 
\n w! ( n addr -- ) .forth
\n Store a word-sized value into the address specified
\n
\n c@ ( addr -- n ) .forth
\n Fetch a single byte from the address specified
\n
\n c! ( n addr -- ) .forth
\n Store a single byte into the address specified
\n
\n + ( x y -- z ) .forth
\n - ( x y -- z ) .forth
\n * ( x y -- z ) .forth
\n / ( x y -- z ) .forth
\n mod ( x y -- z ) .forth
\n These are the basic math words. Insert the operation between the "x" and
\n "y" in the stack comment to convert to infix notation.
\n
\n /mod ( x y -- z n ) .forth
\n Divide, returning the result and the remainder (x/y)
\n
\n wsparse ( "word" -- addr count ) .forth
\n Parse ahead in the TIB until either a space or end of line is reached.
\n
\n lnparse ( "line" -- addr count ) .forth
\n Parse ahead in the tib until the end of the line is reached
\n
\n ' ( "name" -- xt | addr count ) .forth
\n Return the address of a function in the dictionary or the name of
\n the word if it doesn't exist.
\n    Technical note:
\n      This word will set which to the dictionary entry of the word
\n      if found.
\n
\n x' ( "name" -- xt flag | addr count flag ) .forth
\n Return the address of a function in the dictionary or the name of
\n the word if it doesn't exist. Also returns a flag that can be used
\n with the conditional words.
\n 
\n >> ( x y -- z ) .forth
\n Perform a bitwise right shift
\n
\n << ( x y -- z ) .forth
\n Perform a bitwise left shift
\n 
\n here ( -- addr ) .forth
\n Return the value on the top of the stack
\n 
\n :link ( dt -- addr ) .forth
\n Return the address of the link field in a dictionary entry
\n 
\n :xt ( dt -- addr ) .forth
\n Return the address of the xt field in a dictionary entry
\n
\n :class ( dt -- addr ) .forth
\n Return the address of the class field in a dictionary entry
\n
\n :doc ( dt -- addr ) .forth
\n Return the address of the docstring
\n
\n :name ( dt -- addr ) .forth
\n Return the address of the name field in a dictionary entry.
\n Use count to convert this to a string.
\n
\n reclass ( class -- ) .forth
\n Change the class of the most recently defined word to the specified
\n class.
\n 
\n reclass: ( xt "name" -- ) .forth
\n Change the class of the word specified by name to the specified class
\n
\n cells ( x -- y ) .forth
\n Return x multiplied by the size of a cell (4 bytes)
\n
\n cell+ ( x -- y ) .forth
\n Add the size of a cell (4 bytes) to x
\n 
\n cell- ( x -- y ) .forth
\n Subtract the size of a cell (4 bytes) from x
\n 
\n word+ ( x -- y ) .forth
\n Add the size of a word (2 bytes) to x
\n
\n word- ( x -- y ) .forth
\n Subtract the size of a word (2 bytes) from x
\n
\n rot ( x y z -- y z x ) .forth
\n Rotate the stack so that the third element is on top.
\n 
\n -rot ( x y z -- z x y ) .forth
\n Rotate the stack twice. Basically the same as doing rot rot.
\n
\n over ( x y -- x y x ) .forth
\n Place a copy of NOS above TOS
\n
\n tuck ( x y -- y x y ) .forth
\n Place a copy of TOS under NOS
\n 
\n 2dup ( x y -- x y x y ) .forth
\n Duplicate the top two items on the stack
\n
\n later ( rs:x rs:y -- rs:y rs:x ) .forth
\n Defer execution of the rest of the definition until the caller
\n finishes executing.
\n
\n 0; ( n -- n | ) .forth
\n Exit a word if the TOS is equal to 0. Drops TOS before exiting.
\n Leave it alone if non-zero.
\n
\n execute ( xt -- ) .forth
\n Call the code that xt points to. This word ignores the class!
\n   Technical note:
\n     This treats the passed xt as a .self word.
\n   General note:
\n     You can use get-class to obtain the class handler for the
\n     specified xt.
\n
\n create: ( "name" -- ) .forth
\n Create a new word with a name of name and the current class
\n
\n literal, ( n -- ) .forth
\n Compile a literal into a definition. This is different from the
\n macro word literal which is called at compile time. This word
\n is called at runtime.
\n
\n literal? ( n -- n | ) .forth
\n If compiling, compile 'n' as a literal. If interpreting, leave
\n it on the stack.
\n
\n create ( "name" -- ) .forth
\n Create a new word named name using the .data class.
\n
\n variable ( "name" -- ) .forth
\n Create a variable named name with an initial value of 0
\n
\n variable: ( n "name" -- ) .forth
\n Create a variable named name with an initial value of n.
\n
\n constant ( n "name" -- ) .forth
\n Create a constant named name with a value of n.
\n 
\n +! ( n addr -- ) .forth
\n Add n to the contents of the memory location specified by addr.
\n 
\n -! ( n addr -- ) .forth
\n Subtract n from the contents of the memory location specified
\n by addr.
\n 
\n allot ( n -- ) .forth
\n Allocate n bytes in the heap
\n 
\n
\n alias ( xt "name" -- ) .forth
\n Create an alternate dictionary entry for xt with a name of name
\n
\n loc: ( -- ) .forth
\n Start a lexically scoped section of code. These can be nested up to
\n four deep.
\n
\n ;loc ( -- ) .forth
\n End the current lexically scoped section of code.
\n 
\n fill ( addr count value -- ) .forth
\n Fill the memory location specified by addr with count bytes of the
\n specified value.
\n 
\n move ( source dest count -- ) .forth
\n Move count bytes from the memory address specified by source to dest.
\n 
\n copy ( source dest count -- dest count ) .forth
\n Copy "count" bytes from source to dest, leaving the destination and
\n count on the stack.
\n
\n pad ( -- addr ) .forth
\n Return the address of the pad, a floating buffer above here which is
\n used for temporary strings and other structures.
\n 
\n " ( "string" -- addr count ) .forth
\n Parse ahead until a " is encountered. Place this string in the PAD and
\n return a pointer to it.
\n
\n z" ( "string" -- addr ) .forth
\n Like ", but returns a zero-terminated string
\n
\n $, ( addr count -- ) .forth
\n Compile a string into the current definition.
\n 
\n hex ( -- ) .forth
\n Switch to base 16
\n
\n decimal ( -- ) .forth
\n Switch to base 10
\n
\n binary ( -- ) .forth
\n Switch to base 2
\n 
\n octal ( -- ) .forth
\n Switch to base 8
\n
\n >entry ( xt -- dt ) .forth
\n Given an xt, obtain the corresponding dictionary entry.
\n
\n unpack ( addr -- addr count ) .forth
\n Convert a packed string to a counted string (useful with dictionary
\n entries)
\n
\n is ( xt "name" -- ) .forth
\n Change the vectored word name to point to xt. If name does not exist,
\n create a new vectored word with a default definition of xt.
\n
\n default: zt "name" -- ) .forth
\n Change the second vector in a double-vectored word to point to xt.
\n
\n devector ( "name" -- ) .forth
\n Remove the vector of name, restoring the original definition.
\n
\n zt ( addr count -- addr ) .forth
\n Convert a counted string to a zero-terminated string. Cleanup of
\n allocated space is done automatically.
\n
\n get-class ( xt -- xt class ) .forth
\n Obtain the class for a specified xt; if the xt is not found in the
\n dictionary, assumes a default class of .forth
\n
\n =   ( x y -- flag ) .forth
\n <>  ( x y -- flag ) .forth
\n <   ( x y -- flag ) .forth
\n >   ( x y -- flag ) .forth
\n Compare x any y, return a true/false flag that can be used with
\n the new conditionals or 'if'.
\n
\n t   ( flag xt -- ) .forth
\n Execute xt if the flag is true
\n
\n f   ( flag xt -- ) .forth
\n Execute the xt if the flag is false
\n
\n t/f ( flag xt1 xt2 -- ) .forth
\n Execute xt1 if the flag is true, execute xt2 if the flag is false
\n
\n on ( addr -- ) .forth
\n off ( addr -- ) .forth
\n 'on' sets a variable to 'true', 'off' sets it to false
\n
\n toggle ( addr -- ) .forth
\n Toggle a variable between true and false
\n
\n ( ( "comment" -- ) .self
\n Parse ahead until the ) character or end of line is found. Ignore
\n everything that was parsed.
\n
\n : ( "name" -- ) .self
\n Create a new word with a name of "name" and start the compiler. The
\n word is created in the current class.
\n
\n [[ ( -- ) .self
\n ]] ( -- xt ) .self
\n Start and end an anonymous definition. This can be used inside
\n other definitions, and nested up to four levels deep.
\n
\n ; ( -- ) .macro
\n End the current definition
\n See also: ;;
\n
\n [ ( -- ) .macro
\n Switch to interpretation mode. Sets state to 0.
\n
\n ;; ( -- ) .macro
\n Compile an exit to the current word without ending the definition
\n    Technical note:
\n      This word will compile either a "ret" ($c3 opcode) or change
\n      the last compiled call opcode to a jump opcode. This provides
\n      inherent tail call elimination and allows for safe recursion.
\n       As ; uses this, the same applies to it.
\n
\n literal ( n -- ) .macro
\n Compile a literal from the stack into the current definition
\n
\n x: ( "name" -- ) .macro
\n Compile a call to name ignoring the action defined by the word's class.
\n This treats the "name" as a .self word.
\n
\n ['] ( "name" -- ) .macro
\n Compile the xt of name into the current word
\n
\n c: ( "name" -- ) .macro
\n Compile the code needed to compile a call to name into the current
\n definition. Does the same thing as: ['] name compile
\n
\n as ( "class" -- ) .macro
\n Change the class of the most recently created word to the specified
\n class
\n
\n >r ( n -- rs:n ) .macro
\n Move TOS onto the return stack.
\n
\n r> ( rs:n -- n ) .macro
\n Move TORS to the data stack
\n
\n r ( -- n ) .macro
\n Get a copy of TORS on the data stack.
\n    Historical Note:
\n       In most Forths this word is called r@. In RetroForth, it has
\n       traditionally been called r. We chose to continue with the
\n       RetroForth naming in this case.
\n    Technical Note:
\n       This has the same effect as: r> dup >r
\n
\n rdrop ( rs:n -- ) .macro
\n Drop the TORS.
\n    Technical Note:
\n       Has the same effect as: r> drop
\n
\n repeat ( -- ) .macro
\n Start an unconditional loop
\n 
\n again ( -- ) .macro
\n Close an unconditional loop, branching back to the most recent repeat
\n    Technical Note:
\n       Loops constructed using repeat and again are properly
\n       tail recursive.
\n
\n for ( n -- rs:counter ) .macro
\n Start a counted loop. The counter is put on the return stack
\n
\n next ( rs:counter -- rs:counter | ) .macro
\n Close a loop that starts with for. Decrements the counter. If 0, exit,
\n otherwise branch back to for.
\n
\n (if) ( n -- ) .macro
\n Factor of most of the forms of if
\n General Note:
\n There is seldom any reason to call this word in normal code. Its
\n sole purpose is to factor out a chunk of code shared between the
\n other conditionals.
\n
\n <>if ( x y -- ) .macro
\n =if ( x y -- ) .macro
\n <if ( x y -- ) .macro
\n >if ( x y -- ) .macro
\n We describe these together since they are very similar in functionality.
\n To visualize the action, insert the symbol between "x" and "y" in the
\n stack diagram. <> denotes inequality.
\n These words start a conditional, ending with then.
\n
\n if ( flag -- ) .macro
\n If the flag is true, execute the code between if and then. If not
\n true, skips ahead to then.
\n
\n then ( -- ) .macro
\n Terminate any of the if constructs. This patches the conditional jump
\n to point to the proper offset in the compiled definition.
\n 
\n ;then ( -- ) .macro
\n Compile an exit to the word and then terminate any if construct.
\n    Technical Note:
\n       The same as: ;; then
\n
\n if; ( flag -- ) .macro
\n If true, then exit the word. Otherwise continue execution of the word.
\n    Technical Note:
\n       The same as: if ;; then
\n
\n prior ( "word" -- ) .macro
\n Compile a call to an earlier definition of word.
\n
\n vector ( -- ) .macro
\n Make the word a vectored word. This must be the first word in the
\n definition if you use it.
\n
\n s" ( "string" -- addr count ) .macro
\n Compile a string into the definition
\n
\n { ( "}" -- ) .macro
\n Compile a sequence of code to be evaluated at runtime. The compiler
\n state is not altered by this.
\n
\n dup ( n -- n n ) .inline
\n Duplicate the top item on the stack
\n 
\n 1+ ( x -- y ) .inline
\n Increment the TOS
\n
\n 1- ( x -- y ) .inline
\n Decrement the TOS
\n
\n swap ( x y -- y x ) .inline
\n Exchange the location of the top two items on the stack
\n
\n drop ( x -- ) .inline
\n Discard the top element of the stack
\n
\n nip ( x y -- y ) .inline
\n Discard the second element on the stack
\n
\n 2drop ( x y -- ) .inline
\n Discard the top two elements on the stack
\n 
\n and ( x y -- z ) .inline
\n Perform a bitwise AND operation
\n 
\n or ( x y -- z ) .inline
\n Perform a bitwise OR operation
\n 
\n xor ( x y -- z ) .inline
\n Perform a bitwise XOR operation
\n
\n h0 ( -- addr ) .data
\n Variable pointing to the top of the heap
\n 
\n base ( -- addr ) .data
\n Variable holding the current base
\n 
\n >in ( -- addr ) .data
\n Variable that holds the current address in the sequence being
\n evaluated.
\n 
\n class ( -- addr ) .data
\n Variable that stores the address of the current class handler for
\n creating new words.
\n 
\n state ( -- addr ) .data
\n Variable which contains the state of the compiler. true is compiling,
\n false is interpreting.
\n 
\n which ( -- addr ) .data
\n Variable pointing to the dictionary entry of the most recently
\n found word.
\n 
\n whitespace ( -- addr ) .data
\n Variable which contains a character used as the whitespace to search
\n for.
\n 
\n list ( -- addr ) .data
\ nVariable pointing to a data structure used to implement lexical scoping.
\n 
\n true ( -- addr ) .data
\n Constant returning the value -1
\n 
\n false ( -- addr ) .data
\n Constant returning the value 0
\-pre

\comment -----------------------------------------------
\comment This needs to be updated to cover all the words
\comment in the latest Rx Core and RetroForth itself.
\comment -----------------------------------------------

\t Appendix 2: Assembly Listings

\p Many words in the bootstrap code for Rx are written using raw opcodes for various instructions. This has been a cause of much confusion, so we'd like to take the time now to document what each word actually compiles to. Due to the little-endian nature of the x86, the opcodes in the source are in reverse order. These listings have the normal order.

\pre
\n dup
\n 8946FC mov [esi-4], eax
\n 8D76FC lea esi, [esi-4]
\n
\n drop
\n AD lodsd
\n
\n swap
\n 8706 xchg eax, [esi]
\n
\n nip
\n 83C604 add esi, 4
\n
\n 1+
\n 40 inc eax
\n
\n 1-
\n 48 dec eax
\n
\n 2drop
\n AD lodsd
\n AD lodsd
\n
\n and
\n 2306 and eax, [esi]
\n 83C604 add esi, 4
\n
\n or
\n 0B06 or eax, [esi]
\n 83C604 add esi, 4
\n
\n xor
\n 3306 xor eax, [esi]
\n 83C604 add esi, 4
\n
\n r>
\n <call to dup>
\n 58 pop eax
\n
\n >r
\n 50 push eax
\n AD lodsd
\n 
\n r
\n <call to dup>
\n 58 pop eax
\n 50 push eax
\n
\n rdrop
\n 5B pop ebx
\n
\n =if
\n 0F85 jnz
\n
\n <if
\n 0F8E jng
\n
\n >if
\n 0F8D jnl
\n 
\n <>if
\n 0F84 jz
\n 
\n (if)
\n 3B06 cmp eax, [esi]
\n AD lodsd
\n AD lodsd
\n ???? <conditional, passed on stack>
\n ?????? <offset for jump, dword>
\n
\n then
\n <patch the last jump>
\n $90 nop
\n 
\n vector
\n $E9 jmp
\n ?????? <offset for jump, dword>
\n
\n +
\n 0603 add eax, [esi]
\n 83C604 add esi, 4
\n
\n -
\n 2906 sub [esi], eax
\n AD lodsd
\n
\n *
\n F726 mul dword [esi]
\n 83C604 add esi, 4
\n
\n /mod
\n 89C3 mov ebx, eax
\n AD lodsd
\n 99 cdq
\n F7FB idiv ebx
\n 8946FC mov [esi-4], eax
\n 8D76FC lea esi, [esi-4]
\n 89D0 mov eax, edx
\n 8706 xchg eax, [esi]
\n
\n @
\n 8B00 mov eax, [eax]
\n 
\n !
\n 89C2 mov edx, eax
\n AD lodsd
\n 8902 mov [edx], eax
\n AD drop
\n
\n c!
\n 89C2 mov edx, eax
\n AD lodsd
\n 8802 mov [edx], al
\n AD drop
\n
\n w!
\n 89C2 mov edx, eax
\n AD lodsd
\n 668902 mov [edx], ax
\n AD drop
\n
\n next
\n <call to dup>
\n 58 pop eax
\n 48 dec eax
\n 0F8F jg near
\n ???? <offset to jump to, dword>
\n AD lodsd
\n 
\n >>
\n 89C1 mov ecx, eax
\n AD lodsd
\n D3E8 shr eax, cl
\n
\n <<
\n 89C1 mov ecx, eax
\n AD lodsd
\n D3E0 shl eax, cl
\-pre

\comment -----------------------------------------------
\comment 
\comment 
\comment 
\comment -----------------------------------------------

\end