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.

+

See also 1BRANCH, BRANCH, IF, +ELSE, IFBREAK and IFAGAIN.

_______________________________________________________
@@ -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.

-

Compare with NOT.

+

This is the same function as NOT.

_______________________________________________________
@@ -951,14 +962,13 @@ _______________________________________________________ less than 0, and 0 otherwise.

-
-
Definition concept 1: Word: 0<
+
-
: 0= 0 SWAP < ;
+
Definition concept for 0<
+

( v — 0/1 ) : 0= 0 SWAP < ;

-

See also SWAP and -<.

+

See also SWAP and <.

_______________________________________________________
@@ -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.

+

See also 0BRANCH, BRANCH, IF, +ELSE, IFBREAK and IFAGAIN.

_______________________________________________________
@@ -1003,10 +1021,10 @@ _______________________________________________________ stack.

-
-
Definition concept 2: Word: 2DUP
+
-
: 2DUP OVER OVER ;
+
Definition concept for 2DUP
+

( v1 v2 — v1 v2 v1 v2 ) : 2DUP OVER OVER ;

@@ -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
+
-
: 2OVER 3 PICK 3 PICK ;
+
Definition concept for 2OVER
+

( v1 v2 v3 v4 — v1 v2 v3 v4 v1 v2 ) : 2OVER 3 PICK 3 PICK ;

@@ -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
+
-
: 2SWAP 3 ROLL 3 ROOL ;
+
Definition concept for 2SWAP
+

( v1 v2 v3 v4 — v3 v4 v1 v2 ) : 2SWAP 3 ROLL 3 ROLL ;

@@ -1097,10 +1115,10 @@ _______________________________________________________ at the current free head address, which also is incremented.

-
-
Definition concept 5: Word: C,
+
-
: C, HERE @ 1 ALLOT C! ;  ( v -- ; Claim 1 byte and put lsb value there )
+
Definition concept for C,
+

: C, HERE @ 1 ALLOT C! ; ( v — ; Claim 1 byte and put lsb value there )

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.

+
+
+
+
+
Definition concept for [']
+

: ['] IMMEDIATE ' ;

+
+
_______________________________________________________
@@ -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.

+

See also 0BRANCH, 1BRANCH, IF, +ELSE, IFBREAK and IFAGAIN.

_______________________________________________________
@@ -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
+;
+
+
+

See also BRANCH, 0BRANCH, +1BRANCH, IF, ELSE, +IFBREAK and IFAGAIN.

_______________________________________________________
@@ -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: :
+
-
: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;
+
Definition concept for :
+

: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;

See also doFORTH, READ-WORD, @@ -1397,10 +1467,10 @@ _______________________________________________________ HERE heap.

-
-
Definition concept7: Word: ,
+
-
: , HERE @ 8 ALLOT ! ; ( v -- ; Claim 8 bytes and put value there )
+
Definition concept for ,
+

: , HERE @ 8 ALLOT ! ; ( v — ; Claim 8 bytes and put value there )

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
+
-
HERE @ R> ( save tfa on RS )
+
Definition concept for CREATE

+
HERE @ R> ( save tfa on RS )
   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
   DUP 49 + R@ + ,             ( pCFA )
   0 ,                         ( flags )
@@ -1459,13 +1530,16 @@ for RRQFORTH constants created by "CONSTANT".

   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )
   R@ ,                        ( pTFA )
   0 ,                         ( OFF )
-  doVARIABLE                  ( CFA, default semantics )
+ doVARIABLE ( CFA, default semantics )

-
+
+
+
+
Usage example 5: a possible definition of CONSTANT
-
Usage example: a possible definition of CONSTANT
-

: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;

+
: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;
+

See also !, +, [p_comma], @, [p_Ccomma], CURRENT-WORD, DUP, @@ -1490,7 +1564,7 @@ word list word content is as follows:

-
Layout 1: word list word content
+
Layout 2: word list word content
  8 TFA of latest word in the word list
   8 DFA of the/a subsequent word list to search through
@@ -1525,10 +1599,10 @@ _______________________________________________________

"DECIMAL" is a function word that sets BASE to 10.

-
-
Definition concept 9: Word: DECIMAL
+
-
: DECIMAL 10 BASE ! ;
+
Definition concept for DECIMAL
+

: DECIMAL 10 BASE ! ;

@@ -1652,16 +1726,16 @@ offset to the current heap address. I.e., the word being defined will have its execution start at whatever comes after "DOES>".

-
-
Word: DOES>
+
-
: DOES> IMMEDIATE
+
Defintion concept for DOES>

+
: DOES> IMMEDIATE
 STATE @ != IF ( only for compilation mode )
   CURRENT-WORDLIST @ @ TFA>CFA    ( cfa of current word )
     doDOES OVER !                 ( set up doer )
     HERE @ OVER 8 + - SWAP 8 - !  ( set up offset
   THEN
-;
+;

See also @@ -1936,14 +2010,6 @@ execution.

stack while reading, parsing and executing.

If "EVALUATE-STREAM" ends with 0, then THIS-WORD holds the [n:chars] reference of the offending word in the stream buffer.

-
-
-
-
Definition concept 10: Word: EVALUATE-STREAM
-
-
( too complex to include here )
-
-
_______________________________________________________
@@ -2082,10 +2148,10 @@ _______________________________________________________ then decrements the cell at that address by n.

-
-
Defintion concept 11Word: @n++
+
-
: @n++ OVER @ DUP ROT - ROT ! ;
+
Defintion concept for @n++
+

: @n++ OVER @ DUP ROT - ROT ! ;

@@ -2163,10 +2229,13 @@ _______________________________________________________

"HERE" is a variable word that keeps the lowest address of the free allocation space. It get updated by all words that allocate memory.

+
+
-
Usage example
-

1024 HEAP @ + HEAP ! ( allocate 1024 bytes on the heap )

+
allocate 1024 bytes on the heap
+

1024 HEAP @ + HEAP !

+

See also ALLOT.

@@ -2185,10 +2254,10 @@ letters a-f as additional digits. (Uppercase letter are also accepted on input).

-
-
Definition concept 12: Word: HEX
+
-
: HEX 16 BASE ! ;
+
Definition concept for HEX
+

: HEX 16 BASE ! ;

@@ -2257,10 +2326,10 @@ _______________________________________________________ the most recent word to 1, thereby making that word an immediate word.

-
-
Definition concept 13:Word: IMMEDIATE
+
-
: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;
+
Definition concept for IMMEDIATE
+

: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;

See also :, CURRENT-WORDLIST, @@ -2281,10 +2350,10 @@ mode to be intepreting. In this mode, words are executed immediately after parsing, by invoking their "doer".

-
-
Definition concept 14: Word: [
+
-
: [ IMMEDIATE 0 STATE ! ;
+
Definition concept for [
+

: [ IMMEDIATE 0 STATE ! ;

@@ -2334,10 +2403,10 @@ with the CFA pointer following the value.

It’s not a good idea to use "LIT" interactively.

-
-
Definition concept 15: Word: LIT
+
-
: LIT R> DUP 8 + >R @ ;
+
Definition concept for LIT
+

: LIT R> DUP 8 + >R @ ;

@@ -2356,10 +2425,10 @@ inlined subsequently to it in the containing definition. This is similar to LIT but for a string literal.

-
-
Definition concept 16: Word: LIT
+
-
: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;
+
Definition concept for LIT
+

: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;

@@ -2470,10 +2539,10 @@ _______________________________________________________ on the data stack.

-
-
Definition concept 17: Word: NIP
+
-
: NIP SWAP DROP ;
+
Definition concept for NIP
+

: NIP SWAP DROP ;

@@ -2521,14 +2590,6 @@ a 1 on top, or just a 0 if the word didn’t parse.

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.

-
-
-
-
Definition concept 18: Word: NUMBER
-
-
( too complex to include here )
-
-
_______________________________________________________
@@ -2758,10 +2819,10 @@ left on the stack.

wordlist; i.e., the word list may contain definitions for numbers.

-
-
Definition concept 19: Word: ]
+
-
: ] 1 STATE ! ;
+
Definition concept for ]
+

: ] 1 STATE ! ;

@@ -2823,10 +2884,10 @@ _______________________________________________________ by means of adding an EXIT

-
-
Definition concept 20: Word: :
+
-
: ; IMMEDIATE ' EXIT , ;
+
Definition concept for ;
+

: ; IMMEDIATE ' EXIT , ;

@@ -2941,7 +3002,7 @@ prefixed by a 32 byte STREAM header of the following layout:

-
Stream layout 2, for file descriptor
+
Layout 3: file descriptor stream
  8 bytes = size of buffer (excluding the 32 byte header)
   8 bytes source file descriptor
@@ -2958,7 +3019,7 @@ following layout:
-
Stream layout 3, for memory block
+
Layout 4: memory block stream
  8 bytes = block address
   8 -1 (indicates memory block)
@@ -3134,10 +3195,10 @@ _______________________________________________________
 
"TFA>FLAGS@" is a function word that pushes word flags of the given tfa.

 

 

-

-
Defintion concept 21Word: TFA>FLAGS@

+

 

-
: TFA>FLAGS@ 16 + @ ;

+
Defintion concept for TFA>FLAGS@

+
: TFA>FLAGS@ 16 + @ ;

 

 

 

@@ -3156,10 +3217,10 @@ pointer to the word pname’s character sequence, which is zero
 terminated as well as preceded by a length cell.

 

 

-

-
Defintion concept for TFA>NAMEZ

+

 

-
: TFA>NAMEZ 32 + ;

+
Defintion concept for TFA>NAMEZ

+
: TFA>NAMEZ 32 + ;

 

 

 

@@ -3222,10 +3283,10 @@ _______________________________________________________
 cell on the data stack.

 

 

-

-
Definition concept 22: Word: TUCK

+

 

-
: TUCK SWAP OVER ;

+
Definition concept for TUCK

+
: TUCK SWAP OVER ;

 

 

 

@@ -3272,10 +3333,10 @@ of the the first, v, is within the value range spanned by the second,
 lo, inclusive and third, hi, exclusive.

 

 

-

-
Definition concept 23: Word: WITHIN

+

 

-
: WITHIN 2 PICK > ROT ROT <= AND ;

+
Definition concept for WITHIN

+
: WITHIN 2 PICK > ROT ROT ⇐ AND ;