sandbox/misc/kforth/doc/fst83/s.txt

463 lines
17 KiB
Plaintext

B. UNCONTROLLED REFERENCE WORDS
APPENDIX B. UNCONTROLLED REFERENCE WORDS
The Uncontrolled Reference Word Set contains glossary definitions
which are included for public reference of words that have past
or present usage and/or are candidates for future
standardization. No recommendation is made that these words be
included in a system.
No restrictions are placed on the definition or usage of
uncontrolled words. However, use of these names for procedures
differing from the given definitions is discouraged.
!BITS 16b1 addr 16b2 -- "store-bits"
Store the value of 16b1 masked by 16b2 into the equivalent
masked part of the contents of addr, without affecting bits
outside the mask.
** n1 n2 -- n3 "power"
n3 is the value of n1 to the power n2.
+BLOCK w -- u "plus-block"
u is the sum of w plus the number of the block being
interpreted.
-' -- addr false "dash-tick"
-- true
Used in the form:
-' <name>
Leave the parameter field of <name> beneath zero (false) if
<name> can be found in the search order; leave only true if
not found.
-MATCH addr1 +n1 addr2 +n2 -- addr3 flag "dash-match"
Attempt to find the +n2-length text string beginning at
addr2 somewhere in the +n1-length text string beginning at
addr1. Return the last+1 address addr3 of the match point
and a flag which is zero if a match exists.
-TEXT addr1 +n1 addr2 -- n2 "dash-text"
Compare two strings over the length +n1 beginning at addr1
and addr2. Return zero if the strings are equal. If
unequal, return n2, the difference between the last
characters compared: addr1(i) - addr2(i).
58
B. UNCONTROLLED REFERENCE WORDS
/LOOP +n -- C,I "up-loop"
sys -- (compiling)
A do-loop terminating word. The loop index is incremented
by the positive value +n. If the unsigned magnitude of the
resultant index is greater than the limit, then the loop is
terminated, otherwise execution returns to the corresponding
DO . The comparison is unsigned magnitude. sys is balanced
with its corresponding DO . See: DO
1+! addr -- "one-plus-store"
Add one to the 16-bit contents at addr.
1-! addr -- "one-minus-store"
Subtract one from the 16-bit contents at addr.
;: -- addr C,I"semi-colon-colon"
Used to specify a new defining word:
: <namex> <name>
When <namex> is executed, it creates an entry for the new
word <name>. Later execution of <name> will execute the
sequence of words between ;: and ; , with the address of the
first (if any) parameters associated with <name> on the
stack.
;S -- Interpret only"semi-s"
Stop interpretation of a block.
<> w1 w2 -- flag "not-equal"
flag is true if w1 is not equal to w2.
<BUILDS -- "builds"
Used in conjunction with DOES> in defining words, in the
form:
: <namex> ... <BUILDS ... DOES> ... ;
and then:
<namex> <name>
When <namex> executes, <BUILDS creates a dictionary entry
for the new <name>. The sequence of words between <BUILDS
and DOES> established a parameter field for <name>. When
<name> is later executed, the sequence of words following
DOES> will be executed, with the parameter field address of
<name> on the data stack.
<CMOVE addr1 addr2 u -- "reverse-c-move"
A synonym for CMOVE> .
>< 16b1 -- 16b2 "byte-swap"
Swap the high and low bytes within 16b1.
>MOVE< addr1 addr2 u -- "byte-swap-move"
Move u bytes beginning at addr1 to the memory beginning at
addr2. During this move, the order of each byte pair is
reversed.
59
B. UNCONTROLLED REFERENCE WORDS
@BITS addr 16b1 -- 16b2 "fetch-bits"
Return the 16-bits at addr masked by 16b1.
AGAIN -- C,I
sys -- (compiling)
Effect an unconditional jump back to the start of a BEGIN-
AGAIN loop. sys is balanced with its corresponding BEGIN .
See: BEGIN
ASCII -- char I,M "as-key"
-- (compiling)
Used in the form:
ASCII ccc
where the delimiter of ccc is a space. char is the ASCII
character value of the first character in ccc. If
interpreting, char is left on the stack. If compiling,
compile char as a literal so that when the colon definition
is later executed, char is left on the stack.
ASHIFT 16b1 n -- 16b2 "a-shift"
Shift the value 16b1 arithmetically n bits left if n is
positive, shifting zeros into the least significant bit
positions. If n is negative, 16b1 is shifted right; the
sign is included in the shift and remains unchanged.
B/BUF -- 1024 "bytes-per-buffer"
A constant leaving 1024, the number of bytes per block
buffer.
BELL --
Activate a terminal bell or noise-maker as appropriate to
the device in use.
CHAIN -- M
Used in the form:
CHAIN <name>
Connect the CURRENT vocabulary to all definitions that might
be entered into the vocabulary <name> in the future. The
CURRENT vocabulary may not be FORTH or ASSEMBLER . Any
given vocabulary may only be chained once, but may be the
object of any number of chainings. For example, every user-
defined vocabulary may include the sequence:
CHAIN FORTH
CONTINUED u -- M
Continue interpretation at block u.
CUR -- addr
A variable pointing to the physical record number before
which the tape is currently positioned. REWIND sets CUR=1.
DBLOCK ud -- addr M "d-block"
Identical to BLOCK but with a 32-bit block unsigned number.
60
B. UNCONTROLLED REFERENCE WORDS
DPL -- addr U "d-p-l"
A variable containing the number of places after the
fractional point for input conversion.
FLD -- addr U "f-l-d"
A variable pointing to the field length reserved for a
number during output conversion.
H. u -- M "h-dot"
Output u as a hexadecimal integer with one trailing blank.
The current base is unchanged.
I' -- w C "i-prime"
Used within a colon definition executed only from within a
do-loop to return the corresponding loop index.
IFEND Interpret only"if-end"
Terminate a conditional interpretation sequence begun by
IFTRUE .
IFTRUE flag -- Interpret only "if-true"
Begin an:
IFTRUE ... OTHERWISE ... IFEND
conditional sequence. These conditional words operated
like:
IF ... ELSE ... THEN
except that they cannot be nested, and are to be used only
during interpretation. In conjunction with the words [ and
] the words [ and ] they may be used within a colon
definition to control compilation, although they are not to
be compiled.
INDEX u1 u2 -- M
Print the first line of each screen over the range {u1..u2}.
This displays the first line of each screen of source text,
which conventionally contains a title.
LAST -- addr U
A variable containing the address of the beginning of the
last dictionary entry made, which may not yet be a complete
or valid entry.
LINE +n -- addr M
addr is the address of the beginning of line +n for the
screen whose number is contained in SCR . The range of +n
is {0..15}.
LINELOAD +n u -- "line-load"
Begin interpretation at line +n of screen u.
61
B. UNCONTROLLED REFERENCE WORDS
LOADS u -- M
A defining word executed in the form:
u LOADS <name>
When <name> is subsequently executed, block u will be
loaded.
MAP0 -- addr "map-zero"
A variable pointing to the first location in the tape map.
MASK n -- 16b
16b is a mask of n most-significant bits if n is positive,
or n least-significant bits if n is negative.
MOVE addr1 addr2 u --
The u bytes at address addr1 are moved to address addr2.
The data are moved such that the u bytes remaining at
address addr2 are the same data as was originally at address
addr1. If u is zero nothing is moved.
MS +n -- M "m-s"
Delay for approximately +n milliseconds.
NAND 16b1 16b2 -- 16b3
16b3 is the one's complement of the logical AND of 16b1 with
16b2.
NOR 16b1 16b2 -- 16b3
16b3 is the one's complement of the logical OR of 16b1 with
16b2.
NUMBER addr -- d
Convert the count and character string at addr, to a signed
32-bit integer, using the value of BASE . If numeric
conversion is not possible, an error condition exists. The
string may contain a preceding minus sign.
O. u -- M "o-dot"
Print u in octal format with one trailing blank. The value
in BASE is unaffected.
OTHERWISE -- Interpret only
An interpreter-level conditional word. See: IFTRUE
PAGE -- M
Clear the terminal screen or perform a form-feed action
suitable to the output device currently active.
READ-MAP -- M "read-map"
Read to the next file mark on tape constructing a
correspondence table in memory (the map) relating physical
block position to logical block number. The tape should
normally be rewound to its load point before executing READ-
MAP .
62
B. UNCONTROLLED REFERENCE WORDS
REMEMBER -- M
A defining word executed in the form:
REMEMBER <name>
Defines a word which, when executed, will cause <name> and
all subsequently defined words to be deleted from the
dictionary. <name> may be compiled into and executed from a
colon definition. The sequence
DISCARD REMEMBER DISCARD
provides a standardized preface to any group of transient
word definitions.
REWIND -- M
Rewind the tape to its load point, setting CUR equal to one.
ROTATE 16b1 n -- 16b2
Rotate 16b1 left n bits if n is positive, right n bits if n
is negative. Bits shifted out of one end of the cell are
shifted back in at the opposite end.
S0 -- addr U "s-zero"
A variable containing the address of the bottom of the
stack.
SET 16b addr -- M
A defining word executed in the form:
16b addr SET <name>
Defines a word <name> which, when executed, will cause the
value 16b to be stored at addr.
SHIFT 16b1 n -- 16b2
Logical shift 16b1 left n bits if n is positive, right n
bits if n is negative. Zeros are shifted into vacated bit
positions.
TEXT char -- M
Accept characters from the input stream, as for WORD , into
PAD , blank-filling the remainder of PAD to 84 characters.
USER +n -- M
A defining word executed in the form:
+n USER <name>
which creates a user variable <name>. +n is the offset
within the user area where the value for <name> is stored.
Execution of <name> leaves its absolute user area storage
address.
WORDS -- M
List the word names in the first vocabulary of the currently
active search order.
63
B. UNCONTROLLED REFERENCE WORDS
\LOOP +n -- C,I "down-loop"
sys -- (compiling)
A do-loop terminating word. The loop index is decremented
by the positive value +n. If the unsigned magnitude of the
resultant index is less than or equal to the limit, then the
loop is terminated, otherwise execution returns to the
corresponding DO . The comparison is unsigned. sys is
balanced with its corresponding DO . See: DO
64