X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=reference.html;h=9cb4b59609eabf30834431443a2a66a96331f340;hb=97bcab28825fde3e717ac5489b0f3f19e5e3f5db;hp=f57f5c8805811feb0fa67dcb88aee1b7a7ee5d6d;hpb=c8819ee75b180664d649f542f4448122f6c4cdce;p=rrq%2Frrqforth.git
diff --git a/reference.html b/reference.html
index f57f5c8..9cb4b59 100644
--- a/reference.html
+++ b/reference.html
@@ -770,17 +770,23 @@ asciidoc.install();
!
C@
C!
+W@
+W!
+D@
+D!
2@
2!
!+
@n++
@n--
C,
-S"
+W,
+D,
+S"
>R
R@
R>
-R[n]
+R[n]
@@ -800,10 +807,12 @@ asciidoc.install();
BEGIN
BREAK
+LIT-STRING
+LOAD-BUFFER-SIZE
+LOAD-FILE
-OPEN-FILE"
+
PAD
@@ -852,19 +866,25 @@ asciidoc.install();
+
ROT
+
RSP
+
@@ -905,6 +927,8 @@ RRQFORTH executon by means of the following instruction sequence:
Note that the FORTH compiler does not invoke an assembler so any
+inline assembly code must be provided in its binary form.
_______________________________________________________
@@ -921,6 +945,15 @@ means of optionally adding the subsequent branch offset, or not, to
the point of execution. If the value, v, is 0 then the branch offset
is added, and otherwise execution continues with the cell following
the branch offset in the definition.
+Note that the branch offset is a byte count and each FORTH word of a
+definition take up a cell of 8 bytes. The offset is relative to the
+cell address immediately subsequent to the offset cell. In other
+words, offset 0 is not branching anywhere and an offset of -16 would
+make a tight loop back to the branch instruction itself. The latter
+would pull data stack values until and including the first non-zero
+value.
_______________________________________________________
@@ -935,7 +968,7 @@ _______________________________________________________
"0=" is a function word that replaces a value with its logical
complement; the result is zero if the value non-zero, and the result
is non-zero if the value is zero.
This is the same function as NOT.
_______________________________________________________
@@ -951,14 +984,13 @@ _______________________________________________________
less than 0, and 0 otherwise.
-
-
Definition concept 1: Word: 0<
+
-
+
_______________________________________________________
@@ -975,6 +1007,14 @@ means of optionally adding the subsequent branch offset, or not, to
the point of execution. If the value, v, is non-zero then the branch
offset is added, and otherwise execution continues with the cell
following the branch offset in the definition.
+Note that the branch offset is a byte count and each FORTH word of a
+definition take up a cell of 8 bytes. The offset is relative to the
+cell address immediately subsequent to the offset cell. In other
+words, offset 0 is not branching anywhere and an offset of -16 would
+make a tight loop back to the branch instruction itself. The latter
+would pull data stack values until and including the first zero value.
_______________________________________________________
@@ -1003,10 +1043,10 @@ _______________________________________________________
stack.
-
-
Definition concept 2: Word: 2DUP
+
@@ -1039,10 +1079,10 @@ onto the top of the data stack. This is similar to
OVER bu
working with cell pairs rather than single cells.
-
-
Definition concept 3: Word: 2OVER
+
@@ -1075,10 +1115,10 @@ the upper and lower pair. This is similar to
SWAP but
working with cell pairs rather than single cells.
-
-
Definition concept 4: Word: 2SWAP
+
@@ -1097,10 +1137,10 @@ _______________________________________________________
at the current free head address, which also is incremented.
-
-
Definition concept 5: Word: C,
+
See also :, [p_comma]. HERE, @,
@@ -1108,6 +1148,72 @@ at the current free head address, which also is incremented.
_______________________________________________________
+
+
+
+
Word: W,
+
+
"W," (W-comma) is a function word that puts a "word" (double-byte) on
+the HERE heap. The two least significant bytes of the value
+are put at the current free head address, which also is incremented
+accordingly.
+
+
+_______________________________________________________
+
+
+
+
+
Word: D,
+
+
"D," (D-comma) is a function word that puts a "double word"
+(double-byte) on the HERE heap. The four least significant
+bytes of the value are put at the current free head address, which
+also is incremented accordingly.
+
+
+_______________________________________________________
+
+
+
+
+
Word: CFA>TFA
+
+
+
Data stack: ( cfa -- tfa )
+
+
"CFA>TFA" is a function word that pushes word tfa of the given cfa.
+
+
+_______________________________________________________
+
@@ -1120,6 +1226,32 @@ _______________________________________________________
_______________________________________________________
+
+
+
+
Word: W@
+
+
+
Data stack: ( a -- v )
+
+
"W@" is a function word that pushes the "word" (double-byte) value v
+from the address a.
+
+_______________________________________________________
+
+
+
+
+
Word: R@
+
+
+
Data stack: ( -- v ) Return stack: ( v -- v )
+
+
"R@" is a function word that "copies" the top return stack value onto
+the data stack.
+
+_______________________________________________________
+
@@ -1133,10 +1265,36 @@ significant byte of the cell) at the address a.
_______________________________________________________
+
+
+
+
Word: W!
+
+
+
Data stack: ( v a -- )
+
+
"W!" is a function word that stores the "word" (2-byte) value v (the
+two least significant bytes of the cell) at the address a.
+
+_______________________________________________________
+
+
+
+
+
Word: D!
+
+
+
Data stack: ( v a -- )
+
+
"D!" is a function word that stores the "doublw word" (4-byte) value v
+(the four least significant bytes of the cell) at the address a.
+
+_______________________________________________________
+
-
Word: R@
+
Word: R@
Data stack: ( -- v ) Return stack: ( v -- v )
@@ -1172,6 +1330,23 @@ value. To that end, the values are 64-bit signed integers.
_______________________________________________________
+
+
+
+
Word: AGAIN
+
+
+
Data stack: Compiling: ( -- a )
+
+
"AGAIN" is an immediate function word that is used together with
+BEGIN and instead of END to implement structured
+execution control. AGAIN scans the datastack for the nearest preceding
+BEGIN marker and lays out an unconditional branch from this point the
+beginning of the block during execution. It thereafter performs the
+END compile action to end the block.
+
+_______________________________________________________
+
@@ -1253,10 +1428,6 @@ numerical base is set to 10 or 16 by
DECIMAL and
supported.
See also DIGITS, which holds the mapping table from
digits to text.
-
-
-
Usage example 3: claim 16 bytes for variable FOO
CREATE FOO BASE
-
_______________________________________________________
@@ -1274,6 +1445,25 @@ implement structured execution control. BEGIN simply places the
address for resolving branches back to this point during execution,
and then a 0 as a marker so as to allow for an unknown number of block
exit points.
+
+
+
+
Usage example 3:
+
+
: WTELL ( tfa -- ; Print word pname )
+ 24 + DUP 8 + SWAP @ TELL SP EMIT
+;
+
+: WORDS ( wordlist -- ; Print all words of word list )
+ BEGIN
+ @ DUP 0= IFBREAK
+ DUP WTELL
+ END
+ DROP
+ NL EMIT
+;
+
+
_______________________________________________________
@@ -1287,6 +1477,14 @@ _______________________________________________________
"[']" is an immediate function word that reads the next word on the
input stream and pushes its cfa.
_______________________________________________________
@@ -1301,6 +1499,14 @@ _______________________________________________________
"BRANCH" is a function word that implements execution transfer by
means of adding the subsequent branch offset to the point of
execution.
Note that the branch offset is a byte count and each FORTH word of a
+definition take up a cell of 8 bytes. The offset is relative to the
+cell address immediately subsequent to the offset cell. In other
+words, offset 0 is not branching anywhere and an offset of -16 would
+make a tight loop back to the branch instruction itself. The latter
+would pull data stack values until and including the first zero value.
_______________________________________________________
@@ -1313,6 +1519,28 @@ branch out of an enclosing xef:p_begin[BEGIN]-END block.
Similar to IFBREAK it lays out the branch cell
followed by a reserved cell for the branch offset, and inserts the
resolution address just above the required 0 on the data stack.
+
+
+
+
Usage example 4: unconditional break with a condition.
+
+
: WTELL ( tfa -- ; Print word pname )
+ 24 + DUP 8 + SWAP @ TELL SP EMIT
+;
+
+: WORDS ( wordlist -- ; Print all words of word list )
+ BEGIN
+ @ DUP IF DUP WTELL ELSE BREAK THEN
+ 1 IFAGAIN
+ END
+ DROP
+ NL EMIT
+;
+
+
_______________________________________________________
@@ -1373,10 +1601,10 @@ This includes reading the next word for making a new dictionary entry
and setting evaluation state to compiling mode.
-
-
Definition concept 6: Word: :
+
See also doFORTH, READ-WORD,
@@ -1397,10 +1625,10 @@ _______________________________________________________
HERE heap.
-
-
Definition concept7: Word: ,
+
See also :, [p_Ccomma]. HERE, @,
@@ -1422,6 +1650,7 @@ Address) of the word. The header memory layout is as follows:
+
Layout 1: rrqforth word structure
struct WORD
TFA 8 link ; tfa of previous word
@@ -1448,10 +1677,10 @@ function words initiated by ":" (aka "COLON") or changed to "dovalue"
for RRQFORTH constants created by "CONSTANT".
-
-
Definition concept 8: Word: CREATE
+
-