X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=reference.html;h=9137d075cfd0bd68e35fda305d8050d21cc8f636;hb=7a99f2ed7cfe55f3aa69560b31c055ce45fe1f0c;hp=f57f5c8805811feb0fa67dcb88aee1b7a7ee5d6d;hpb=c8819ee75b180664d649f542f4448122f6c4cdce;p=rrq%2Frrqforth.git diff --git a/reference.html b/reference.html index f57f5c8..9137d07 100644 --- a/reference.html +++ b/reference.html @@ -770,17 +770,24 @@ asciidoc.install(); !   C@   C!   +W@   +W!   +D@   +D!   2@   2!   !+   @n++   @n--   C,   -S"   +W,   +D,   +S"   >R   R@   R>   -R[n]  

+R[n]   +D[n]  

DATA-STACK   RETURN-STACK     @@ -793,6 +800,7 @@ asciidoc.install(); 2OVER   2SWAP  

ABS   +AGAIN   ALLOT   AND   [ASM]  

@@ -800,10 +808,12 @@ asciidoc.install(); BEGIN   BREAK  

CFA>FLAGS@   +CFA>TFA   CLEAR-STREAM   CREATE   CURRENT-WORDLIST  

DECIMAL   +DEFINITIONS   DEPTH   DIGITS   /MOD   @@ -825,6 +835,8 @@ asciidoc.install(); EXECUTE   EXIT  

FALSE   +FDEMIT   +FDTELL   FIND   FORTH  

HERE   @@ -832,17 +844,22 @@ asciidoc.install();

IF   IFAGAIN   IFBREAK   -IMMEDIATE  

+IMMEDIATE   +INPUT  

LIT   -LOAD-FILE"  

+LIT-STRING   +LOAD-BUFFER-SIZE   +LOAD-FILE  

MAIN-ARGS   -MALLOC  

+MALLOC   +MIN   +MAX  

NEGATE   NIP   NL   NOT   NUMBER  

-

OPEN-FILE"   +

OPEN-FILE   OR   OVER  

PAD   @@ -850,21 +867,30 @@ asciidoc.install(); PROGRAM_VERSION  

QUIT  

READ-STREAM-CHAR   +READ-STREAM-LINE   READ-WORD   REALLOC   +RETURN   ROLL   -ROT  

+ROT   +RSP  

SP   STATE   STDIN   STREAM   STREAM-NCHARS   +STR>TEMP   STRLEN   STRNCMP   STRNCPY   SWAP   SYSTEM  

TELL   +.TEMP   +TEMP   +TEMPHELD   +TEMPSPACE   +TEMPUSED   TERMINATE0   TFA>CFA   TFA>DFA   @@ -874,6 +900,8 @@ asciidoc.install(); THIS-WORD   TRUE   TUCK  

+

UNSTREAM   +USE  

VERBOSE?  

WITHIN   WORDS  

@@ -905,6 +933,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 +951,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 +974,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 +990,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 +1013,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 +1049,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 +1085,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 +1121,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 +1143,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, @, @@ -1108,6 +1154,85 @@ at the current free head address, which also is incremented.

_______________________________________________________
+

+
+
+

Word: W,

+
+
+
Data stack: ( v -- )
+
+

"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.

+
+
+
+
+
Definition concept for W,
+

: W, HERE @ 2 ALLOT W! ;

+
+
+
+_______________________________________________________ +
+

+
+
+

Word: D,

+
+
+
Data stack: ( v -- )
+
+

"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.

+
+
+
+
+
Definition concept for D,
+

: D, HERE @ 4 ALLOT D! ;

+
+
+
+_______________________________________________________ +
+

+
+
+

Word: D[n]

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

"D[n]" is a function word that pushes the address for the n:th cell of +the data stack onto the data stack.

+
+_______________________________________________________ +
+

+
+
+

Word: CFA>TFA

+
+
+
Data stack: ( cfa -- tfa )
+
+

"CFA>TFA" is a function word that pushes word tfa of the given cfa.

+
+
+
+
+
Definition concept for CFA>TFA
+

: CFA>TFA 14 - @ ;

+
+
+
+_______________________________________________________ +

@@ -1120,6 +1245,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 +1284,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 +1349,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.

+
+_______________________________________________________ +

@@ -1221,7 +1415,8 @@ _______________________________________________________

"ARGS" is a value word that holds a pointer to the command line data block which consists of a count cell followed by that many asciiz -pointers and then a 0 cell.

+pointers and then a 0 cell. That is next followed by the environment +as a number of asciiz pointers and a 0 cell.

@@ -1229,9 +1424,10 @@ pointers and then a 0 cell.

ARGS -> 8 bytes: count of non-zero asciiz pointers following
         8 bytes: command name string
-        8 bytes: first argument string
-        8* ...
-        8 zero
+ 8* bytes: argument strings + 8 bytes: zero cell + 8* bytes: envirnment strings + 8 bytes: zero cell
@@ -1253,10 +1449,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 +1466,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 +1498,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 +1520,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 +1540,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 +1622,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 +1646,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 +1671,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 +1698,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 +1709,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 +1743,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 +1778,31 @@ _______________________________________________________

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

-
-
Definition concept 9: Word: DECIMAL
+
+
+
Definition concept for DECIMAL
+

: DECIMAL 10 BASE ! ;

+
+
+
+_______________________________________________________ +
+

+
+
+

Word: DEFINITIONS

+
+
+
Data stack: ( wordlist -- )
+
+

"DEFINITIONS" is a function word that installs the given wordlist as +the CURRENT-WORDLIST one.

+
-
: DECIMAL 10 BASE ! ;
+
+
+
Definition concept for DEFINITIONS
+

: DEFINITIONS CURRENT-WORDLIST ! ;

@@ -1652,16 +1926,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 @@ -1749,6 +2023,23 @@ the current BASE (either DECIMAL

_______________________________________________________
+

+
+
+

Word: .TEMP

+
+
+
Data stack: ( v -- char* n )
+
+

".TEMP" is a function word that renders a cell value as an integer +using the current BASE, which is either +DECIMAL or HEX. In DECIMAL +BASE, a negative value is rendered as such with a leading +minus sign, whereas HEX BASE rendering is +unsigned.

+
+_______________________________________________________ +

@@ -1936,14 +2227,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 )
-
-
_______________________________________________________
@@ -2003,11 +2286,10 @@ _______________________________________________________

Word: EXIT

-
Data stack: ( -- )
+
Data stack: ( v -- )
-

"EXIT" is a function word that implements the ending of a FORTH -definition and its threading to the subsequent step of the calling -definition.

+

"EXIT" is a function word that terminates the rrqforth process +immediately with the given exit code.

_______________________________________________________
@@ -2023,6 +2305,33 @@ _______________________________________________________
_______________________________________________________
+

+
+
+

Word: FDEMIT

+
+
+
Data stack: ( c fd -- )
+
+

"FDEMIT" is a function word that puts the given character code to the +given file descriptor. The character is the least significant byte of +the data stack cell.

+
+_______________________________________________________ +
+

+
+
+

Word: FDTELL

+
+
+
Data stack: ( char* n fd -- )
+
+

"FDTELL" is a function word that prints a string to the given file +descriptor.

+
+_______________________________________________________ +

@@ -2082,10 +2391,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 +2472,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 +2497,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 +2569,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 +2580,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 +2606,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 +2659,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 @ ;

@@ -2346,38 +2671,72 @@ _______________________________________________________

-

Word: S"

+

Word: LIT-STRING

Data stack: ( -- chars* n )
-

"S"" is a function word that pushes the [n:char] pointer for a string -inlined subsequently to it in the containing definition. This is -similar to LIT but for a string literal.

+

"LIT-STRING" is a function word that pushes the char* and length n of +a subsequent inline string, then advances execution to continue after +the string. This is similar to LIT but for a block literal.

+

Note that the inlined byte count includes the terminating NUL byte.

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

: LIT-STRING R@ DUP @ 8 + R@ @ 2DUP + R> + >R 1 - ;

_______________________________________________________
-

+

-

Word: LOAD-FILE"

+

Word: S"

-
data stack: ( "name" -- )
+
Data stack: ( -- )  Input stream: " chars"
-

"LOAD-FILE"" is a function word that opens a file via -OPEN-FILE", allocates a stream buffer of 15000 -bytes for reading it, saves the stream pointer as value for the newly -created filename variable, and then it invokes -EVALUATE-STREAM for processing the file.

+

"S"" is an immediate function word that compiles the subseqent +characters up to terminating double-quote into the current definition, +preceded by a LIT-STRING cell, and the count of +bytes scanned. The inline text includes a terminating NUL character +which also is included in the inlined count.

+

Note that "S"" uses " for reading the string.

+
+_______________________________________________________ +
+

+
+
+

Word: LOAD-BUFFER-SIZE

+
+
+
data stack: ( -- a )
+
+

"LOAD-BUFFER-SIZE" is a variable word telling the buffer size in bytes +that LOAD-FILE should use.

+
+_______________________________________________________ +
+

+
+
+

Word: LOAD-FILE

+
+
+
data stack: ( chaz* -- * 0/1 )
+
+

"LOAD-FILE" is a function word that evaluates a text file. It opens a +file via OPEN-FILE and sets up a stream with a +buffer of LOAD-BUFFER-SIZE bytes for +reading it. The stream is passed to +EVALUATE-STREAM for processing its words. Upon +its return the file is closed and the stream memory is reclaimed, and +then the function returns whatever +EVALUATE-STREAM returns.

_______________________________________________________
@@ -2416,6 +2775,32 @@ page" of mmap for details.

_______________________________________________________
+

+
+
+

Word: MAX

+
+
+
Data stack: ( v1 v2 -- v3 )
+
+

"MAX" is a function word that selects the greatest of v1 and v2. To +that end, the values are 64-bit signed integers.

+
+_______________________________________________________ +
+

+
+
+

Word: MIN

+
+
+
Data stack: ( v1 v2 -- v3 )
+
+

"MIN" is a function word that selects the least of v1 and v2. To that +end, the values are 64-bit signed integers.

+
+_______________________________________________________ +

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

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

: NIP SWAP DROP ;

@@ -2521,28 +2906,20 @@ 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 )
-
-
_______________________________________________________
-

+

-

Word: OPEN-FILE"

+

Word: OPEN-FILE

-
Data stack: ( "name" -- fd )
+
Data stack: ( chaz* -- fd )
-

"OPEN-FILE"" is a function word that reads the intputstream for a -filename, adds that to the dictionary as a no-content variable, opens -that file and returns the input file descriptor.

+

"OPEN-FILE" is a function word that opens the file named by the zero +terminated character string and returns the file descriptor, or if +less than 0, the system call error code.

_______________________________________________________
@@ -2687,6 +3064,40 @@ word on the input stream and pushes its cfa.

_______________________________________________________
+

+
+
+

Word: RSP

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

"RSP" is a function word that pushes the return stack pointer value +onto the data stack.

+
+_______________________________________________________ +
+

+
+
+

Word: R[n]

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

"R[n]" is a function word that pushes the address for the n:th cell of +the return stack onto the data stack.

+
+
+
+
+
Defintion concept for R[n]
+

( n — a ) : R[n] 8 * RSP + ;

+
+
+
+_______________________________________________________ +

@@ -2705,6 +3116,22 @@ instead.

_______________________________________________________
+

+
+
+

Word: READ-STREAM-LINE

+
+
+
Data stack: ( stream -- n )
+
+

"READ-STREAM-LINE" is a function word that gets the next line from the +given stream buffer into PAD and returns number of characters. If the +stream is backed by a file descriptor, the stream buffer is refilled +from there as needed, by a SYS_READ call when more characters are +needed.

+
+_______________________________________________________ +

@@ -2718,6 +3145,18 @@ separated word from the given stream and returns the [n:char*] duoble cell pointer for it. The characters of the word are copied to PAD, and there is a limit of 1024 characters.

At the end of the stream READ-WORD returns 0 length.

+
+
Special syntax 1: Whitespace
+
+

All character codes less or equal to 32 are regarded as "whitespace".

+
+
+
Special syntax 2: Rest-of-line comment
+
+

The "#" character following whitespace starts a line comment and the +rest of the line is ignored. Note that this is also recognised with +parethesis commenting.

+
_______________________________________________________
@@ -2739,6 +3178,20 @@ kernel, and the granularity is in pages, i.e. a multiple of 4 kb.

_______________________________________________________
+

+
+
+

Word: RETURN

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

"RETURN" is a function word that implements the ending of a FORTH +definition and make execution return to the next step in the calling +definition.

+
+_______________________________________________________ +

compile.asm: WORD p_right_bracket,],fasm

@@ -2758,10 +3211,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 ! ;

@@ -2798,19 +3251,6 @@ and the first becomes the second.

_______________________________________________________
-

-
-
-

Word: R[n]

-
-
-
Data stack: ( n -- a )
-
-

"R[n]" is a function word that pushes the address for the n:th cell on -the top return stack value onto the data stack.

-
-_______________________________________________________ -

@@ -2819,14 +3259,15 @@ _______________________________________________________
Data stack: ( -- )
-

";" (semi-colon) is a function word that ends a new forth definition -by means of adding an EXIT

+

";" (semi-colon) is an immediate function word that ends a new forth +definition by means of adding an EXIT cell, then changing +<<p_state,STATE> to interpreting.

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

: ; IMMEDIATE ' EXIT , ;

@@ -2941,7 +3382,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 +3399,7 @@ following layout:

-
Stream layout 3, for memory block
+
Layout 4: memory block stream
  8 bytes = block address
   8 -1 (indicates memory block)
@@ -2985,6 +3426,29 @@ stream (or filling it by reading the backing file).

_______________________________________________________
+

+
+
+

Word: STR>TEMP

+
+
+

Data stack: ( char* n — char* n )

+
+

"STR>TEMP" is a function word that copies a given string plus a +terminating NUL character into a TEMPSPACE snippet, +all preceded by a length cell. It returns a pointer for to the text in +the snippet and its length, excluding the NUL character at end and the +length cell before tie text.

+
+
Layout for copied string
+
+
        length: 8 bytes
+returned char*: n bytes
+           nul: 1 byte
+
+
+_______________________________________________________ +

@@ -3070,6 +3534,90 @@ descriptor 1).

_______________________________________________________
+

+
+
+

Word: TEMP

+
+
+

Data stack: ( size — addr )

+
+

"TEMP" is a function word that "allocates" a TEMPSPACE +area of given size and returns its base address. The allocation is +temporary and only valid until there is a later allocation that +overruns this area.

+

Allocations are done in succession until the requested size overruns +the TEMPSPACE. If so, the allocation pointer is reset +and the space is allocated from start again. This is all intended for +small and short-lived data areas.

+
+_______________________________________________________ +
+

+
+
+

Word: TEMPHELD

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

"TEMPHELD" is a variable word that keeps the lowest offset of the +TEMPSPACE space to reuse upon cycling. The space +below TEMPHELD is "held" in the sense of not being reused upon +cycling. An application may change the TEMPSPACE offset as needed to +dynamically preserve memory longer term.

+
+_______________________________________________________ +
+

+
+
+

Word: TEMPSPACE

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

"TEMPSPACE" is a variable word that holds three cells the for managing +"temporary memory":

+
    +
  • +

    +the size of the temporary memory space (default 104857600 bytes) +

    +
  • +
  • +

    +the base address for whole temporary memory area +

    +
  • +
  • +

    +the amount currently used +

    +
  • +
+

This memory is intended to be used by requesting snippets of memory in +a cyclic fashion via TEMP without concern about it possibly +overlapping a prior request.

+
+_______________________________________________________ +
+

+
+
+

Word: TEMPUSED

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

"TEMPUSED" is a variable word that keeps the lowest offset of the +TEMPSPACE space to use next as temporary space. This +is advance upon each allocation via TEMP, and recycled back +to TEMPHELD when next allocation otherwise would exceed +the space size.

+
+_______________________________________________________ +

@@ -3134,10 +3682,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 +3704,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 +3770,10 @@ _______________________________________________________ cell on the data stack.

-
-
Definition concept 22: Word: TUCK
+
-
: TUCK SWAP OVER ;
+
Definition concept for TUCK
+

: TUCK SWAP OVER ;

@@ -3244,6 +3792,48 @@ values are unequal, and 0 otherwise.

_______________________________________________________
+

+
+
+

Word: UNSTREAM

+
+
+
Data stack: ( stream* -- )
+
+

"UNSTREAM" is a function word that releases the memory allocated for a +stream, and closes the associated file if it’s a file stream.

+
+

File descriptor backed stream

+

This kind of stream has the stream header as a prefix within the +allocated memory. Thus, stream* is the base address for the memory to +reclaim, and the size of this is determined from the cell at (stream* ++ 16) plus the 32 bytes head itself.

+
+
+

Memory block backed STREAM

+

This kind of stream has a separate header which points at the memory +area to reclaim. The cell at stream* is the base address, and the cell +at (stream* + 16) is its size.

+
+_______________________________________________________ +
+

+
+
+
+

Word: USE

+
+
+
Data value: ( wordlist -- )  Input stream: word
+
+

"USE" is a function word that looks up next word given the wordlist. +It reads next word on INPUT via READ-WORD, +then temporarily changes CURRENT-WORDLIST to +FIND the word via the given wordlist, and returns the TFA +of that word, or just 0 if the word coudn’t be found.

+
+_______________________________________________________ +

@@ -3272,10 +3862,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 +3925,7 @@ is deepest.