Forth on Robots/Forth Dictionary
From HBRC WIki
This page provides a dictionary/encyclopedia for the basic Forth words you need to get Forth up and running. The intent is to provide a small, grouped dictionary reference to basic Forth kernal words in a manner that is easy to follow and provides the data you need to understand what is going on.
This dictionary is intended to be short and basic, rather than comprehensive and complete. The choice of important core words is subjective (Dave Wyland), by necessity. In any Forth implementation, there will typically be other, working words created to get the job done and/or reflecting the coding style of the programmer.
A Forth dictionary is essential to using and understanding Forth. You need to know the words that are available on boot-up, what they do and to some degree how they do it.
Another useful piece of documentation would be the execution tree for the Forth interpreter, the Forth program that comes up at boot-up. A Forth program is a deeply nested tree structure with primitive Forth words (assembly language) at the leaves. This can be nicely shown graphically as a web page of nested links or a file-tree graphic. Another sub-project.
Forth Dictionary
- Word groups and vocabularies - description
- Current and Context
- Application and Edit vocabularies
- Words grouped by function: definition of actions performed
- Stack comment notation
- Code comments notation
Dictionary Structure
- Dictionary as a stack - growing and shrinking
- Linked list structure
- Dictionary header - integrated versus separated headers
- Header flags: Immediate, hidden
- Writing to the flash: Page write buffering
- Writing dictionary and code words in flash
- Printing the dictionary - Debugging
Comment Structures
Comment structures allow the programmer to comment the code
Comments
There are two forms of comments: comments enclosed in parentheses "( comment)" and end-of-line comments "\ comment".
The structure for comments enclosed in parentheses is:
- a leading left parenthesis, "(",
- one or more spaces
- the comment string
- an ending right parenthesis: ")"
- Example: "( This is a comment string)"
The structure for end of line comments is:
- a leading backslash character "\",
- one or more spaces
- the comment string
- a carriage return/line feed marking the end of the line of text.
- Example: " THIS ARE FORTH WORDS \ these are comment words"
Stack diagrams
A Forth word expects parameters on the stack, and it can take or put items on the stack. A stack diagram shows a picture of the stack before and after the word executes. It shows the items which the word expects to see at at the entry to the word and the items that will be returned on the stack at the exit of the word. The stack diagram is in the form of a parentheses comment, as follows:
- A leading comment parenthesis and space
- Words describing each element on the stack at entry, TOS on the right (ANSI standard)
- A space and two hyphens: " -- "
- Words describing each element on the stack at exit, TOS on the right (ANSI standard)
- The closing comment parenthesis.
- Example: ( TOS-2 TOS-1 TOS -- TOS-1 TOS) Note: this pops one element from the stack
Every Forth word in a word glossary should have a stack notation comment to indicate the stack conditions at entry and exit.
Forth Execution Core Words: 27
These are the basic words of the Forth kernel. Many of them are written in assembly language, unique to the CPU on which they are run. You will need more words for a full Forth to compile new words, etc.
Data Stack Words: 8
These words set up the data stack and manipulate words on the data stack.
S0 - Initialize Data Stack pointer
SP0 - Data Stack Pointer initial value
S@ - Get the Data Stack Pointer value
DUP - Push a copy of the top of stack (TOS)
OVER - Push a copy of the value under TOS (TOS-1)
DROP - Pop the TOS
SWAP - Exchange TOS and TOS-1
LITERAL - Push constant following the word LITERAL
Used in compiling a number. When the interpreter finds a number while compiling a compound word, it places a LITERAL word followed by the number value in the definition being compiled.
Return Stack Words: 3
These words manipulate words on the data stack. The return stack can (logically) only be set up by a cold start or a restart.
>R - Pop Data Stack, push onto Return Stack
R> - Pop Return Stack, push onto Data Stack
R@- Get Copy of top of Return Stack to Data Stack
Push the TOS of the return stack onto the Data Stack and pop the return stack.
Arithmetic Words: 5
The arithmetic words perform arithmetic operations on the data stack elements.
Add (+) - Add TOS to TOS-1, pop TOS
NEGATE - Negate TOS (2's complement)
Subtract (-) - Subtract TOS from TOS-1, pop TOS
EQZ - Set TOS = 1 if TOS =0
TEST - Set CPU flags For TOS value
Used in assembly code. Sets the micro-controller flags (zero, negative) to correspond to the TOS.
Logic Words: 4
The logic words perform logical operations on the data stack elements.
AND - AND TOS to TOS-1, pop TOS
OR - OR TOS to TOS-1, pop TOS
XOR - XOR TOS to TOS-1, pop TOS
INVERT - Invert TOS (1's complement)
Logically inverts the bits in the TOS word.
Bit Manipulation Words: 3
The bit manipulation words perform shifting operations on the TOS.
SLA - Shift TOS left 1 bit, insert 0
SRA - Shift TOS right 1 bit, insert sign
ROTATE - Rotate TOS right one bit
Rotates the TOS right one bit.
Memory Access Words: 4
The memory access operations perform memory read and write operations.
The words shown are for a single memory. Micro-controllers often have several different types of memories. For example, the AVR has a flash program memory, an SRAM data memory and an EEPROM non-volatile data memory. Additional words will be required to access these memories, or the 3 memory types will have to be integrated into a single address space, with the sorting out done by the memory access words.
A single address space approach can work well for the AVR Atmega328 because the sum of the three memory sizes (32 KB flash, 2 KB SRAM, 1 KB EEPROM) is less than 64K bytes. This means that the tree memories can be mapped to a 64 KB address space accessed by a single, 16-bit address.
@ - Memory Read Word: Replace address on TOS with memory data
C@ - Memory Read Byte: Replace address on TOS with memory data
! - Memory Write Word: Address on TOS, Data at TOS-1
C! - Memory Write Byte: Address on TOS, Data at TOS-1
.
Forth Core Words for a Full Forth
Forth core words allow full Forth operation of interpreting words and defining new words from the keyboard.
Utility Words: 12
Utility words are handy subroutines. A utility word does a common function that would otherwise require 2 or more words. Utility words save space and reduce code size. Their choice is arbitrary, by utility in whatever code you are writing.
0 Push constant 0
1 Push constant 1
1+ Increment TOS
1- Decrement TOS
+! Add TOS-1 to Memory at address on TOS
1+! Increment Memory by 1at address on TOS
2+! Increment Memory by 2 at address on TOS
1-! Decrement Memory by 1 at address on TOS
2-! Decrement Memory by 2 at address on TOS
U* Unsigned multiply: TOS * TOS-1 => Product on TOS, TOS-1
* Signed multiply: TOS * TOS-1 => Product on TOS, TOS-1
/ Divide: TOS-1 & TOS-2 divided by TOS => Quotient on TOS, remainder on TOS-1
.
Compiling Word Set: 15
Compiling words generate new words in the dictionary.
Memory Allocation Words: 2
In micro-controllers, both program flash and data SRAM have to be allocated.
ALLOT - Allocate N bytes of program memory, N on TOS
RAMALLOT - Allocate N bytes of RAM memory, N on TOS
Allocate N bytes of RAM memory, N on TOS.
Dictionary Words: 8
These words create dictionary headers for new words and put code words in the dictionary for the new words to execute.
COMMA - Put TOS into the dictionary space at HERE
CREATE - Create a name header in the dictionary
FIND - Find a name in the dictionary
HERE - Pointer to next empty word in dictionary
FORTH - Pointer to start of Forth Kernal in dictionary
WORDS - Prints the word names in the current dictionary
LATEST - Pointer to last name in dictionary
ALIAS - Calling a word by another name=
It is sometimes useful to call a word by another name. The ALIAS word allows this, as follows:
ALIAS <new-name> <existing-name>
For example
ALIAS COUNT TEMP
This creates a new name, COUNT , that is an alias for TEMP. ALIAS generates a dictionary header for COUNT and but uses a copy of the execution address of TEMP as its execution address. Executing COUNT will cause the execution of the code for TEMP, exactly as though TEMP were called. ALIAS can be applied to most words, with some care required for compiling words. It is particularly useful for renaming variables.
Compiling Words: 7
Compiling words actually do the compiling.
CONSTANT - Compiles a named constant
VARIABLE - Compiles the address constant for a named variable
ARRAY - Compiles the address constant for a named, allocated array
COLON - Begins a compound word definition
SEMICOLON - Ends a compound word definition
BUILDS - Defines what what a compiling word does at compile time.
Functionally equivalent to CREATE.
DOES - Defines what a compiled word does at execution time
Puts the address of the execution code in the dictionary header for the word being crated.
Compiling Words for Conditionals and Loops: 10
Conditional Words: 4
Conditionals have the forms of:
<test code> IF <Execute code for true> ENDIF
Compiling this structure generates:
<test code> 0BRANCH ^address after "true" code^ <execute code for true>
The 0BRANCH test the TOS for zero. If the TOS is non-zero, execution continues with <execute code if true>. If the TOS is zero, OBRANCH jumps past the <execute if true> code.
<test code> IF <execute code if true> ELSE <execute code if false> ENDIF
Compiling this structure generates:
<test code> 0BRANCH ^address of execute code if false^ <Execute code for true> JUMP ^address after "false" code^ <execute code if false>
The 0BRANCH test the TOS for zero. If the TOS is non-zero, execution continues with <execute code if true>. After it is executed, the code jumps to the next instruction after <execute code if false>. If the TOS is zero, OBRANCH jumps past the <execute if true> code to the start of the <execute if false code.
0BRANCH - Jump to address if TOS is zero
This is used by conditional (IF, etc.) and loop (DO, etc.)
Loop Words: 6
Begin-Until Loop Words: BEGIN, UNTIL, REPEAT and EXIT
Begin-Until loops have the form: BEGIN <execute code> <test code> UNTIL and BEGIN <execute code> REPEAT.
In BEGIN-UNTIL loops, UNTIL tests the TOS. If it is zero, the loop repeats; if it is non-zero, the loop exits.
In BEGIN-REPEAT loops, the code executed continually unless an EXIT instruction is executed in the loop
Executing an EXIT instruction will cause the code to exit the loop.
While-Repeat Loop Words: WHILE, REPEAT
While-Repeat loops have the form: <test code> WHILE <execute code> <test code> REPEAT.
In While-Repeat loops, WHILE tests the TOS. If it is zero, the loop repeats; if it is non-zero, the loop exits.
Interpreter Words: 17
Interpreter words read in the command line and execute it. They receive keyboard input and print result outputs.
Text I/O Words: 7
Text I/O words receive keystrokes from the keyboard and print characters to the output.
KEY - Wait for and get a keyboard character
KEY? - Test for keyboard character waiting
EMIT - Print a character
DOT - Print TOS as a number
CRLF = Print a carriage return and line feed
SPACES - Print N spaces, N on TOS
DOTQUOTE ('") - Print literal text string constant
Interpreting Words: 8
Interpreting words get the input command line and interpret it.
GETLINE - Get a line of text terminated by a CRLF
WORD - Get the next word from TIB to PAD
TIB - Address of the Terminal Input Buffer
PAD - Address of the string work area
NUMBER - Convert text string to a number
EXECUTE - Execute the word address on TOS
INTERPRET - Gets words form the keyboard and interprets them
Uses GETLINE to get the words.
QUIT - Interpreting loop
QUIT is the "Main" program word: An infinite loop around INTERPRET. If INTERPRET fails by finding a word it cannot find or convert, it falls through to QUIT. QUIT issues an error message, restores the stack and dictionary to its prior stat and loops back to INTERPRET.
String Words: 2
String words move and print character strings.
CMOVE - Move a block of text
QUOTE - Create a named text string constant
.
Debug Words
These words are not part of the Forth Core, but you will find them very useful, indeed
