Builder Wordlist


The following words are in the BUILDER wordlist. In Building mode, the interpreter searches this wordlist first. The interpreter executes the word if it's an immediate word or if the interpreter is not in compile mode. Otherwise, the interpreter does another search without BUILDER in the search order. This keeps the execution semantics of Forth words that are expected to execute on the host PC.

The search order during building generally goes something like BUILDER ... CORE ... HOME. For example: DECIMAL will always set the base to 10 on the host PC because it's at the top of the search order, even when DECIMAL has been defined as a target word in the CORE vocabulary. The HOME vocabulary is a catch-all for words that execute on the host PC. If you define a target word that has the same name as a word in the HOME wordlist, that word will mask the home wordlist's version. If this causes a problem, you can place the desired HOME wordlist words within {{ }} brackets.


Defining words:

NAME stack effect Compilation semantics (what the compiler does)
  stack effect Execution semantics (what the resulting code does)
     
: ( <name> -- f ) Begins a definition. Sets state to 1.
code ( <name> -- f ) Begins a definition. Sets search order to ASSEM.
loco ( <name> -- f ) Begins a code definition with no header. Like CODE but saves the address as an assembler label.
BEFORE: ( <name> -- f ) Chains new code to the beginning of an existing definition. Similar to : .
AFTER: ( <name> -- f ) Chains new code to the end of an existing definition. Similar to : .
VARIABLE ( <name> -- ) Creates a word that points to data space. Allocates a cell. In TOF, lays down 0 to initialized data space.
  ( -- addr ) Points to a cell in data space.
CVARIABLE ( <name> -- ) Creates a word that points to data space. Allocates a byte. In TOF, lays down 0 to initialized data space.
  ( -- addr ) Points to a byte in data space.
SEMAPHORE ( <name> -- ) Same as VARIABLE
2VARIABLE ( <name> -- ) Creates a word that points to data space. Allocates a double cell. In TOF, lays down 0 to initialized data space.
  ( -- addr ) Points to a double cell in data space.
CONSTANT ( x <name> -- ) Creates a word that returns a constant.
  ( -- x ) Pushes x onto the stack.
2CONSTANT ( d <name> -- ) Creates a word that returns a double constant.
  ( -- d ) Pushes d onto the stack.
ARRAY ( len <name> -- ) Creates a word that points to data space. Allocates len bytes. In TOF, lays down 0 to initialized data space.
  ( -- addr ) Points to an array of bytes.
STRING ( len <name> -- ) Creates a word that points to a string. Allocates len bytes.
  ( -- addr len ) Returns address and length of the string
CREATE ( <name> -- ) Creates a pointer for a data structure in data space. Switches to RAM mode. Note: does> is not supported by builder.
  ( -- addr ) Points to data in data space.
PCREATE ( <name> -- ) Creates a pointer for a data structure in program space.
  ( -- addr ) Points to data in program space.
VALUE ( x <name> -- ) Creates a word that points to data space. Allocates a cell, lays down x to initialized data space.
  ( -- x ) Pushes the value of x onto the stack.
VOCABULARY ( <name> -- ) Creates a new target vocabulary.
  ( -- ) Overwrites the top of the search order with this vocabulary.
DEFER ( <name> -- ) Defines a deferred word. Use IS <name> to assign a cfa to it.

Data compilation:

ORG ( a -- ) Sets the HERE value for code or data space depending on whether destination is RAM or ROM.
ALLOT ( n -- ) Increase HERE by n.
HERE ( -- a ) Points to the next available byte in the target image.
ALIGN ( -- ) Allots enough bytes to bring the address to an instruction or cell boundary.
ALIGNED ( a1 -- a2 ) a2 is the next aligned address past a1.
, ( x -- ) Lays down a cell
w, ( w -- ) Lays down a 16-bit value.
lw, ( w -- ) Lays down a 16-bit value, little endian.
bw, ( w -- ) Lays down a 16-bit value, big endian.
ll, ( n -- ) Lays down a 32-bit value, little endian.
bl, ( n -- ) Lays down a 32-bit value, big endian.
," ( string" -- ) Appends a counted string to the target image.
DB" ( string" -- ) Appends a string to the target image.
USB" ( n string" -- ) Lays down unicode string with 1-byte embedded descriptor, n is usually 3.
bindings, ( -- ) Creates a table of binding data. See IMAGE.G.
values, ( -- ) Creates a run-length encoded table of RAM initialization data. See IMAGE.G.

Code Compilation:

; ( -- ) Compile RET or convert the last call to a jump.
assemble ( -- f ) Enters assembler mode for macros.
c[ ( -- f ) Enters assembler mode for inline assembly. End with ]c.
C" ( <string> -- ) Compiles string to data space and code for a literal.
  ( -- addr ) Pushes address of counted string onto stack.
S" ( <string> -- ) Compiles string to data space and code for literals.
  ( -- addr len ) Pushes address and length of string onto stack.
." ( <string> -- ) Compiles string to data space and code to TYPE it.
  ( -- ) Types string.
[COMPILE] ( <name> -- ) Compiles code to compile <name>.
  ( -- ) Compiles a call to <name>.
[ ( -- ) Terminates compile mode. Sets state = 0.
] ( -- ) Resumes compile mode. Sets state = 1.
TO ( x <name> -- ) State=0 (interpret): store x to value <name>.
  ( <name> -- ) State=1 (compile): compile code to store to <name>.
  ( -- x ) TO XYZ compiles to XYZ (%TO!)

These set flags in the last header defined:

immediate ( -- ) This word is an immediate word
call-only ( -- ) A call to this word must not be converted to a jump.
macro ( -- ) This word may be copied as inline code.
nobind ( -- ) When calling this word, don't use the binding table.
optim ( n -- ) Put a nonzero value in this word's optimization field.
C( ( -- string) -- ) Copy 32 bytes to the summary comment of this word.

 


Control Structures:

NAME stack effect Compilation semantics (what the compiler does)
  stack effect Execution semantics (what the resulting code does)
 
IF ( -- addr f ) Lays down code to test a flag and jump forward if flag is zero. Leaves a pointer to the jump instruction's address field.
  ( flag -- ) Executes code between IF and THEN if flag is nonzero.
  Usage: IF...THEN, IF...ELSE...THEN, IF...ELSE...ENDIF
IF ( -- addr f ) Lays down code to test a flag and jump forward if n >= 0. Leaves a pointer to the jump instruction's address field.
  ( n -- ) Executes code between IF and THEN if n < 0.
THEN ( addr f -- ) Resolves the jump instruction's address field left by IF.
  ( -- )  
ENDIF ( addr f -- ) Resolves the jump instruction's address field left by IF. Same as THEN.
  ( -- )  
ELSE ( addr f -- addr' f' ) Resolves the jump instruction's address field left by IF, compiles a forward jump and leaves a pointer to it.
  ( -- )  
AHEAD ( -- addr f ) Same effect as 0 IF
  ( -- )  
BEGIN ( -- addr f ) Marks the beginning of a looping control structure: A future jump instruction will jump to the address left on the stack.
  ( -- )  
  Usage: BEGIN..AGAIN, BEGIN..UNTIL, BEGIN..WHILE..REPEAT
UNTIL ( addr f -- ) Lays down code to test a flag and jump backward.
  ( flag -- ) Quits loop if flag is nonzero.
-UNTIL ( addr f -- ) Lays down code to test n and jump backward.
  ( n -- ) Quits loop if n < 0.
AGAIN ( addr f -- ) Lays down an unconditional backward branch
  ( -- ) Loops forever.
WHILE ( a f -- a f a' f' ) Lays down code to test a flag and jump forward. Leaves a pointer to the jump instruction's address field.
  ( flag -- ) Tests flag, quits loop if zero. Executes words between WHILE and REPEAT if nonzero.
-WHILE ( a f -- a f a' f' ) Lays down code to test a flag and jump forward. Leaves a pointer to the jump instruction's address field.
  ( n -- ) Tests flag, quits loop if n >= 0. Executes words between WHILE and REPEAT if n< 0..
REPEAT ( a f a' f' -- ) Resolves WHILE's jump address and compiles a jump to BEGIN.
  ( -- ) Jump back to BEGIN.
MULTI ( -- a f a' f' ) Lays down code to bump the top of the return stack and jump if negative.
  ( -- | R: x -- x-1 ) Decrements the top of the return stack by 1 and quit the loop if it's negative.
  Usage: MULTI ... REPEAT is equivalent to BEGIN R> 1- DUP >R 0>= WHILE ... REPEAT
  Non-ANS. Uses to do something zero or more times. More efficient than DO..LOOP.
DO ( -- a1 a2 f ) Lays down code for DO, leaves pointers for LOOP to resolve later.
  ( n1 n2 -- ) Sets up loop control parameters with index n2 and limit n1, usually on the return stack.
  Usage: DO..LOOP, DO..+LOOP, ?DO..LOOP, ?DO..+LOOP
  Note: In this implementation, LEAVE and UNLOOP are usually not compilation words, so they aren't defined in the BUILDER vocabulary.
?DO ( -- a1 a2 f ) Same as DO except that the loop doesn't execute at all if n1 = n2.
  ( n1 n2 -- ) Sets up loop control parameters with index n2 and limit n1, usually on the return stack.
LOOP ( a1 a2 f -- ) Lays down code to perform LOOP, resolves DO's jumps.
  ( -- ) Add one to the loop index. If the loop index is then equal to the loop limit, discard the loop parameters and continue execution immediately following the loop. Otherwise continue execution at the beginning of the loop.
+LOOP ( a1 a2 f -- ) Lays down code to perform +LOOP, resolves DO's jumps.
  ( n -- ) Add n to the loop index. If the loop index did not cross the boundary between the loop limit minus one and the loop limit, continue execution at the beginning of the loop. Otherwise, discard the current loop control parameters and continue execution immediately following the loop.
CASE ( -- 0 ) Marks the beginning of a CASE structure
  ( -- )  
  Usage: CASE...OF...ENDOF...OF...ENDOF...ENDCASE
OF ( ... -- ... a f ) Lays down code that compares n1 to n2 and jumps forward if they match.
  ( n1 n2 -- n1 ) If n1=n2, execute words between n1 and n2 and exit case structure.
ENDOF ( a f -- a' f' ) Compiles a forward branch to ENDCASE, resolves the forward branch left by OF.
  ( -- )  
ENDCASE ( 0 ... -- ) Resolves all of ENDOF's forward branches.
  ( x -- ) Drop.
LITERAL ( x -- ) Compiles code to push a number onto the stack.
  ( -- x ) Pushes a number onto the stack.
EXIT ( -- ) Compiles a return instruction or compiles the last call to a jump.
  ( -- ) Exits a definition.
RECURSE ( -- ) Lays down an unconditional call to this word.
  ( -- ) Compiles a static call to the word being defined.
RETRY ( -- ) Lays down an unconditional jump to this word.
  ( -- ) Jumps to the beginning of the word being defined
[static] ( -- ) Same as STATIC but immediate. No code generated.
[dynamic] ( -- ) Same as DYNAMIC but immediate. No code generated.

Image and mode setup:

RAM ( -- ) Causes c, , etc. to compile to and HERE to point to data space.
ROM ( -- ) Causes c, , etc. to compile to and HERE to point to program space.
static ( -- ) Switches to static mode: calls will bypass binding table.
dynamic ( -- ) Switches to dynamic mode: calls will be into binding table.
decimal ( -- ) Set base to 10 on host.
hex ( -- ) Set base to 16 on host.
headers-on ( -- ) Turns on header creation. The evaluator needs header info.
headers-off ( -- ) Turns off headers. Code outside TOF sometimes doesn't need headers.

Word characteristics:

IS ( xt <name> -- ) Assigns xt to <name>. Used with DEFERed words.
ISA ( cfa <name> -- ) Assigns cfa to <name>. Use ISA with :NONAME, which returns a CFA not an XT
CFA ( <name> - cfa ) Gets the cfa (physical address) of a word.
[CFA] ( <name> - cfa ) Gets the cfa of a word while in compile mode.
' ( <name> -- xt ) Gets the xt (execution token) of a word.
['] ( <name> -- ) Gets the xt of a word while in compile mode.
[CHAR] ( <c> -- ) Gets the following ASCII character while in compile mode.

Other:

H# ( <hex_number> -- # ) OFW word to represent a hex number. Split for target's cell width if it's a double.
RESET ( -- ) Asserts the target board's reset line for ½ second. Typically by dropping the DTR line.
end*code ( -- ) Does nothing. See tokenizer.
test{ ( -- )  
}test ( -- )