Starting Forth
Leo Brodie

Chapter 0 Introductions

human -> machine
puppeteer -> wooden control -> strings -> marionette
programmer -> high-level languages -> machine languages -> computer

Forth is
  a high-level language
  an assembly language
  an operating system
  a set of development tools
  a software design philosophy

Forth is
  fast
  compact
  transportable
  productive

Chapter 1 Fundamental Forth

( Large letter F )
 : STAR 42 EMIT ;
 : STARS   0 DO  STAR  LOOP ;
 : MARGIN  CR 30 SPACES ;
 : BLIP MARGIN STAR ;
 : BAR  MARGIN 5 STARS ;
 : F    BAR BLIP BAR BLIP BLIP CR ;

Word name consists any character except
   return
   backspace
   space

: xxxx yyy ; ( -- )           Creates a new definition with the name xxx, consisting of word or words yyy.
CR           ( -- )           Performs a carriage return and line feed at your terminal.
SPACES       ( n -- )         Prints the given number of blank spaces at your terminal.
SPACE        ( -- )           Prints one blank space at your terminal.
EMIT         ( c -- )         Transmits a character to the output device.
." xxx"      ( -- )           Prints the character string xxx at your terminal. The " character terminates the string.
+            ( n1 n2 -- sum ) Adds.
.            ( n -- )         Prints a number, followed by one space.

Review of Terms
  Compile
  Dictionary
  Execuate
  Extensibility
  Glossary
  Infix notation
  Input stream
  Interpret
  LIFO
  Postfix notation
  Stack
  Stack overflow
  Stack underflow
  Word

Chapter 2 How to Get Results

Integer-arithmetic operators
  + ( n1 n2 -- sum )  Adds.
  - ( n1 n2 -- diff ) Subtracts (n1-n2).
  * ( n1 n2 -- prod ) Multiplies.
  / ( n1 n2 -- quot ) Divides (n1/n2).

To convert to postfix, simply move the operator to the end of the expression.

Division operators
  /MOD ( n1 n2 -- rem quot ) Divides. Returns the remainder and quotient.
  MOD ( n1 n2 -- rem ) Returns the remainder from division.

Stack manipulation operators
  SWAP ( n1 n2 -- n2 n1 ) Reverses the top two stack items.
  DUP  ( n -- n n ) Duplicates the top stack item.
  OVER ( n1 n2 -- n1 n2 n1 ) Makes a copy of the second item and pushes it on top.
  ROT  ( n1 n2 n3 -- n2 n3 n1 ) Rotates the third item to the top.
  DROP ( n -- ) Discards the top stack item.

When writing equations in Forth, it's best to "factor them out" first.

Double
  2SWAP ( d1 d2 -- d2 d1 ) Reverses the top two pairs of numbers.
  2DUP  ( d -- d d ) Duplicates the top pair of numbers.
  2OVER ( d1 d2 -- d1 d2 d1 ) Makes a copy of the second pair of numbers and pushes it on top.
  2DROP ( d -- ) Discards the top pair of numbers.

Review of Terms
  Double-length numbers
  Single-length numbers

Chapter 3 The Editor (and Staff)

You can define the same word more than once in different ways — only the most recent definition will be executed.

USE xxx          ( -- ) Designate OS text file xxx as the "Forth disk."
LIST             ( n -- ) Lists a disk block.
LOAD             ( n -- ) Loads a disk block (compiles or executes).
( xxx)           ( -- ) Causes the string xxx to be ignored by the text interpreter. The character ) is the delimiter.
UPDATE           ( -- ) Marks the most recently referenced block as modified. The block will later be automatically transferred
                        to mass storage if its buffer is needed to store a different block or if FLUSH is executed.
EMPTY-BUFFERS    ( -- ) Marks all block buffers as empty without necessarily affecting their actual contents.
                        Updated blocks are not written to mass storage.
BLOCK            ( u -- addr ) Leaves the address of the first byte in block u. If the block is not already in memory,
                               it is transferred from mass storage into whichever memory buffer has been least recently accessed.
                               If the block occupying that buffer has been updated (i.e., modified), it is rewritten onto
                               mass storage before block u is read into the buffer.
INCLUDE xxx      ( -- ) Load the text file xxx (compiles or executes).
FORGET xxx       ( -- ) Forgets all definitions back to and including xxx.
MARKER xxx       ( -- ) Creates a word xxx which, when executed, restores the dictionary to the state it had just prior to
                        the definition of xxx. In particular, remove xxx and all subsequent word definitions.

Review of Terms
  Block
  Buffer
  Null definition
  Pointer
  Source text

Chapter 4 Decisions, Decisions…

IF   xxx   IF: ( f -- ) If f is true (non-zero) executes xxx; otherwise executes yyy;
ELSE yyy                continues execution with zzz regardless. The phrase ELSE yyy is optional.
THEN zzz
=          ( n1 n2 -- f ) Returns true if n1 and n2 are equal.
-          ( n1 n2 -- n-diff ) Returns true (i.e., the non-zero difference) if n1 and n2 are not equal.
<          ( n1 n2 -- f ) Returns true if n1 is less than n2.
>          ( n1 n2 -- f ) Returns true if n1 is greater than n2.
0=         ( n -- f ) Returns true if n is zero (i.e., reverse the truth value).
0<         ( n -- f ) Returns true if n is negative.
0>         ( n -- f ) Returns true if n is positive.
AND        ( n1 n2 -- and ) Returns the logical AND.
OR         ( n1 n2 -- or ) Returns the logical OR.
?DUP       ( n -- n n ) or ( 0 -- 0 ) Duplicates only if n is non-zero.
ABORT" xx" ( f -- ) If the flag is true, types out an error message, followed by the text.
                    Also clears the stacks and returns control to the terminal. If false, takes no action.
?STACK     ( -- f ) Returns true if a stack underflow condition has occurred.

Review of Terms
  Abort
  "And" decision
  Branching
  Comparison operator
  Flag
  Logic
  Nesting
  "Or" decision

Chapter 5 The Philosophy of Fixed Point

Quickie Operators
  1+ ( n -- n+1 ) Adds one.
  1- ( n -- n-1 ) Subtracts one.
  2+ ( n -- n+2 ) Adds two.
  2- ( n -- n-2 ) Subtracts two.
  2* ( n -- n*2 ) Multiplies by two (arithmetic left shift).
  2/ ( n -- n/2 ) Divides by two (arithmetic right shift).

Miscellaneous Math Operators
  ABS    ( n -- |n| ) Returns the absolute value.
  NEGATE ( n -- -n ) Changes the sign.
  MIN    ( n1 n2 -- n-min ) Returns the minimum.
  MAX    ( n1 n2 -- n-max ) Returns the maximum.

The Return Stack
  >R ( n -- ) Takes a value off the parameter stack and pushes it onto the return stack.
  R> ( -- n ) Takes a value off the return stack and pushes it onto the parameter stack.
  I  ( -- n ) Copies the top of the return stack without affecting it.
  R@ ( -- n ) Copies the top of the return stack without affecting it.
  J  ( -- n ) Copies the third item of the return stack without affecting it.

Scaling operators
  */    ( n1 n2 n3 -- n-result ) Multiplies, then divides (n1*n2/n3). Uses a double-length intermediate result.
  */MOD ( n1 n2 n3 -- n-rem n-result ) Multiplies, then divides (n1*n2/n3). Returns the remainder and the quotient.
                                       Uses a double-length intermediate result.

Rational Approximations to Various Constants

Number                       Approximation           Error
π = 3.141 ...                355 / 113               8.5 x 10-8
π = 3.141 ...                1068966896 / 340262731  3.0 x 10-18
√2 = 1.414 ...               19601 / 13860           1.5 x 10-9
√3 = 1.732 ...               18817 / 10864           1.1 x 10-9
e = 2.718 ...                28667 / 10546           5.5 x 10-9
√10 = 3.162 ...              22936 / 7253            5.7 x 10-9
12√2 = 1.059 ...             26797 / 25293           1.0 x 10-9
log(2) / 1.6384 = 0.183 ...  2040 / 11103            1.1 x 10-8
ln(2) / 16.384 = 0.042 ...   485 / 11464             1.0 x 10-7

Review of Terms
  Double-length intermediate result
  Fixed-point arithmetic
  Floating-point arithmetic
  Parameter stack
  Return stack
  Scaling

Chapter 6 Throw It For a Loop

DO ... LOOP      DO: ( limit index -- ) Sets up a finite loop, given the index range.
                 LOOP: ( -- )
DO ... +LOOP     DO: ( limit index -- ) Like DO … LOOP except adds the value of n (instead of always one) to the index.
                 +LOOP: ( -- )
LEAVE            ( -- ) Terminate the loop immediately.
BEGIN ... UNTIL  UNTIL: ( f -- ) Sets up an indefinite loop which ends when f is true.
BEGIN xxx        WHILE: ( f -- ) Sets up an indefinite loop which always executes xxx and also yyy if f is true.
WHILE yyy                        Ends when f is false.
REPEAT
U.R              ( u width -- ) Prints the unsigned single-length number, right-justified within the field width.
PAGE             ( -- ) Clears the terminal screen and resets the terminal’s cursor to the upper left-hand corner.
QUIT             ( -- ) Terminates execution for the current task and returns control to the terminal.

Review of Terms
  definite loop
  infinite loop
  indefinite loop

Chapter 7 A Number of Kinds of Numbers

Shift Operators
  2*     ( n -- n*2 ) Multiplies by two (arithmetic left shift)
  2/     ( n -- n/2 ) Divides by two (arithmetic right shift)
  LSHIFT ( n u -- n*2^u ) Logical left shift over u positions
  RSHIFT ( n -- n/2^-u ) Logical right shift over u positions

Unsigned Operators
  U.     ( u -- ) Prints the unsigned single-length number, followed by a space.
  UM*    ( u1 u2 -- ud ) Multiplies two single-length numbers. Returns a double-length result. All values are unsigned.
  UM/MOD ( ud u1 -- u2 u3 ) Divides a double-length by a single-length number. Returns a single-length quotient u2 and remainder u3.
                            All values are unsigned.
  U<     ( u1 u2 -- f ) Leaves true if u1 < u2, where both are treated as single-length unsigned integers.

Number Bases
  HEX     ( -- ) Sets the base to sixteen.
  OCTAL   ( -- ) Sets the base to eight (available on some systems).
  DECIMAL ( -- ) Returns the base to ten.

D. ( d -- ) Prints the signed double-length number, followed by one space.

: UD.  <# #S #> TYPE ;

Number Formatting Operators
  <#      Begins the number conversion process. Expects the unsigned double-length number on the stack.
  #       Converts one digit and puts it into an output character string. # always produces a digit — if you're out of
          significant digits, you'll still get a zero for every #.
  #S      Converts the number until the result is zero. Always produces at least one digit (0 if the value is zero).
  c HOLD  Inserts, at the current position in the character string being formatted, a character c whose ASCII value is on
          the stack. HOLD (or a word which uses HOLD) must be used between <# and #>.
  SIGN    Inserts a minus sign in the output string if the top of stack is negative. Usually used with ROT immediately
          before #> for a leading minus sign.
  #>      Completes number conversion by leaving the character count and address on the stack
          (these are the appropriate arguments for TYPE).

Stack effects for number formatting
  phrase              stack
  <# ... #>           ( ud -- addr u ) double-length unsigned
  <# ... ROT SIGN #>  ( n |d| -- addr u ) double-length signed (where n is the high-order cell of d and |d| is the absolute
                                          value of d).

Key
  n, n1, ... = single-length signed
  d, d1, ... = double-length signed
  u, u1, ... = single-length unsigned
  addr = address
  c = ASCII character value

Number Formatting — Signed and Single-length
  Number to be printed     Precede <# by
  double-length, unsigned  (nothing needed)
  double-length, signed    TUCK DABS (to save the sign in the third stack position for ROT SIGN)
  single-length, unsigned  0 (to give a dummy high-order part)
  single-length, signed    DUP ABS 0 (to save the sign)

Double-length Operators
  D.R      ( d width -- ) Prints the signed double-length number, right-justified within the field width.
  D+       ( d1 d2 -- d-sum ) Adds two double-length numbers.
  D-       ( d1 d2 -- d-diff) Subtracts two double-length numbers (d1-d2).
  DNEGATE  ( d -- -d) Changes the sign of a double-length number.
  DMAX     ( d1 d2 -- d-max ) Returns the maximum of two double-length numbers (d1-d2).
  DMIN     ( d1 d2 -- d-min ) Returns the minimum of two double-length numbers (d1-d2).
  D=       ( d1 d2 -- f ) Returns true if d1 and d2 are equal.
  D0=      ( d -- f ) Returns true if d is zero.
  D<       ( d1 d2 -- f ) Returns true if d1 is less than d2.
  DU<      ( ud1 ud2 -- f ) Returns true if ud1 is less than ud2. Both numbers are unsigned.

Mixed-length Operators
  M+      ( d n -- d-sum ) Adds a double-length number to a single-length number. Returns a double-length result.
  SM/REM  ( d n1 -- n2 n3 ) Divide d by n1, giving the symmetric quotient n3 and the remainder n2. Input and output
                            stack arguments are signed. An ambiguous condition exists if n1 is zero or if the quotient
                            lies outside the range of a single-cell signed integer.
  FM/MOD  ( d n1 -- n2 n3 ) Divide d by n1, giving the floored quotient n3 and the remainder n2. Input and output
                            stack arguments are signed. An ambiguous condition exists if n1 is zero or if the quotient
                            lies outside the range of a single-cell signed integer.
  M*      ( n1 n2 -- d-prod ) Multiplies two single-length numbers. Returns a double-length result. All values are signed.
  M*/     ( d n1 n2 -- d-result ) Multiplies a double-length number by a single-length number and divides the
                                  triple-length result by a single-length number (d*n/n). Returns a double-length result.
                                  All values are signed.

The number's binary value depends on the number base at the time you compile the definition.

Review of Terms
  Arithmetic left and right shift
  Logical left and right shift
  ASCII
  Binary
  Byte
  Cell
  Decimal
  Hexadecimal
  Literal
  Mask
  Number formatting
  Octal
  Sign bit high-order bit
  Two's complement
  Unsigned number
  Unsigned single-length number
  Word
  Integer division
  Floored division
  Symmetric division

Chapter 8 Variables, Constants, and Arrays

In Forth, variables are appropriate for any value that is used inside a definition which may need to change
at any time after the definition has already been compiled.

BASE ( n -- ) A variable which contains the value of the number base being used by the system.

CONSTANT xxx   ( n -- )      Creates a constant named xxx with the value n;
         xxx:  ( -- n )      the word xxx returns n when executed.
VARIABLE xxx   ( -- )        Creates a variable named xxx;
         xxx:  ( -- addr )   the word xxx returns its address when executed.
!              ( n addr -- ) Stores a single-length number into the address.
@              ( addr -- n ) Replaces the address with its contents.
?              ( addr -- )   Prints the contents of the address, followed by one space.
+!             ( n addr -- ) Adds a single-length number to the contents of the address.

2CONSTANT xxx  ( d -- )      Creates a double-length constant named xxx with the value d;
          xxx: ( -- d )      the word xxx returns d when executed.
2VARIABLE xxx  ( -- )        Creates a double-length variable named xxx;
          xxx: ( -- addr )   the word xxx returns its address when executed.
2!             ( d addr -- ) Stores a double-length number into the address.
2@             ( addr -- d ) Returns the double-length contents of the address.

CREATE xxx     ( -- )        Creates a dictionary entry (head and code pointer only) named xxx;
       xxx:    ( -- addr )   the word xxx returns its address when executed.
,              ( n -- )      Compiles n into the next available cell in the dictionary.
ALLOT          ( n -- )      Adds n bytes to the body of the most recently defined word.

ERASE ( addr n -- )   Stores zeroes into n bytes of memory, beginning at the address.
FILL  ( addr n b -- ) Fills n bytes of memory, beginning at the address, with value b.
C!    ( b addr -- )   Stores an 8-bit value into the address.
C@    ( addr -- b )   Fetches an 8-bit value from the address.
C,    ( b -- )        Compiles b into the next available byte in the dictionary.
DUMP  ( addr u -- )   Displays u bytes of memory, starting at the address.

Key
  n, n1, ... single-length signed
  d, d1, ... double-length signed
  u, u1, ... single-length unsigned
  ud, ud1, ... double-length unsigned
  addr address
  c ASCII character value
  b 8-bit byte
  f Boolean flag

Review of Terms
  Array
  Constant
  Factoring
  Fetch
  Initialize
  Offset
  Store
  Variable

Chapter 9 Under the Hood

' xxx   ( -- addr )           Attempts to find the execution token of xxx
                              (the word that follows in the input stream) in the dictionary.
[']     compile time ( -- )   Used only in a colon definition, compiles the execution token
        run time ( -- addr )  of the next word in the definition as a literal.'

Definition
  name field
  link field
  code pointer field
  data field

EXECUTE ( xt -- ) Executes the dictionary entry whose execution token is on the stack.
EXIT    ( -- ) When compiled within a colon definition, terminates execution at that point.
QUIT    ( -- ) Clears all stacks and returns control to the terminal. No message is given.

HERE    ( -- addr ) Returns the next available dictionary location.
PAD     ( -- addr ) Returns the beginning address of a scratchpad area used to hold character strings
                    for intermediate processing.
SP@     ( -- addr ) User variable. Return the address of the top of the stack before SP@ is executed.
SP0     ( -- addr ) User variable. Contains the address of the bottom of the parameter stack.

TIB     Contains the address of the start of the terminal input buffer.
#TIB    Contains the size of the terminal input buffer.
SCR     A pointer to the current block number (set by LIST).
BASE    Number conversion base.
CP      Dictionary pointer. Pointer to the next available byte.
>IN     A pointer to the current position in the input stream.
BLK     If non-zero, a pointer to the block being interpreted by LOAD.
        A zero indicates interpretation from the terminal (via the input message buffer).

Variables
  System variables contain values used by the entire Forth system.
  User variables contain values that are unique for each task.
  Regular variables can be accessible either system-wide or within a single task only.

Review of Terms
  Address interpreter
  Body
  Cfa
  Code pointer field
  Defining word
  Head
  Input message buffer
  Link field
  Name field
  Pad
  Data field
  Run-time code
  System variable
  Task
  User variable
  Vectored execution