--------------------------------------------------------------
CORE Variables
--------------------------------------------------------------
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
--------------------------------------------------------------
Macros
--------------------------------------------------------------
1+ 1-
Use: Increment (1+) or Decrement (1-) the TOS.
Take: n
Return: n+1
Notes: Inlines to "inc eax" or "dec eax"
--------------------------------------------------------------
swap
Use: swap the top two items on the stack
Take: x y
Return: y x
Notes: inlined to "xchg eax, [esi]"
--------------------------------------------------------------
drop
Use: drop the tos, setting nos as the new tos
Take: ... n
Return: ...
Notes: inlines to "lodsd"
--------------------------------------------------------------
nip
Use: drop the nos
Take: ... x y
Return: ... y
Notes: inlines to ""
--------------------------------------------------------------
true false
Use: set the value of the flag
Take:
Return:
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:).
Take:
Return:
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.
These words parse the input stream
Example: : foo f: bar ; | compile a call to the forth word
| "bar"
: baz m: bat ; | compile a call to the macro named
| "bat"
--------------------------------------------------------------
[']
Use: Compile the address of a word into the definition
Take:
Return:
Notes: This only searches the forth dictionary, not macros
This is a parsing word
Example: : foo ['] words . ;
--------------------------------------------------------------
s"
Use: Compile a string into a definition
Take:
Return: a #
Notes: The string is placed in a special memory buffer and
the address/count is stored in the definition.
This is a parsing word.
Example: : foo s" hello, world!" type cr ;
--------------------------------------------------------------
."
Use: Same as s" but also compiles in a call to 'type'
Take:
Return:
Notes: Basically this is provided to make displaing strings
easier. It is a parsing word.
--------------------------------------------------------------
:
Use: Define a new entry point
Take:
Return:
Notes: Define a new entry point into a definition.
This is a parsing word
Example: : foo 1 2 : bar + 3 * ;
Notes: In this example, foo puts 1 and then 2 onto the stack
Execution falls through to 'bar' which adds the tos
and nos and then multiplies by 3. Calling 'bar' by
itself will use the values you placed on the stack.
--------------------------------------------------------------
(
Use: Comments in definitions
Take:
Return:
Notes: Allow things like stack comments. Comments are
terminiated by a ) character.
This is a parsing word
Example: : foo ( x -- x+2 ) 2 + ;
--------------------------------------------------------------
>r
Use: Place a value on the return stack
Take: x
Return:
Notes: Drops the TOS
--------------------------------------------------------------
r>
Use: Take the top of the return stack and place on data
stack
Take:
Return: x
Notes: Drops the TORS
--------------------------------------------------------------
r
Use: Place a copy of the TORS on the data stack
Take:
Return: x
Notes: Does not drop the TORS
--------------------------------------------------------------
repeat
Use: Start a structured loop
Take:
Return:
Notes:
--------------------------------------------------------------
again
Use: Repeat an unconditional loop
Take:
Return:
Notes:
Example: : foo 0 repeat dup . 1+ again ;
--------------------------------------------------------------
until
Use: Repeat a counted loop
Take: x
Return: x-1 (see notes)
Notes: When x=0 the loop exits
Decrements tos *before* comparing to 0. This means
that if you say "0 until" an essentially infinite
loop will result.
The counter is the TOS
Example: : foo 10 repeat dup . 1- until cr ;
--------------------------------------------------------------
for
Use: Start a counted loop
Take:
Return:
Notes: This is the same as 'repeat >r'
--------------------------------------------------------------
next
Use: Repeat a counted loop
Take:
Return:
Notes: The counter is on the return stack, not the data
stack.
See the notes on 'until' for more details.
This is the same as 'r> until'
Example: : foo 10 for r . next cr ;
--------------------------------------------------------------
=if
Use: Conditional
Take: x y
Return:
Notes: Continue execution if x and y are equal, otherwise
skip to after 'then'
--------------------------------------------------------------
<>if
Use: Conditional
Take: x y
Return:
Notes: Continue execution if x and y are not equal, else
skip to after 'then'
--------------------------------------------------------------
>if
Use: Conditional
Take: x y
Return:
Notes: Continue execution if x is greater than y,
otherwise skip to after 'then'
--------------------------------------------------------------
<if
Use: Conditional
Take: x y
Return:
Notes: Continue execution if x is less than y,
otherwise skip to after 'then'
--------------------------------------------------------------
?if
Use: Conditional
Take:
Return:
Notes: Continue execution if the flag is true, otherwise
skips to after 'then'
--------------------------------------------------------------
(if)
Use: Conditional (not to be called directly!)
Take: x
Return:
Notes: This is used to implement other conditionals.
--------------------------------------------------------------
Forth Words
--------------------------------------------------------------
swap
Use: Swap the TOS and NOS
Take: x y
Return: y x
Notes: This is also a macro
--------------------------------------------------------------
drop
Use: Drop the TOS
Take: ... x
Return: ...
Notes: This is also a macro
--------------------------------------------------------------
nip
Use: Drop the NOS
Take: ... x y
Return: ... y
Notes: This is also a macro
--------------------------------------------------------------
dup
Use: Duplicate the TOS
Take: x
Return: x x
Notes:
--------------------------------------------------------------
and
Use: Bitwise AND
Take: x y
Return: z
Notes:
--------------------------------------------------------------
or
Use: Bitwise OR
Take: x y
Return: z
Notes:
--------------------------------------------------------------
xor
Use: Bitwise XOR
Take: x y
Return: z
Notes:
--------------------------------------------------------------
not
Use: Bitwise NOT
Take: x
Return: y
Notes:
--------------------------------------------------------------
@ c@
Use: Fetch a value
Take: a
Return: n
Notes: Fetch a cell (@) or byte (c@) from the address
provided
--------------------------------------------------------------
! c!
Use: Store a value
Take: a n
Return:
Notes: Store a cell (!) or byte (c!) to the provided
address
--------------------------------------------------------------
hex
Use: Change the base to hexadecimal
Take:
Return:
Notes: Base 16
--------------------------------------------------------------
decimal
Use: Change the base to decimal
Take:
Return:
Notes: Base 10
--------------------------------------------------------------
binary
Use: Change the base to binary
Take:
Return:
Notes: Base 2
--------------------------------------------------------------
octal
Use: Change the base to octal
Take:
Return:
Notes: Base 8
--------------------------------------------------------------
+
Use: Add TOS and NOS
Take: x y
Return: z
Notes: x+y
--------------------------------------------------------------
-
Use: Subtract NOS from TOS
Take: x y
Return: z
Notes: x-y
--------------------------------------------------------------
*
Use: Multiply TOS and NOS
Take: x y
Return: z
Notes: x*y
--------------------------------------------------------------
/mod
Use: Divide and determine remainder
Take: x y
Return: d r
Notes:
--------------------------------------------------------------
/
Use: Divide NOS by TOS
Take: x y
Return: z
Notes: x/y
--------------------------------------------------------------
mod
Use: Divide NOS by TOS and return the remainder
Take: x y
Return: z
Notes:
--------------------------------------------------------------
negate
Use: Negate the TOS
Take: x
Return: x
Notes: The same as doing -1 *
--------------------------------------------------------------
1+
Use: Add 1 to TOS
Take: x
Return: x+1
Notes: This is also a macro
--------------------------------------------------------------
1-
Use: Subtract 1 from TOS
Take: x
Return: x-1
Notes: This is also a macro
--------------------------------------------------------------
|
Use: Comments
Take:
Return:
Notes: This parses until the end of the line and ignores the
parsed code.
This is a parsing word
This type of comment does not work in definitions
--------------------------------------------------------------
wsparse
Use: Parse ahead until the next whitespace
Take:
Return: a #
Notes: Whitespace is either a space, tab, or EOL character
This is a parsing word
--------------------------------------------------------------
lnparse
Use: Parse ahead until the end of the line
Take:
Return: a #
Notes: EOL can be a cr or lf character
This is a parsing word
--------------------------------------------------------------
>>
Use: Shift right
Take: x y
Return:
Notes:
--------------------------------------------------------------
<<
Use: Shift left
Take:
Return:
Notes:
--------------------------------------------------------------
here
Use: Return the top of the heap
Take:
Return: 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
Take: x
Return:
Notes: Allocate X bytes of memory
--------------------------------------------------------------
cells
Use: Convert a number of cells to the size in bytes
Take: x
Return: x*4
Notes: Cells are 4 bytes (a dword on x86) in size
--------------------------------------------------------------
cell+
Use: Increase TOS by the size of a cell
Take: x
Return: x+4
Notes: Cells are 4 bytes (a dword on x86) in size
--------------------------------------------------------------
later
Use: Delay execution of a word until the caller finishes
Take:
Return:
Notes: This is tricky to learn, but very powerful
--------------------------------------------------------------
exit,
Use: Compile an exit instruction
Take:
Return:
Notes: Compiles a RET ($c3) on x86
--------------------------------------------------------------
create:
Use: Create a new dictionary entry
Take:
Return:
Notes: Does a 'wsparse entry' to create the entry
This is a parsing word
--------------------------------------------------------------
variable
Use: Create a variable
Take:
Return:
Notes: This creates a variable with an initial value of 0
This is a parsing word
--------------------------------------------------------------
variable:
Use: Create a variable
Take: x
Return:
Notes: This creates a variable with an initial value of 'x'
This is a parsing word
--------------------------------------------------------------
rot
Use: Rotate the stack
Take: x y z
Return: y z x
Notes:
--------------------------------------------------------------
-rot
Use: Rotate the stack twice
Take: x y z
Return: z x y
Notes:
--------------------------------------------------------------
tuck
Use: Tuck a copy of the TOS under the NOS
Take: ... x y
Return: ... y x y
Notes:
--------------------------------------------------------------
over
Use: Place a copy of the NOS over the TOS
Take: ... x y
Return: ... x y x
Notes:
--------------------------------------------------------------
2drop
Use: Drop the top two entries on the stack
Take: ... x y
Return: ...
Notes:
--------------------------------------------------------------
2dup
Use: Duplicate the top two entries on the stack
Take: ... x y
Return: ... x y x y
Notes: The same as doing 'over over'
--------------------------------------------------------------
'
Use: Obtain the address of a word
Take:
Return: a
Notes: This does not recognize macros
This is a parsing word
--------------------------------------------------------------
alias
Use: Bind an address to a name
Take: a
Return:
Notes: Using this with loc: and ;loc allows localized
fatoring
This is a parsing word
--------------------------------------------------------------
execute
Use: Execute the provided address
Take: a
Return:
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
Take: x
Return:
Notes:
--------------------------------------------------------------
constant
Use: Create a symbolic constant
Take: x
Return:
Notes: Essentially the same as ": name value ;"
This is a parsing word
--------------------------------------------------------------
0;
Use: Exit a word if the TOS is 0
Take: x
Return: x (if not zero)
(drops tos if it is 0)
Notes: Useful in loops
--------------------------------------------------------------
list
Use: Array holding the addresses of 'last' during a loc:
and ;loc pairing
Take:
Return: a
Notes: Not intended for use by words other than loc: and
;loc
--------------------------------------------------------------
loc:
Use: Start a locally factored definition
Take:
Return:
Notes: You can nest up to four levels deep.
--------------------------------------------------------------
;loc
Use: End a locally factored definition
Take:
Return:
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
Take: a # b
Return:
Notes: b is the byte to fill memory with
--------------------------------------------------------------
move
Use: Copy a region of memory from one location to another
Take: s d #
Return:
Notes: s is source, d is dest, # is the number of bytes to
move
--------------------------------------------------------------
pad
Use: Return the address of the PAD
Take:
Return: a
Notes: Strings are initially placed in PAD
--------------------------------------------------------------
>pad
Use: Copy a string to the PAD
Take: a #
Return: a #
Notes: Destroys the original contents of PAD
--------------------------------------------------------------
"
Use: Create a temporary string
Take:
Return: a #
Notes: The string is placed in PAD using >PAD
--------------------------------------------------------------
."
Use: Display a string
Take:
Return:
Notes: The string is placed in PAD before displaying it
--------------------------------------------------------------
$,
Use: Inline a string into the definition of the current
word.
Take: addr count
Return:
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
Take: a #
Return: a
Notes: This replaces zt-make and zt-free from the 7.x series
--------------------------------------------------------------
cr
Use: Next output will be on the next line
Take:
Return:
Notes:
--------------------------------------------------------------
space
Use: Display a space
Take:
Return:
Notes:
--------------------------------------------------------------
.
Use: Display a signed number
Take: n
Return:
Notes:
--------------------------------------------------------------
u.
Use: Display an unsigned number
Take: n
Return:
Notes:
--------------------------------------------------------------
words
Use: Display all currently defined words in the current
dictionary
Take:
Return:
Notes:
--------------------------------------------------------------