dsforth: added "(TR-CAT)"

[urasm.git] / dsforth / forth.txt

PARTS OF THE ORIGINAL MANUAL, CHANGED A LITTLE

2.2 Types of Numbers

FORTH is a typeless language. There is no distinction between a number
and a character for example. Things on the stack are taken by a word and
interpreted as that word sees fit. Some of the more common
interpretations, other than the normal 16 bit signed numbers (range
-32768 to 32767) which have been used, are:

Unsigned:
range 0 to 65535. The word 'U.' acts like `.' but it assumes that the
number is unsigned rather than signed.

Double precision:
The top two numbers on the stack are interpreted as a 32 bit number,
either signed or unsigned. The top number is taken as the high 16 bits.
The second number is taken as the low 16 bits. To put a 32 bit number
onto the stack type the number with a decimal point somewhere in the
number. The system variable DPL contains the number of digits following
the decimal point, in case it is important.

  70.000 . . DPL @ .

will print 1 4464 3 ok. The 32 bit number 70000 (not 70) is put onto the
stack as two numbers. The first '.' prints the top half as a signed
number. The bottom half is then printed (note 70000 = 1 x 2^16 + 4464).
The contents of DPL are 3 since there are 3 digits after the decimal
point.

The words U* U/MOD M* M/ and M/MOD are mixed mode versions of * / and
/MOD where the operands and results are of different types.

Byte:
Sometimes only 8 bit numbers are required, for instance to represent a
character. They are represented on the stack by 16 bit numbers with the
8 highest bits zero. 'C@' and 'C!' fetch and store only a single byte at
a time.

Flags:
To make decisions, the values true and false are needed. For instance
  2 3 = .       prints 0 (false), whereas
  3 3 = .       prints 1 (true).

In fact any non-zero number is treated as true. (So,'-' can be used for
<>, since x - y = 0 (false) only if x = y.)
Other comparisons are:
  <  U<  0< (equivalent to 0 <) and 0= (equivalent to 0 =).

'NOT' changes a true flag to false and vice versa. (This is actually
equivalent to 0=.)


2.4 Control Structures

Added 'IFNOT'.

Added 'OTHERWISE':
  CASE
    8 OF ." This is 8" CR ENDOF
    12 OF ." This is 12" CR ENDOF
    99 OF ." This is 99" CR ENDOF
    OTHERWISE ." The number is: " . CR ENDOF
  ENDCASE



2.7 The RAM disc

Destroyed.


2.8 The Graphics Routines

Destroyed.


2.11 Miscellaneous Additions

The final changes to the standard are:

f LINK
Destroyed.

UDG
Destroyed.


CHAPTER 3. ADVANCED FEATURES OF FORTH

3.0 Saving an extended Dictionary

Broken.


CHAPTER 4. THE DISC EDITOR

Not here.


CHAPTER 6. FORTH GLOSSARY

The glossary contains all of the word definitions in this release of
fig-FORTH (with extensions for the Spectrum). The definitions are
presented in the order of their ASCII sort.

The first line of each entry shows a symbolic description of the action
of the procedure on the parameter stack. The symbols indicate the order
in which input parameters have been placed on the stack. Three dashes
'---' indicate the execution point; any parameters left on the stack are
listed. In this notation, the top of the stack is to the right.

The symbols include:

  addr    memory address
  b       8 bit byte (i.e. high 8 bits zero)
  c       7 bit ASCII character
  d       32 bit signed double integer.
  f       boolean flag. 0 = false, non-zero = true.
  ff      boolean false flag = 0
  n       16 bit signed integer number.
  u       16 bit unsigned integer number
  tf      boolean true flag = non-zero

  The capital letters on the right show definition characters:
  C       May only be used within a colon definition. A digit indicates number of memory addresses used.
  E       Intended for execution only.
  P       Has precedence bit set. Will execute even when compiling.
  U       A user variable.

Unless otherwise noted, all references to numbers are for 16 bit signed
integers. The high byte is on top of the stack, with the sign in the
leftmost bit. For 32 bit numbers the most significant part is on top.

All arithmetic is implicitly 16 bit signed integer math, with error and under-flow indication unspecified.

Acknowledgements are duly made to the FORTH INTEREST GROUP. PO Box 1105,
San Carlos, CA 94070 for parts of this compiler and manual.


dsForth FORTH GLOSSARY

! ( n addr -- ) L0
Store 16 bits of n at address. Pronounced "store"

!CSP
Save the stack position in CSP. Used as part of the compiler security.

# ( d1 -- d2 ) L0
Generate from a double number d1, the next ASCII character which is
placed in an output string. Result d2 is the quotient after division by
BASE, and is maintained for further processing. Used between <# and #>.
See #S.

#> ( d -- addr count ) L0
Terminates numeric output conversions by dropping d, leaving the text
address and character count suitable for TYPE.

#S ( d1 -- d2 ) L0
Generates ASCII text in the text output buffer, by the use of #, until a
zero double number results. Used between <# and #>.

' ( -- addr ) P,L0
Used in the form:    ' nnnn
Leaves the parameter field address of dictionary word nnnn. As a
compiler directive, executes a colon-definition to compile the address
as a literal. If the word is not found after a search of CONTEXT and
CURRENT, an appropriate error message is given. Pronounced "tick".

( P, L0
Used in the form:  ( cccc)
Ignore a comment that will be delimited by a right parenthesis on the
same line. May occur during execution or in a colon-definition. A blank
after the leading parenthesis is required.

(.") C+
The run-time procedure, compiled by ." which transmits the following
in-line text to the selected output device. See ."

(;CODE) C
The run-time procedure, compiled by ;CODE, that rewrites the code field
of the most recently defined word to point to the following machine code
sequence. See ;CODE.

(+LOOP) ( n -- ) C2
The run-time procedure compiled by +LOOP, which increments the loop
index by n and tests for loop completion. See + LOOP.

(ABORT)
Executes after an error when WARNING is -1. The word normally executes
ABORT, but may be altered (with care) to a user's alternative procedure.

(DO) C
The run-time procedure compiled by DO which moves the loop control
parameters to the return stack. See DO

(FIND) ( addr l addr2 -- pfa b tf  ok)
       ( addr l addr2 -- ff        bad)
Searches the dictionary starting at the name field address addr2,
matching to the text at addrl. Returns parameter field address, length
byte of name field and true for a good match. If no match is found, only
a boolean false is left.

(LINE) ( n1 n2 -- addr count )
Convert the line number n1 and the screen n2 to the disc buffer address
containing the data. A count of 64 indicates the full line text length.

(LOOP) C2
The run-time procedure compiled by LOOP which increments the loop index
and tests for loop completion. See LOOP

(NUMBER) ( d1 addrl -- d2 addr2 )
Convert the ASCII text beginning at addr1 + 1 with regard to BASE. The
new value is accumulated into double number d1, being left as d2. Addr2
is the address of the first unconvertible digit. Used by NUMBER.

* ( n1 n2 -- prod )L0
Leaves the signed product of two signed numbers.

*/ ( n1 n2 n3 -- n4 ) L0
Leaves the ratio n4=n1*n2/n3 where all are signed numbers. Retention of
an intermediate 31 bit product permits greater accuracy than would be
available with the sequence:  n1 n2 * n3 /

*/MOD ( n1 n2 n3 -- n4 n5 ) L0
Leaves the quotient n5 and remainder n4 of their operation n1*n2/n3. A
31 bit intermediate product is used as for */

+ ( n1 n2 -- sum )L0
Leave the sum of n1 + n2.

+! ( n addr -- ) L0
Add n to the value at the address. Pronounced "plus-store".

+- ( n1 n2 -- n3 )
Apply the sign of n2 to n1, which is left as n3.

+BUF ( addr1 -- addr2 f )
Advance the disc buffer address addr1 to the address of the next buffer
addr2. Boolean f is false when addr2 is the buffer presently pointed to
by variable PREV.

+LOOP ( n1 --  run)
      ( addr n2 --  compile)   P,C2,L0
Used in a colon-definition in the form:  DO... n1 +LOOP

At run-time, +LOOP selectively controls branching back to the
corresponding DO, based on n1, the loop index and the loop limit. The
signed increment n1 is added to the index and the total compared to the
limit. The branch back to DO occurs until the new index is equal to or
greater than the limit (n1>0), or until the new index is equal to or less
than the limit (n1<0). Upon exiting the loop, the parameters are
discarded and execution continues ahead.

At compile time, +LOOP compiles the run-time word (+LOOP) and the branch
offset computed from HERE to the address left on the stack by DO. n2 is
used for compile time error checking.

+ORIGIN ( n -- addr )
Leave the memory address offset n bytes from the origin. This definition
is used to access or modify the boot-up parameters at the origin area.


, ( n -- ) L0
Store n into the next available dictionary memory cell, advancing the
dictionary pointer. (comma)

- ( n1 n2 -- diff ) L0
Leave the difference of n1-n2.

--> ( P,L0 )
Continue interpretation with the next disc screen. (pronounced next-screen).

-DUP ( n1 -- n1  if zero)
     ( n1 -- n1 n1  if non-zero)      L0
Reproduce n1 only if it is non-zero.  This is usually used to copy a
value just before IF, to eliminate the need for an ELSE part to drop it.

-FIND ( -- pfa b tf  found)
      ( -- ff        not found)
Accepts the next text word (delimited by blanks) in the input stream to
HERE, and searches the CONTEXT and then CURRENT vocabularies for a
matching entry. If found, the * dictionary entry's parameter field
address, its length byte, and a boolean true is left. Otherwise, only a
boolean false is left.

-TRAILING ( addr n1 -- addr n2 )
Adjusts the character count n1 of a text string beginning address to
suppress the output of trailing blanks.

. ( n -- ) L0
Print a number from a signed 16 bit two's complement value, converted
according to the numeric BASE. A trailing blank follows. Pronounced
"dot".

." P,L
Used in the form: ." cccc" Compiles an in-line string cccc (delimited by
the trailing ") with an execution procedure to transmit the text to the
selected output device. If executed outside a definition, ." will
immediately print the text until the final ". See (.").

.LINE ( line scr -- )
Print on the screen, a line of text from the RAM disc by its line and
screen number. Trailing blanks are suppressed.

(.NEXT)
This is the inner interpreter that uses the interpretive pointer IP to
execute compiled Forth definitions. It is not directly executed but is
the return point for all code procedures. It acts by fetching the
address pointed to by IP, storing this value in register W. W points to
the code field of a definition which contains the address of the code
which is to be executed for that definition. This address is then jumped
to. This usage of indirect threaded code is a major contributor to the
power, portability, and extensibility of Forth. Locations of IP and W
are computer specific. (See earlier note on Spectrum FORTH convention).

(.PUSHDE)
(.PUSHHL)
This code sequence pushes machine registers to the computation stack and
returns to NEXT. it is not directly executable, but is a Forth re-entry
after machine code. PUSHHL returns just the HL register PUSHDE returns
the DE register under the HL register on the stack.


.R ( n1 n2 -- )
Print the number n1 right aligned in a field whose width is n2. No
following blank is printed.

/ ( n1 n2 -- rem )
Leave the signed quotient of n1 /n2.

/MOD ( n1 n2 -- rem quot ) L0
Leave the remainder and signed quotient of n1/n2. The remainder has the
sign of the dividend.

0 1 2 3 -- n
These small numbers are used so often that it is attractive to define
them by name in the dictionary as constants.

0< ( n -- f ) L0
Leave a true flag if the number is less than zero (negative), otherwise
leave a false flag.

0= ( n -- f ) L0
Leave a true flay if the number is equal to zero, otherwise leave a
false flag.

0BRANCH f --
The run-time procedure to conditionally branch. If f is false (zero),
the following in-line parameter is added to the interpretive pointer to
branch ahead or back. Compiled by IF, UNTIL and WHILE.

1+ ( n1 -- n2 ) L1
Increment n1 by 1.

2+ ( n1 -- n2 )
Increment n1 by 2.

2! ( nlow nhigh addr -- )
32 bit store, nhigh is stored at addr; nlow is stored at addr+2.

2CONSTANT ( d -- )
A defining word used in the form: d 2CONSTANT cccc
to create word cccc, with its parameter field containing d. When cccc is
later executed, it will push the double value of d to the stack.

2DROP ( d -- )
Drop the double number from the stack.

2DUP ( n2 n1 -- n2 n1 n2 n1 )
Duplicates the top two values on the stack. Equivalent to OVER OVER.

2OVER ( d1 d2 -- d1 d2 d1 )
Copy the first double value d1 to the top of the stack.

2SWAP ( d1 d2 -- d2 d1 )
Exchange the top two double numbers on the stack.

2VARIABLE
A defining word used in the form: d VARIABLE cccc
When VARIABLE is executed, it creates the definition cccc with its
parameter field initialized to d. When cccc is later executed, the
address of its parameter field (containing d) is left on the stack, so
that a double fetch store may access this location.

: P,E,L0
Used in the form called a colon-definition: : cccc ... ;
Creates a dictionary entry defining cccc as equivalent to the following
sequence of FORTH word definitions '...' until the next `;' or ';CODE'.
The compiling process is done by the text interpreter as long as STATE
is non-zero. Other details are that the CONTEXT vocabulary is set to the
CURRENT vocabulary and that words with the precedence bit set (P) are
executed rather than being compiled.

; P,C,L0
Terminate a colon-definition and stop further compilation. Compiles the
run-time ;S.

;CODE P,C,L0
Used in the form: : cccc .... ;CODE
Stop compilation and terminate a new defining word cccc by compiling
(;CODE). Set the CONTEXT vocabulary to ASSEMBLER, assembling to machine
code the following mnemonics. If the ASSEMBLER is not loaded, code
values may be compiled using , and C,.  When cccc later executes in the
form: cccc nnnn the word nnnn will be created with its execution
procedure given by the machine code following cccc. That is when nnnn is
executed, it does so by jumping to the code after nnnn. An existing
defining word must exist in cccc prior to ;CODE.

;S P,L0
Stop interpretation of a screen. ;S is also the run-time word compiled
at the end of a colon-definition which returns execution to the calling
procedure.

< ( n1 n2 -- f ) L0
Leave a true flag if n1 is less than n2; otherwise leave a false flag.

<# L0
Setup for pictured numeric output formatting using the words: <# # #S SIGN #>
The conversion is done on a double number producing text at PAD.

<BUILDS C,L0
Used within a colon-definition:  : cccc <BUILDS... DOES> ... ;
Each time cccc is executed, <BUILDS defines a new word with a high-level
execution procedure. Executing cccc in the form:  cccc nnnn uses <BUILDS
to create a dictionary entry for nnnn with a call to the DOES> part for
nnnn. When nnnn is later executed, it has the address of its parameter
area on the stack and executes the words after DOES> in cccc. <BUILDS
and DOES> allow run-time procedures to be written in high-level rather
than in assembler code (as required by ;CODE).

= ( nl n2 -- b ) L0
Leave a true flag if n1=n2; otherwise leave a false flag.

> ( n1 n2 -- b ) L0
Leave a true flag if n1 is greater than n2; otherwise a false flag.

>R ( n -- ) C,L0
Remove a number from the computation stack and place as the most
accessible on the return stack. Use should be balanced with R> in the
same definition.

? ( addr -- ) L0
Print the value contained at the address in free format according to the
current base.

?COMP
Issue error message if not compiling.

?CSP
Issue error message if stack position differs from value saved in CSP.

?ERROR ( f n -- )
Issue an error message number n, if the boolean flag is true.

?EXEC
Issue an error message if not executing.

?LOADING
Issue an error message if not loading.

?PAIRS ( n1 n2 -- )
Issue an error message if n1 does not equal n2. The message indicates
that compiled conditionals do not match.

?STACK
Issue an error message if the stack is out of bounds.

?BREAK ( -- f )
Perform a test of the terminal keyboard for actuation of the break key.
A true flag indicates actuation.

@ ( addr -- n ) L0
Leave the 16 bit contents of address.

ABORT L0
Clear the stacks and enter the execution state. Return control to the
keyboard, printing a message.

ABS ( n -- u ) L0
Leave the absolute value of n as u.

AGAIN ( addr n --  compiling)  P,C2,L0
Used in a colon-definition in the form:  BEGIN ... AGAIN
At run-time, AGAIN forces execution to return to corresponding BEGIN.
There is no effect on the stack. Execution cannot leave this loop
(unless R> DROP is executed one level below). At compile time, AGAIN
compiles BRANCH with an offset from HERE to addr. n is used for
compile-time error checking.

ALLOT ( n -- ) L0
Add the signed number to the dictionary pointer DP. May be used to
reserve dictionary space or reorigin memory. n is with regard to
computer address type (byte or word).

AND ( n1 n2 -- n3 ) L0
Leave the bitwise logical and of n1 and n2 as n3.

GOTOXY ( x y -- )
Moves the cursor position to line y, column x (0-based).

B/BUF ( -- n )
This constant leaves the number of bytes per disc buffer, the byte count
read from disc by BLOCK

B/SCR ( -- n )
This constant leaves the number of blocks per editing screen. By
convention, an editing screen is 1024 bytes organised as 16 lines of 64
characters each.

BACK ( addr -- )
Calculate the backward branch offset from HERE to addr and compile into
the next available dictionary memory address.

BASE ( -- addr ) U,L0
A user variable containing the current number base used for input and
output conversion.

BEGIN ( -- addr n  compiling) P,L0
Occurs in a colon-definition in forms:
  BEGIN ... UNTIL
  BEGIN ... AGAIN
  BEGIN ... WHILE ... REPEAT
At run-time, BEGIN marks the start of a sequence that may be
repetitively executed. It serves as a return point from the
corresponding UNTIL, AGAIN or REPEAT. When executing UNTIL, a return to
BEGIN will occur if the top of the stack is false; for AGAIN and REPEAT
a return to BEGIN always occurs.
At compile time BEGIN LEAVES its return address and n for compiler error
checking.

BL ( -- c )
A constant that leaves the ASCII values for "blank".

BLANKS ( addr count -- )
Fill an area of memory beginning at addr with count blanks.

BLEEP ( n1 n2 -- )
Produce a tone in the Spectrum noise maker of duration n1, pitch n2.

BLOCK ( n -- addr ) L0
Leave the memory address of the block buffer containing block n. If the
block is not already in memory, it is transferred from microdrive to
which ever buffer was least recently written. If the block occupying
that buffer has been marked as updated, it is rewritten to microdrive
before block n is read into the buffer. See also BUFFER, R/W UPDATE
FLUSH

BRANCH C2,L0
The run-time procedure to unconditionally branch. An in-line offset is
added to the interpretive pointer IP to branch ahead or back. BRANCH is
compiled by ELSE, AGAIN, REPEAT.

BRANCHT C2,L0
The run-time procedure to conditionally branch. If f is true (non-zero),
the following in-line parameter is added to the interpretive pointer to
branch ahead or back. Compiled by IFNOT.

BORDER  ( n -- )
Set the border to colour n.

BUFFER  ( n -- addr )
Obtain the next memory buffer, assigning it to block n. If the contents
of the buffer is marked as updated, it is written to the microdrive. The
block is not read from the microdrive. The address left is the first
cell within the buffer to data storage.

BYE
Exit to Basic/TR-DOS.

C! ( b addr -- )
Store 8 bits at address.

C/L ( -- n )
Constant leaving the number of characters per line; used by the editor.

C, ( b -- )
Store 8 bits of b into the next available dictionary byte, advancing the
dictionary pointer.

C@ ( addr -- b )
Leave the 8 bit contents of memory address.

CASE ( -- n  compiling)
Occurs in a colon definition in the form:
  CASE
    n OF .....   ENDOF
  ENDCASE
At run-time, CASE marks the start of a sequence of OF ... ENDOF statements.
At compile-time CASE leaves n for compiler error checking.

CFA ( pfa -- cfa )
Convert the parameter field address of a definition to its code field address.

CLS ( -- )
Performs the clear-screen home-cursor function.

CMOVE ( from to count -- )
Move the specified quantity of bytes beginning at address from , to
address to. The contents of address from is moved first, proceeding
toward high memory.

COLD
The cold start procedure to adjust the dictionary pointer to the minimum
standard and restart via ABORT. May be called from the terminal to
remove application programs and restart.

COMPILE C2
When the word containing COMPILE executes, the execution address of the
word following COMPILE is copied (compiled) into the dictionary. This
allows specific compilation situations to be handled in addition to
simply compiling an execution address (which the interpreter already
does).

CONSTANT ( n -- ) L0
A defining word used in the form: n CONSTANT cccc
to create word cccc, with its parameter field containing n. When cccc is
later executed, it will push the value of n to the stack.

CONTEXT ( -- addr ) U,L0
A user variable containing a pointer to the vocabulary within which
dictionary searches will first begin.

COUNT ( addr1 -- addr2 n ) L0
Leave the byte address addr2 and byte count n of a message text
beginning at address addr1. It is presumed that the first byte at addr1
contains the text byte count and the actual text starts with the second
byte. Typically COUNT is followed by TYPE.

CR L0
Transmit a carriage return and line feed to the selected output device.

CREATE
A defining word used in the form: CREATE cccc
by such words as CODE and CONSTANT to create a dictionary header for a
Forth definition. The code field contains the address of the word's
parameter field. The new word is created in the current vocabulary.

CSP ( -- addr ) U
A user variable temporarily storing the stack pointer position, for
compilation error checking.

D+ ( d1 d2 -- dsum )
Leave the double number sum of two double numbers.

D+- ( d1 n -- d2 )
Apply the sign of n to the double number d1, leaving it as d2.

D. ( d -- ) L1
Print a signed double number from a 32 bit two's complement value. The
high-order 16 bits are most accessible on the stack. Conversion is
performed according to the current BASE. A blank follows. Pronounced
D-dot.

D.R ( d n -- )
Print a signed double number d, right aligned in a field n characters wide.

DABS ( d -- ud )
Leave absolute value ud of a double number.

DECIMAL ( L0 )
Set the numeric conversion base for decimal input-output.

DEFINITIONS ( LI )
Used in the form:  cccc DEFINITIONS
Set the CURRENT vocabulary to the CONTEXT vocabulary. In the example,
executing vocabulary name cccc made it the CONTEXT vocabulary and
executing DEFINITIONS made if both the CONTEXT and CURRENT vocabularies.

DIGIT ( c n1 -- n2 tf  ok)
      ( c n1 -- ff     bad)
Converts the ascii character c (using base n1) to its binary equivalent
n2, accompanied by a true flag. If the conversion is invalid, leaves
only a false flag.

DLITERAL ( d -- d  executing)
         (d --     compiling) P
If compiling, compile a double number from the stack into a literal.
Later execution of the definition containing the literal will push it to
the stack. If executing, the number will remain on the stack.

DNEGATE ( d1 -- d2 )
Convert d1 to its double number two's complement.

DO ( n1 n2 --   execute)
   ( addr n --  compile) P,C2,L0
Occurs in a colon-definition in forms:
  DO ... LOOP
  DO... +LOOP
At run time, DO begins a sequence with repetitive execution controlled
by a loop limit n1 and an index with initial value n2. DO removes these
from the stack. Upon reaching LOOP the index is incremented by one, and
B, unless A. In this case the loop parameters are discarded and
execution continues ahead. Both n1 and n2 are determined at run-time and
may be the result of other operations. Within a loop 'I' will copy the
current value of the index to the stack. See I, LOOP, +LOOP, LEAVE.
When compiling with the colon-definition, DO compiles (DO). It then
leaves the following address addr, and n for later error checking.

DOES> L0
A word which defines the run-time action within a high-level defining
word.  DOES> alters the code field and first parameter of the new word
to execute the sequence of compiled word addresses following DOES>. Used
in combination with <BUILDS. When the DOES> part executes it begins with
the address of the first parameter of the new word on the stack. This
allows interpretation using this area or its contents. Typical uses
include the Forth assembler, multidimensional arrays, and compiler
generation.

DP ( -- addr ) U,L
A user variable, the dictionary pointer, which contains the address of
the next free memory above the dictionary. The value may be read by HERE
and altered by ALLOT.

DPL ( -- addr ) U,L0
A user variable containing the number of digits to the right of the
decimal on double integer input. It may also be used to hold output
column location of a decimal point, in user generated formatting. The
default value on single number input is -1.

DROP ( n -- ) L0
Drop the number from the stack.

DUP ( n -- n n ) L0
Duplicate the value on the stack.

ELSE ( addr1 n1 -- )
     ( addr2 n2  compiling) P,C2,L0
Occurs within a colon-definition in the form:   IF ... ELSE ... ENDIF
At run-time, ELSE executes after the true part following IF. ELSE forces
execution to skip over the following part and resumes execution after
the ENDIF. It has no stack effect.
At compile-time ELSE compiles BRANCH, reserving space for a branch
offset. It leaves the address addr2, and n2 for error testing. ELSE also
resolves the pending forward branch from IF by calculating the offset
from addr1 to HERE, and storing at addrl.

EMIT ( c -- ) L0
Transmit ascii character c to the screen.

EMPTY-BUFFERS ( L0 )
Mark all block-buffers as empty, not necessarily affecting the contents.
Updated blocks are not written to the microdrive. This is also an
initialisation procedure before first use of the microdrive.

ENCLOSE ( addr1 c -- addr1 n1 n2 n3 )
The text scanning primitive used by WORD. From the text address addr1
and an ascii delimiting character c, is determined the byte offset to
the first non-delimiter character n1, the offset to the first delimiter
after the text n2, and the offset to the first character not included.
This procedure will not process past an ascii 'null", treating it as an
unconditional delimiter.

END P,C2,L0
This is an 'alias' or duplicate definition for UNTIL.

ENDCASE ( addr n --  compile)
Occurs in a colon definition in the form:
  CASE
    n OF ..... ENDOF
  ENDCASE
At run-time ENDCASE marks the conclusion of a CASE statement.
At compile-time, ENDCASE computes forward branch offsets.

ENDIF ( addr n --  compile)    P,C0,L0
Occurs in a colon-definition in forms:
  IF ... ENDIF
  IF ... ELSE ... ENDIF
At run-time, ENDIF serves only as the destination of a forward branch
from IF or ELSE. It marks the conclusion of the conditional structure.
THEN is another name for ENDIF. Both names are supported in fig-FORTH.
See also IF and ELSE.
At compile-time, ENDIF computes the forward branch offset from addr to
HERE and stores it at addr. n is used for error tests.

ENDOF ( Addr n --  compile)
Used as ENDIF but in CASE statements.

FILL ( addr quan b -- )
Fill memory at the address with the specified quantity of bytes b.

ERASE ( addr n -- )
Clear to zero a region of memory, n bytes long, starting at addr.

ERROR ( n -- in blk )
Execute error notification and restart of systems. WARNING is first
examined. If 1, the text of line n, relative to screen 4 is printed.
This line number may be positive or negative, and beyond just screen 4.
If WARNING=0, n is just printed as a message number (RAM disc
installation). If WARNING is -1 the definition (ABORT) is executed,
which executes the system ABORT. The user may cautiously modify this
execution by altering (ABORT). fig-FORTH saves the contents of IN and
BLK on the stack to assist in determining the location of the error.
Final action is execution of QUIT.

EXECUTE ( addr -- )
Execute the definition whose code field address is on the stack. The
code field address is also called the compilation address.

EXIT
Force the conclusion of a definition at a different place than the end.
Must not be used when the return stack has been modified!

EXPECT ( addr count -- ) L0
Transfer characters from the terminal to address, until a "return" or
the count of characters have been received. One or more nulls are added
at the end of the text.

FENCE   ( -- addr ) U
A user variable containing an address below which FORGETting is not
allowed. To forget below this point the user must alter the contents of
FENCE.

FIRST ( -- n )
A constant that leaves the address of the first (lowest) block buffer.

FLD ( -- addr ) U
A user variable for control of number output field width. Presently
unused.

FLUSH
Write all updated disc buffers to the microdrive.

FORGET E,L0
Executed in the form:  FORGET cccc
Deletes definition named cccc from the dictionary with all entries
physically following it. In fig-FORTH, an error message will occur if
the CURRENT and CONTEXT vocabularies are not currently the same.

FORTH P,L1
The name of the primary vocabulary. Execution makes FORTH the CONTEXT
VOCABULARY. Until additional user vocabularies are defined, new user
definitions become a part of FORTH. FORTH is immediate, so it will
execute during the creation of a colon-definition to select this
vocabulary at compile time.

FREE ( -- n )
Returns a value on the stack of the amount of store remaining in bytes.

HERE ( -- addr ) L0
Leave the address of the next available dictionary location.

HEX L0
Set the numeric conversion base to sixteen (hexadecimal).

HLD ( -- addr )L0
A user variable that holds the address of the latest character of text
during numeric output conversion.

HOLD ( c -- ) L0
Used between <# and #> to insert an ascii character into a pictured
numeric output string e.g. 2E HOLD will place a decimal point  .

I ( -- n ) C, L0
Used within a DO-LOOP to copy the loop index to the stack.  See R.

I' ( -- n )
Copies the last but one value from the return stack (which within a
DO-LOOP is the loop limit).

ID. ( addr -- )
Print a definition's name from its name field address.

IF ( f --  run-time)
   ( -- addr n (compile) P,C2,L0
Occurs in a colon-definition in the forms:
  IF (tp) ... ENDIF
  IF (tp) ... ELSE (fp)  ... ENDIF
At run-time, IF selects execution based on a boolean flag. If f is true
(non-zero), execution continues  ahead throughout the true part. If f is
false, execution jumps to just after ELSE to execute the false part.
After either part, execution resumes after ENDIF. ELSE and its false
part are optional. If missing, false execution skips to just after
ENDIF.
At compile-time IF compiles 0BRANCH and reserves space for an offset at
addr. addr and n are used later for resolution of the offset and error
testing.

IMMEDIATE
Mark the most recently made definition so that when encountered at
compile time, it will be executed rather than being compiled, i.e. the
precedence bit in its header is set. This method allows definitions to
handle unusual compiling situations, rather than build them into the
fundamental compiler. The user may force compilation of an immediate
definition by preceding it with [COMPILE].

IN ( -- addr ) L0
A user variable containing the byte offset within the current input text
buffer (terminal or RAM-disc) from which the next text will be accepted.
WORD uses and moves the value of IN.

INK ( n -- )
Sets the ink colour to n(0-9)

INKEY ( -- c )
Leaves the value of the key being pressed. If no key being pressed
leaves hex FF

INP ( n1 -- b )
Returns the value read from port n1.

INTERPRET
The outer text interpreter which sequentially executes or compiles text
from the input stream (terminal or RAM-disc) depending on STATE. If the
word name cannot be found after a search of CONTEXT and then CURRENT it
is converted to a number according to the current base. That also
failing, an error message echoing the name with a "?" will; be given.
Text input will be taken according to the convention for WORD. If a
decimal point is found as part of a number, a double number value will
be left. The decimal point has no other purpose than to force this
action. See NUMBER.

J ( -- n )
Used within nested DO loops. Returns the index value of the outer loop.

KEY ( -- v ) L0
Leave the ascii value of the next terminal key struck.

LATEST ( -- addr )
Leave the name field address of the topmost word in the CURRENT
vocabulary.

LEAVE C, L0
Force termination of a DO-LOOP at the next opportunity by setting the
loop limit equal to the current value of the index. The index itself
remains unchanged, and execution proceeds normally until LOOP or +LOOP
is encountered.

LFA pfa -- lfa
Convert the parameter field address of a dictionary definition to its
link field address.

LIMIT (  -- n )
A constant leaving the address just above the highest memory address
used by the system.

LINE ( n -- addr )
Leave address of line n of current screen. This address will be in the
RAM-disc buffer area.

LIST ( n -- ) L0
Display the ASCII text of screen n on the display. SCR contains the
screen number during and after this process.

LIT ( -- n ) C2,L0
Within a colon-definition, LIT is automatically compiled before each 16
bit literal number encountered in input text. Later execution of LIT
causes the contents of the next dictionary address to be pushed to the
stack.

LITERAL ( n --  compiling)               P,C2,L0
If compiling, then compile the stack value n as a 16 bit literal. This
definition is immediate so that it will execute during a colon
definition, the intended use is:   : xxx [calculate] LITERAL;
Compilation is suspended for the compile time calculation of a value.
Compilation is resumed and LITERAL compiles this value.

TLOAD ( addr len -- ) L0
Begin interpretation of screen n. Loading will terminate at the end of the screen or at;S. See ;S and -->.

LOOP ( addr n --  compiling)  P,C2,L0
Occurs in a colon-definition in form: DO ... LOOP
At run-time, LOOP selectively controls branching back to the
corresponding DO based on the loop index and limit. The loop index is
incremented by one and compared to the limit. The branch back to DO
occurs until the index equals or exceeds the limit; at that time, the
parameters are discarded and execution continues ahead.
At compile-time, LOOP compiles (LOOP) and uses addr to calculate an
offset to DO. n is used for error testing.

M* ( nl n2 -- d )
A mixed magnitude math operation which leaves the double number signed
product of two signed numbers.

M/ ( d n1 -- n2 n3 )
A mixed magnitude math operator which leaves the signed remainder n2 and
signed quotient n3, from a double number d dividend and divisor n1. The
remainder takes its sign from the dividend.

M/MOD ( ud1 u2 -- u3 ud4 )
An unsigned mixed magnitude math operation which leaves a double
quotient ud4 and remainder u3, from a double dividend ud1 and single
divisor u2.

MAX ( n1 n2 -- max ) L0
Leave the greater of two numbers.

MESSAGE ( n -- )
Print on the selected output device the text of line n relative to
screen 4 of drive 0. n may be positive or negative. MESSAGE may be used
to print incidental text such as report headers. If WARNING is zero, the
message will simply be printed as a number (RAM disc system).

MIN ( n1 n2 -- min ) L0
Leave the smaller of two numbers.

MOD             n1 n2 -- mod                   L0
Leave the remainder of n1/n2, with the same sign as n1.

NEGATE ( n1 -- n2 ) L0
Leave the two's complement of a number.

NFA ( pfa -- nfa )
Convert the parameter field address of a definition to its name field.

NOOP
A FORTH no-operation.

NOT ( f1 -- f2 )
Leaves a false flag if a true flag is on the stack, else leaves a true
flag. (Actually executes 0=)

NUMBER ( addr -- d )
Convert a character string left at addr with a preceding count, to a
signed double number, using the current numeric base. If a decimal point
is encountered in the text, its position will be given in DPL, but no
other effect occurs. If numeric conversion is not possible, an error
message will be given.

OFFSET ( -- addr ) U
A user variable which may contain a block offset for the RAM-disc. The
contents of OFFSET is added to the stack number by BLOCK. Messages
printed by MESSAGE are independent of OFFSET. See BLOCK, MESSAGE.

OR ( n1 n2 -- or ) L0
Leave the bit-value logical or of two 16 bit values.

OUTP ( n1 n2 -- )
Presents n1 to output port n2.

OVER ( n1 n2 -- n1 n2 n1 ) L0
Copy the second stack value, placing it as the new top.

PAD ( -- addr ) L0
Leaves the address of the text output buffer, which is a fixed offset above HERE.

PFA ( nfa -- pfa )
Convert the name field address of a compiled definition to its parameter
field address.

PLOT ( n1 n2 -- )
Sets point n1(x),n2(y). If this value is off the screen, no action is taken.

POINT ( n1 n2 -- f )
Returns a true flag if n1(x),n2(y) is set, else returns a false flag.

PREV ( -- addr )
A variable containing the address of the buffer most recently
referenced. The UPDATE command marks this buffer to be later written to
microdrive.

QUIT
Clear the return stack, stop compilation, and return control to the
operator's terminal. No message is given.

R# ( -- addr ) U
A user variable which may contain the location of an editing cursor or
other file related function.

R/W ( addr blk f -- )
The fig-FORTH standard disc read-write linkage. addr specifies the
source or destination block buffer. blk is the sequential number of the
referenced block; and f is a flag for f= write and f=1 read. R/W
determines the location on the microdrive, performs the read-write and
performs any error checking.

R>              -- n                                   L0
Remove the top value from the return stack and leave it on the
computation stack. See >R and R.

R@ ( -- n )
Copy the top of the return stack to the computation stack.

R0              -- addr                                U
A user variable containing the initial location of the return stack.
Pronounced R-zero. See RP!

RDROP ( -- n )
Drop the top of the return stack.

QUERY
Input 80 characters of text (or until a "return") from the operators
terminal. Text is positioned at the address contained in TIB with IN set
to zero.

REPEAT ( addr n --  compiling) P,C2
Used within a colon-definition in the form:     BEGIN ... WHILE ... REPEAT
At run-time, REPEAT forces an unconditional branch back to just after
the corresponding BEGIN.
At compile-time, REPEAT compiles BRANCH and the offset from HERE to
addr. n is used for error testing.

ROT ( n1 n2 n3 -- n2 n3 n1 ) L0
Rotate the top three values on the stack, bringing the third to the top.

RP@ ( -- addr )
Leaves the current value in the return stack pointer register.

RP!
A computer dependent procedure to initialize the return stack pointer
from user variable R0.

S->D ( n -- d )
Sign extend a single number to form a double number.

S0 ( -- addr ) U
A user variable that contains the initial value for the stack pointer.
Pronounced S-zero. See SP!

SCR ( -- addr )
A user variable containing the screen number most recently referenced by LIST.

SCREEN ( n1 n2 -- a )
Returns the ascii value of the character at line n1, column n2 as long
as that character is not a user-defined character.

SIGN ( n d -- d ) L0
Stores an ascii "-" sign just before a converted numeric output string
in the next output buffer when n is negative. n is discarded, but double
number d is maintained. Must be used between < # and #>.

SIZE ( -- n )
SIZE returns a value on the stack of the current size of the dictionary.

SMUDGE
Used during word definition to toggle the "smudge bit" in a definitions'
name field. This prevents an uncompleted definition from being found
during dictionary searches, until compiling is completed without error.

SP!
A computer dependent procedure to initialize the stack pointer from S0.

SP@ ( -- addr )
A computer dependent procedure to return the address of the stack
position to the top of the stack, as it was before SP@ was executed.
(e.g. 1 2 SP@ @ . . . would type 2 2 1)

SPACE L0
Transmit an ascii blank to the output device.

SPACES ( n -- ) L0
Transmit n ascii blanks to the output devic.

STATE ( -- addr ) L0,U
A user variable containing the compilation state. A non-zero value
indicates compilation.

SWAP ( n1 n2 -- n2 n1 ) L0
Exchange the top two values on the stack.

TEXT ( c -- )
Accept following text to PAD. c is the text delimiter.

THEN P,C0,L0
An alias for ENDIF.

TIB ( -- addr ) U
A user variable containing the address of the terminal input buffer.

TOGGLE ( addr b -- )
Complement the contents of addr ' by the bit pattern b.

TRAVERSE ( addr1 n -- addr2 )
Move across the name field of a fig-FORTH, variable length, name field.
addr1 is the address of either the length byte or the last letter. If
n=1, the motion is toward hi memory; if n=-1, the motion is toward low
memory. The addr resulting is address of the other end of the name.

TYPE ( addr count -- )L0
Transmit count characters from addr to the display.

U< ( u1 u2 -- f )
Leave the boolean value of an unsigned less-than comparison. Leaves f=1
for u1 < u2, otherwise leaves 0. This function should be used when
comparing memory addresses.

U* ( u1 u2 -- ud )
Leave the unsigned double number product of two unsigned numbers.

U. ( u -- )
Prints an unsigned 16-bit number converted according to BASE. A trailing
blank follows.

U.R ( u n -- )
Print the unsigned number u right aligned in a field whose width is n.
No following blank is printed.

U/MOD ( ud u1 -- u2 u3 )
Leave the unsigned remainder u2 and unsigned quotient u3 from the
unsigned double dividend ud and unsigned divisor u1.

UNTIL ( f --       run-time)
      ( addr n --  compile) P,C2,L0
Occurs within a colon-definition in the form:    BEGIN ... UNTIL
At run-time, UNTIL controls the conditional branch back to the
corresponding BEGIN. If f is false, execution returns to just after
BEGIN; if true, execution continues ahead.
At compile-time, UNTIL compiles (0BRANCH) and an offset from HERE to
addr. n is used for error tests.

UPDATE L0
marks the most recently referenced block (pointed to by PREV) as
altered. The block will subsequently be transferred automatically to
disk should its buffer be required for storage of a different block.

USE ( -- addr )
A variable containing the address of the block buffer to use next, as
the least recently written.

USER ( n -- ) L0
A defining word used in the form:    n USER cccc
The parameter field of cccc contains n as a fixed offset relative to the
user pointer register UP for this user variable. When cccc is later
executed, it places the sum of its offset and user area base address on
the stack as the storage address of that particular variable.

VARIABLE E,LU
A defining word used in the form:        n VARIABLE cccc
When VARIABLE is executed, it creates the definition cccc with its
parameter field initialized to n. When cccc is later executed, the
address of its parameter field (containing n) is left on the stack, so
that a fetch or store may access this location.

WORDS
List the names of the definitions in the context vocabulary. "Break"
will terminate the listing.

VOC-LINK ( -- addr ) U
A user variable containing the address of a field in the definition of
the most recently created vocabulary. All vocabulary names are linked by
these fields to allow control by FORGETting through multiple
vocabularies.

VOCABULARY E,L
A defining word used in the form: VOCABULARY cccc
to create a vocabulary definition cccc. Subsequent use of cccc will make
it the CONTEXT vocabulary which is searched first by INTERPRET. The
sequence "cccc DEFINITIONS" will also make cccc the CURRENT vocabulary
into which new definitions are placed.  In fig-FORTH, cccc will be so
chained as to include all definitions of the vocabulary in which cccc is
itself defined. All vocabularies ultimately chain to Forth. By
convention, vocabulary names are to be declared IMMEDIATE. See VOC-LINK.

WARNING ( -- addr ) U
A user variable containing a value controlling messages. If it =1 disk
is present, and screen 4 of drive 0 is the base location for messages.
If it =0, no disk is present and messages will be presented by number.
If it = -1, execute (ABORT) for user defined procedure. See MESSAGE,
ERROR.

WHERE ( n1 n2 -- )
If an error occurs during LOAD from disk, ERROR leaves these values on
the stack. WHERE uses these values to show the user where the error
occurred by printing the screen and line no.

WHILE ( f --                    (run-time)
      ( ad1 n1 -- ad1 n1 ad2 n2 ) P,C2
Occurs in a colon-definition in the form: BEGIN ... WHILE (tp) ... REPEAT
At run-time, WHILE selects conditional execution based on boolean flag f.
If f is true (non-zero), WHILE continues execution of the true part thru
to REPEAT, which then branches back to BEGIN. If f is false (zero),
execution skips to just after REPEAT, exiting the structure.
At compile time, WHILE compiles (BRANCH) and leaves ad2 of the reserved
offset. The stack values will be resolved by REPEAT.

WIDTH ( -- addr ) U
In fig-FORTH, a user variable containing the maximum number of letters
saved in the compilation of a definitions' name. It must be 1 thru 31,
with a default value of 31. The name character count and its natural
characters are saved, up to the value in WIDTH. The value may be changed
at any time within the above limits.

WORD ( c -- ) L0
Read the next text characters from the input stream being interpreted,
until a delimiter c is found, storing the packed character string
beginning at the dictionary buffer HERE. WORD leaves the character count
in the first byte, then the characters, and ends with two or more
blanks. Leading occurrences of c are ignored If BLK is zero, text is
taken from the terminal input buffer, otherwise from the disc block
stored in BILK See BLK, IN.

X
This is pseudonym for the "null" or dictionary entry for a name of one
character of ascii null. It is the execution procedure to terminate
interpretation of a line of text from the terminal or within a disc
buffer, as both buffers always have a null at the end.

XOR ( n1 n2 -- xor ) -L1
Leave the bitwise logical exclusive-or of two values.

[ P,L1
Used in a colon-definition in form:     : xxx [ words ] more;
Suspend compilations. The words after [ are executed, not compiled.
This allows calculations of compilation exceptions before resuming
compilation with ]. See LITERAL, ].

[COMPILE] P,C
Used in a colon-definition in form:    : xxx [COMPILE] FORTH;
[COMPILE] will force the compilation of an immediate definition, that
would otherwise execute during compilation. The above example will
select the FORTH vocabulary when xxx executed, rather than at compile
time.

] L1
Resume compilation, to the completion of a colon-definition. See [.