X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=reference.html;h=0fc06e19112a3d6eea43df52850d7670d96558cd;hb=aa6d10c30115571b859b9e7e3d6e8a9b9ced599b;hp=f57f5c8805811feb0fa67dcb88aee1b7a7ee5d6d;hpb=c8819ee75b180664d649f542f4448122f6c4cdce;p=rrq%2Frrqforth.git diff --git a/reference.html b/reference.html index f57f5c8..0fc06e1 100644 --- a/reference.html +++ b/reference.html @@ -832,7 +832,8 @@ asciidoc.install();

IF   IFAGAIN   IFBREAK   -IMMEDIATE  

+IMMEDIATE   +INPUT  

LIT   LOAD-FILE"  

MAIN-ARGS   @@ -905,6 +906,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 +924,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 +947,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 +963,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 +986,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 +1022,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 +1058,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 +1094,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 +1116,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 +1272,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 +1289,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 +1321,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 +1343,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 +1363,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
+;
+
+
+

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

_______________________________________________________
@@ -1373,10 +1445,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 +1469,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 +1494,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 +1521,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 +1532,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 +1566,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 +1601,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 +1728,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 +2012,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 +2150,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 +2231,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 +2256,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 +2328,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, @@ -2268,6 +2339,19 @@ the most recent word to 1, thereby making that word an immediate word.

_______________________________________________________
+

+
+
+

Word: INPUT

+
+
+
Data stack: ( -- a )
+
+

"INPUT" is a variable word for the input stream buffer used by +EVALUATE-STREAM.

+
+_______________________________________________________ +

@@ -2281,10 +2365,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 +2418,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 +2440,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 +2554,10 @@ _______________________________________________________ on the data stack.

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

: NIP SWAP DROP ;

@@ -2521,14 +2605,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 +2834,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 +2899,10 @@ _______________________________________________________ by means of adding an EXIT

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

: ; IMMEDIATE ' EXIT , ;

@@ -2941,7 +3017,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 +3034,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 +3210,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 +3232,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 +3298,10 @@ _______________________________________________________
 cell on the data stack.

 

 

-

-
Definition concept 22: Word: TUCK

+

 

-
: TUCK SWAP OVER ;

+
Definition concept for TUCK

+
: TUCK SWAP OVER ;

 

 

 

@@ -3272,10 +3348,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 ;

 

 

 

@@ -3335,7 +3411,7 @@ is deepest.