From: Ralph Ronnquist
Date: Wed, 2 Jun 2021 13:38:50 +0000 (+1000)
Subject: standardized call-out blocks
X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;ds=inline;h=9b8fcf87eaed58b6dfabcf885f8eef5484643de6;p=rrq%2Frrqforth.git
standardized call-out blocks
---
diff --git a/adoc/inline_code.adoc b/adoc/inline_code.adoc
index b1a9c46..d85166c 100644
--- a/adoc/inline_code.adoc
+++ b/adoc/inline_code.adoc
@@ -20,3 +20,6 @@ RRQFORTH executon by means of the following instruction sequence:
forthcode:
----
====
+
+Note that the FORTH compiler does not invoke an assembler so any
+inline assembly code must be provided in its binary form.
diff --git a/adoc/p_0branch.adoc b/adoc/p_0branch.adoc
index a11ec49..6488d62 100644
--- a/adoc/p_0branch.adoc
+++ b/adoc/p_0branch.adoc
@@ -14,3 +14,13 @@ 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.
+
+See also <>, <>, <>,
+<>, <> and <>.
diff --git a/adoc/p_0equal.adoc b/adoc/p_0equal.adoc
index 827c0f1..8e5379c 100644
--- a/adoc/p_0equal.adoc
+++ b/adoc/p_0equal.adoc
@@ -13,4 +13,4 @@ Data stack: ( v -- 0/-1 )
complement; the result is zero if the value non-zero, and the result
is non-zero if the value is zero.
-Compare with <>.
+This is the same function as <>.
diff --git a/adoc/p_0less.adoc b/adoc/p_0less.adoc
index b068b63..b5c1f5e 100644
--- a/adoc/p_0less.adoc
+++ b/adoc/p_0less.adoc
@@ -12,12 +12,10 @@ Data stack: ( v -- 0/-1 )
less than 0, and 0 otherwise.
====
-.Word: 0<
-[caption='Definition concept {counter:exec}: ']
-----
-: 0= 0 SWAP < ;
-----
+.Definition concept for 0<
+****
+( v -- 0/1 ) : 0= 0 SWAP < ;
+****
====
-See also <> and
-<>.
+See also <> and <>.
diff --git a/adoc/p_1branch.adoc b/adoc/p_1branch.adoc
index 0483d00..8d1b7ca 100644
--- a/adoc/p_1branch.adoc
+++ b/adoc/p_1branch.adoc
@@ -14,3 +14,12 @@ 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.
+
+See also <>, <>, <>,
+<>, <> and <>.
diff --git a/adoc/p_2dup.adoc b/adoc/p_2dup.adoc
index 0b39b08..d425131 100644
--- a/adoc/p_2dup.adoc
+++ b/adoc/p_2dup.adoc
@@ -12,9 +12,8 @@ Data stack: ( v1 v2 -- v1 v2 v1 v2 )
stack.
====
-.Word: 2DUP
-[caption='Definition concept {counter:exec}: ']
-----
-: 2DUP OVER OVER ;
-----
+.Definition concept for 2DUP
+****
+( v1 v2 -- v1 v2 v1 v2 ) : 2DUP OVER OVER ;
+****
====
diff --git a/adoc/p_2over.adoc b/adoc/p_2over.adoc
index 058bfdd..fcfc184 100644
--- a/adoc/p_2over.adoc
+++ b/adoc/p_2over.adoc
@@ -13,10 +13,8 @@ onto the top of the data stack. This is similar to <> but
working with cell pairs rather than single cells.
====
-.Word: 2OVER
-[caption='Definition concept {counter:exec}: ']
-----
-: 2OVER 3 PICK 3 PICK ;
-----
+.Definition concept for 2OVER
+****
+( v1 v2 v3 v4 -- v1 v2 v3 v4 v1 v2 ) : 2OVER 3 PICK 3 PICK ;
+****
====
-
diff --git a/adoc/p_2swap.adoc b/adoc/p_2swap.adoc
index 6c123cf..2c03e49 100644
--- a/adoc/p_2swap.adoc
+++ b/adoc/p_2swap.adoc
@@ -13,9 +13,8 @@ the upper and lower pair. This is similar to <> but
working with cell pairs rather than single cells.
====
-.Word: 2SWAP
-[caption='Definition concept {counter:exec}: ']
-----
-: 2SWAP 3 ROLL 3 ROOL ;
-----
+.Definition concept for 2SWAP
+****
+( v1 v2 v3 v4 -- v3 v4 v1 v2 ) : 2SWAP 3 ROLL 3 ROLL ;
+****
====
diff --git a/adoc/p_Ccomma.adoc b/adoc/p_Ccomma.adoc
index a0b07cd..75992a8 100644
--- a/adoc/p_Ccomma.adoc
+++ b/adoc/p_Ccomma.adoc
@@ -14,11 +14,10 @@ Data stack: ( v -- )
at the current free head address, which also is incremented.
====
-.Word: C,
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for C,
+****
: C, HERE @ 1 ALLOT C! ; ( v -- ; Claim 1 byte and put lsb value there )
-----
+****
====
See also <>, <>. <>, <>,
diff --git a/adoc/p_base.adoc b/adoc/p_base.adoc
index fe6d66f..a8748b7 100644
--- a/adoc/p_base.adoc
+++ b/adoc/p_base.adoc
@@ -17,9 +17,3 @@ supported.
See also <>, which holds the mapping table from
digits to text.
-
-====
-.Usage example {counter:example}: claim 16 bytes for variable FOO
-[caption='Usage example {counter:example}: ']
-CREATE FOO BASE
-====
diff --git a/adoc/p_begin.adoc b/adoc/p_begin.adoc
index ca4f1af..da124ab 100644
--- a/adoc/p_begin.adoc
+++ b/adoc/p_begin.adoc
@@ -14,3 +14,21 @@ 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 {counter:example}:
+----
+: 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
+;
+----
+====
diff --git a/adoc/p_bracketed_quote.adoc b/adoc/p_bracketed_quote.adoc
index 74e15a3..b7a231c 100644
--- a/adoc/p_bracketed_quote.adoc
+++ b/adoc/p_bracketed_quote.adoc
@@ -11,3 +11,10 @@ Data stack: ( -- cfa ) Input stream: word
"[']" is an immediate function word that reads the next word on the
input stream and pushes its cfa.
+====
+.Definition concept for [']
+****
+: ['] IMMEDIATE ' ;
+****
+====
+
diff --git a/adoc/p_branch.adoc b/adoc/p_branch.adoc
index 089e238..02f7319 100644
--- a/adoc/p_branch.adoc
+++ b/adoc/p_branch.adoc
@@ -11,3 +11,13 @@ Data stack: ( -- )
"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.
+
+See also <>, <>, <>,
+<>, <> and <>.
diff --git a/adoc/p_break.adoc b/adoc/p_break.adoc
index f7da196..dec6fd7 100644
--- a/adoc/p_break.adoc
+++ b/adoc/p_break.adoc
@@ -9,3 +9,24 @@ branch out of an enclosing xef:p_begin[BEGIN]-xref:p_end[END] block.
Similar to xref:p_ifbreak[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 {counter:example}: 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
+ END
+ DROP
+ NL EMIT
+;
+----
+====
+
+See also <>, <>,
+<>, <>, <>,
+<> and <>.
diff --git a/adoc/p_colon.adoc b/adoc/p_colon.adoc
index 3a5acec..86b9104 100644
--- a/adoc/p_colon.adoc
+++ b/adoc/p_colon.adoc
@@ -14,11 +14,10 @@ This includes reading the next word for making a new dictionary entry
and setting evaluation state to compiling mode.
====
-.Word: :
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for :
+****
: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;
-----
+****
====
See also <>, <>,
diff --git a/adoc/p_comma.adoc b/adoc/p_comma.adoc
index ae00035..f3064b7 100644
--- a/adoc/p_comma.adoc
+++ b/adoc/p_comma.adoc
@@ -13,11 +13,10 @@ Data stack: ( v -- )
<> heap.
====
-.Word: ,
-[caption='Definition concept{counter:exec}: ']
-----
+.Definition concept for ,
+****
: , HERE @ 8 ALLOT ! ; ( v -- ; Claim 8 bytes and put value there )
-----
+****
====
See also <>, <>. <>, <>,
diff --git a/adoc/p_create.adoc b/adoc/p_create.adoc
index cf8914e..5fdfe27 100644
--- a/adoc/p_create.adoc
+++ b/adoc/p_create.adoc
@@ -14,6 +14,8 @@ indicated [n:char*] print name, and returns the "TFA" (Token Field
Address) of the word. The header memory layout is as follows:
====
+.rrqforth word structure
+[caption='Layout {counter:layout}: ']
----
struct WORD
TFA 8 link ; tfa of previous word
@@ -42,9 +44,8 @@ function words initiated by ":" (aka "COLON") or changed to "dovalue"
for RRQFORTH constants created by "CONSTANT".
====
-.Word: CREATE
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for CREATE
+****
HERE @ R> ( save tfa on RS )
R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
DUP 49 + R@ + , ( pCFA )
@@ -54,13 +55,16 @@ HERE @ R> ( save tfa on RS )
R@ , ( pTFA )
0 , ( OFF )
doVARIABLE ( CFA, default semantics )
-----
+****
====
-.Usage example: a possible definition of CONSTANT
-****
+====
+.a possible definition of CONSTANT
+[caption='Usage example {counter:example}: ']
+----
: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;
-****
+----
+====
See also <>, <>, <>, <>,
<>, <>, <>,
diff --git a/adoc/p_current_wordlist.adoc b/adoc/p_current_wordlist.adoc
index 91d9240..a5ab031 100644
--- a/adoc/p_current_wordlist.adoc
+++ b/adoc/p_current_wordlist.adoc
@@ -10,6 +10,7 @@ Data stack: ( -- a )
"CURRENT-WORDLIST" is a variable word that points out the DFA of the
current word list word for <> to use finding words. The
word list word content is as follows:
+
====
.word list word content
[caption='Layout {counter:layout}: ']
diff --git a/adoc/p_decimal.adoc b/adoc/p_decimal.adoc
index b06e5f2..2925653 100644
--- a/adoc/p_decimal.adoc
+++ b/adoc/p_decimal.adoc
@@ -12,9 +12,8 @@ Data stack: ( -- )
"DECIMAL" is a function word that sets <> to 10.
====
-.Word: DECIMAL
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for DECIMAL
+****
: DECIMAL 10 BASE ! ;
-----
+****
====
diff --git a/adoc/p_does.adoc b/adoc/p_does.adoc
index a9ac349..b31b42b 100644
--- a/adoc/p_does.adoc
+++ b/adoc/p_does.adoc
@@ -15,8 +15,8 @@ offset to the current heap address. I.e., the word being defined will
have its execution start at whatever comes after "DOES>".
====
-.Word: DOES>
-----
+.Defintion concept for DOES>
+****
: DOES> IMMEDIATE
STATE @ != IF ( only for compilation mode )
CURRENT-WORDLIST @ @ TFA>CFA ( cfa of current word )
@@ -24,7 +24,7 @@ STATE @ != IF ( only for compilation mode )
HERE @ OVER 8 + - SWAP 8 - ! ( set up offset
THEN
;
-----
+****
====
See also
diff --git a/adoc/p_evaluate_stream.adoc b/adoc/p_evaluate_stream.adoc
index ec54379..abd86d5 100644
--- a/adoc/p_evaluate_stream.adoc
+++ b/adoc/p_evaluate_stream.adoc
@@ -42,12 +42,3 @@ stack while reading, parsing and executing.
If "EVALUATE-STREAM" ends with 0, then <> holds
the [n:chars] reference of the offending word in the stream buffer.
-====
-.Word: EVALUATE-STREAM
-[caption='Definition concept {counter:exec}: ']
-----
-( too complex to include here )
-----
-====
-
-
diff --git a/adoc/p_get_n_decrement.adoc b/adoc/p_get_n_decrement.adoc
index b419099..9f22ca3 100644
--- a/adoc/p_get_n_decrement.adoc
+++ b/adoc/p_get_n_decrement.adoc
@@ -12,9 +12,8 @@ Data stack: ( a n -- v )
then decrements the cell at that address by n.
====
-.Word: @n++
-[caption='Defintion concept {counter:exec}']
-----
+.Defintion concept for @n++
+****
: @n++ OVER @ DUP ROT - ROT ! ;
-----
+****
====
diff --git a/adoc/p_here.adoc b/adoc/p_here.adoc
index 5a6c416..66aa8ed 100644
--- a/adoc/p_here.adoc
+++ b/adoc/p_here.adoc
@@ -12,9 +12,12 @@ Data stack: ( -- a )
allocation space. It get updated by all words that allocate memory.
-.Usage example
+====
+.allocate 1024 bytes on the heap
+[caption='Usage example {counter:example} ']
****
-1024 HEAP @ + HEAP ! ( allocate 1024 bytes on the heap )
+1024 HEAP @ + HEAP !
****
+====
See also <>.
diff --git a/adoc/p_hex.adoc b/adoc/p_hex.adoc
index 35ef0ff..cdefe59 100644
--- a/adoc/p_hex.adoc
+++ b/adoc/p_hex.adoc
@@ -13,9 +13,8 @@ letters a-f as additional digits. (Uppercase letter are also accepted
on input).
====
-.Word: HEX
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for HEX
+****
: HEX 16 BASE ! ;
-----
+****
====
diff --git a/adoc/p_immediate.adoc b/adoc/p_immediate.adoc
index 5e887fe..154aa3a 100644
--- a/adoc/p_immediate.adoc
+++ b/adoc/p_immediate.adoc
@@ -12,11 +12,10 @@ Data stack: ( -- )
the most recent word to 1, thereby making that word an immediate word.
====
-.Word: IMMEDIATE
-[caption='Definition concept {counter:exec}:']
-----
+.Definition concept for IMMEDIATE
+****
: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;
-----
+****
====
See also <>, <>,
diff --git a/adoc/p_left_bracket.adoc b/adoc/p_left_bracket.adoc
index ead7d3b..ecd77bf 100644
--- a/adoc/p_left_bracket.adoc
+++ b/adoc/p_left_bracket.adoc
@@ -13,10 +13,8 @@ mode to be intepreting. In this mode, words are executed immediately
after parsing, by invoking their "doer".
====
-.Word: [
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for [
+****
: [ IMMEDIATE 0 STATE ! ;
-----
+****
====
-
diff --git a/adoc/p_literal.adoc b/adoc/p_literal.adoc
index 35d98da..5a50f2d 100644
--- a/adoc/p_literal.adoc
+++ b/adoc/p_literal.adoc
@@ -17,11 +17,10 @@ with the CFA pointer following the value.
It's not a good idea to use "LIT" interactively.
====
-.Word: LIT
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for LIT
+****
: LIT R> DUP 8 + >R @ ;
-----
+****
====
diff --git a/adoc/p_literal_string.adoc b/adoc/p_literal_string.adoc
index 218f443..ba94b0f 100644
--- a/adoc/p_literal_string.adoc
+++ b/adoc/p_literal_string.adoc
@@ -13,11 +13,9 @@ inlined subsequently to it in the containing definition. This is
similar to <> but for a string literal.
====
-.Word: LIT
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for LIT
+****
: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;
-----
+****
====
-
diff --git a/adoc/p_nip.adoc b/adoc/p_nip.adoc
index 8e14946..1f99710 100644
--- a/adoc/p_nip.adoc
+++ b/adoc/p_nip.adoc
@@ -12,9 +12,8 @@ Data stack: ( v1 v2 -- v2 )
on the data stack.
====
-.Word: NIP
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for NIP
+****
: NIP SWAP DROP ;
-----
+****
====
diff --git a/adoc/p_number.adoc b/adoc/p_number.adoc
index d3bcce5..c875971 100644
--- a/adoc/p_number.adoc
+++ b/adoc/p_number.adoc
@@ -18,10 +18,3 @@ base, letters a-f or A-F for values 10-15. I.e. the normal positive or
negative decimal integers or normal (positive only) hexadecimal
integers.
-====
-.Word: NUMBER
-[caption='Definition concept {counter:exec}: ']
-----
-( too complex to include here )
-----
-====
diff --git a/adoc/p_right_bracket.adoc b/adoc/p_right_bracket.adoc
index 218873a..580d7bf 100644
--- a/adoc/p_right_bracket.adoc
+++ b/adoc/p_right_bracket.adoc
@@ -19,9 +19,8 @@ Note that a word is parsed as a number only if it is not found in the
wordlist; i.e., the word list may contain definitions for numbers.
====
-.Word: ]
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for ]
+****
: ] 1 STATE ! ;
-----
+****
====
diff --git a/adoc/p_semicolon.adoc b/adoc/p_semicolon.adoc
index 1818e80..c16e147 100644
--- a/adoc/p_semicolon.adoc
+++ b/adoc/p_semicolon.adoc
@@ -13,10 +13,8 @@ Data stack: ( -- )
by means of adding an <>
====
-.Word: :
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for ;
+****
: ; IMMEDIATE ' EXIT , ;
-----
+****
====
-
diff --git a/adoc/p_stream.adoc b/adoc/p_stream.adoc
index cec3e9a..6143ef0 100644
--- a/adoc/p_stream.adoc
+++ b/adoc/p_stream.adoc
@@ -16,8 +16,8 @@ A file descriptor backed STREAM gains a buffer of the given size
prefixed by a 32 byte STREAM header of the following layout:
====
-.file descriptor
-[caption='Stream layout {counter:layout}, for ']
+.file descriptor stream
+[caption='Layout {counter:layout}: ']
----
8 bytes = size of buffer (excluding the 32 byte header)
8 bytes source file descriptor
@@ -33,8 +33,8 @@ A memory block stream is only the header (though allocated via
following layout:
====
-.memory block
-[caption='Stream layout {counter:layout}, for ']
+.memory block stream
+[caption='Layout {counter:layout}: ']
----
8 bytes = block address
8 -1 (indicates memory block)
diff --git a/adoc/p_tfa2flags_get.adoc b/adoc/p_tfa2flags_get.adoc
index 5ded0d4..8e5ed33 100644
--- a/adoc/p_tfa2flags_get.adoc
+++ b/adoc/p_tfa2flags_get.adoc
@@ -11,9 +11,8 @@ Data stack: ( tfa -- flags )
"TFA>FLAGS@" is a function word that pushes word flags of the given tfa.
====
-.Word: TFA>FLAGS@
-[caption='Defintion concept {counter:exec}']
-----
+.Defintion concept for TFA>FLAGS@
+****
: TFA>FLAGS@ 16 + @ ;
-----
+****
====
diff --git a/adoc/p_tfa2namez.adoc b/adoc/p_tfa2namez.adoc
index 074ead9..16db5db 100644
--- a/adoc/p_tfa2namez.adoc
+++ b/adoc/p_tfa2namez.adoc
@@ -14,7 +14,7 @@ terminated as well as preceded by a length cell.
====
.Defintion concept for TFA>NAMEZ
-----
+****
: TFA>NAMEZ 32 + ;
-----
+****
====
diff --git a/adoc/p_tuck.adoc b/adoc/p_tuck.adoc
index 965f0d3..452d163 100644
--- a/adoc/p_tuck.adoc
+++ b/adoc/p_tuck.adoc
@@ -12,9 +12,8 @@ Data stack ( v1 v2 -- v2 v1 v2 )
cell on the data stack.
====
-.Word: TUCK
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for TUCK
+****
: TUCK SWAP OVER ;
-----
+****
====
diff --git a/adoc/p_within.adoc b/adoc/p_within.adoc
index 911325f..ca23146 100644
--- a/adoc/p_within.adoc
+++ b/adoc/p_within.adoc
@@ -13,9 +13,8 @@ of the the first, v, is within the value range spanned by the second,
lo, inclusive and third, hi, exclusive.
====
-.Word: WITHIN
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for WITHIN
+****
: WITHIN 2 PICK > ROT ROT <= AND ;
-----
+****
====
diff --git a/reference.html b/reference.html
index f57f5c8..e07df55 100644
--- a/reference.html
+++ b/reference.html
@@ -905,6 +905,8 @@ RRQFORTH executon by means of the following instruction sequence:
forthcode:
+Note that the FORTH compiler does not invoke an assembler so any
+inline assembly code must be provided in its binary form.
_______________________________________________________
@@ -921,6 +923,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 +946,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 +962,13 @@ _______________________________________________________
less than 0, and 0 otherwise.
-
-
Definition concept 1: Word: 0<
+
-
+
_______________________________________________________
@@ -975,6 +985,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 +1021,10 @@ _______________________________________________________
stack.
-
-
Definition concept 2: Word: 2DUP
+
@@ -1039,10 +1057,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 +1093,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 +1115,10 @@ _______________________________________________________
at the current free head address, which also is incremented.
-
-
Definition concept 5: Word: C,
+
See also :, [p_comma]. HERE, @,
@@ -1253,10 +1271,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 +1288,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 +1320,14 @@ _______________________________________________________
"[']" is an immediate function word that reads the next word on the
input stream and pushes its cfa.
+
_______________________________________________________
@@ -1301,6 +1342,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 +1362,27 @@ 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
+ END
+ DROP
+ NL EMIT
+;
+
+
+
_______________________________________________________
@@ -1373,10 +1443,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 +1467,10 @@ _______________________________________________________
HERE heap.
-
-
Definition concept7: Word: ,
+
See also :, [p_Ccomma]. HERE, @,
@@ -1422,6 +1492,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 +1519,10 @@ function words initiated by ":" (aka "COLON") or changed to "dovalue"
for RRQFORTH constants created by "CONSTANT".
-
-
Definition concept 8: Word: CREATE
+
-