+// rrqforth.asm: WORD data_stack,'DATA-STACK',dovariable
+
anchor:data_stack
-Word: DATA-STACK
-----------------
+=== Word: DATA-STACK
-----
-rrqforth.asm: WORD data_stack,'DATA-STACK',dovariable
-----
+....
+Data stack: ( -- a )
+....
+"DATA-STACK" is a variable word that harbours the data stack.
+// rrqforth.asm: WORD inline_code,'[ASM]',fasm
+
anchor:inline_code[]
-Word: [ASM]
-----------
+=== Word: [ASM]
-----
-rrqforth.asm: WORD inline_code,'[ASM]',fasm
-----
+....
+data stack: ( -- )
+....
-"[ASM]" is a function word that introduces inlined assembly.
+"[ASM]" is a function word that introduces inline assembly in an
+RRQFORTH definition. Such assembly code may return to subsequence
+RRQFORTH executon by means of the following instruction sequence:
+====
+----
+ mov rsi,forthcode
+ lodsq
+ jmp qword [rax]
+forthcode:
+----
+====
+// rrqforth.asm: WORD p_zero_branch,'0BRANCH',fasm
+
anchor:p_zero_branch[]
-Word: 0BRANCH
--------------
+=== Word: 0BRANCH
+
+....
+Data stack: ( v -- )
+....
-----
-rrqforth.asm: WORD p_zero_branch,'0BRANCH',fasm
-----
+"0BRANCH" is a function word that implements execution conditional by
+means of optionally adding the subsequent branch offset, or not, to
+the point of execution. If the value, is 0 then the branch offset is
+added, and otherwise execution continues with the cell following the
+branch offset in the definition.
+// logic.asm: WORD p_0equal, '0=',fasm
+
anchor:p_0equal[]
-Word: 0=
-----------
+=== Word: 0=
+
+....
+Data stack: ( v -- 0/-1 )
+....
+
-----
-logic.asm: WORD p_0equal, '0=',fasm
-----
+"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 <<p_not,NOT>>.
+// logic.asm: WORD p_0less, '0<',fasm
+
anchor:p_0less[]
-Word: 0<
-----------
+=== Word: 0<
+
+....
+Data stack: ( v -- 0/-1 )
+....
+
+"0<" is a function word that replaces a value with -1 if the value is
+less than 0, and 0 otherwise.
+====
+.Word: 0<
+[caption='Definition concept {counter:exec}: ']
----
-logic.asm: WORD p_0less, '0<',fasm
+: 0= 0 SWAP < ;
----
+====
+See also <<p_swap,SWAP>> and
+<<p_lessthan,<>>.
+// stack.asm: WORD p_2drop, '2DROP',fasm
+
anchor:p_2drop[]
-Word: 2DROP
-----------
+=== Word: 2DROP
-----
-stack.asm: WORD p_2drop, '2DROP',fasm
-----
+....
+Data stack: ( v1 v2 -- )
+....
+"2DROP" is a function word that plainly discards the top 2 cells from
+the data stack.
+// stack.asm: WORD p_2dup, '2DUP',fasm
+
anchor:p_2dup[]
-Word: 2DUP
-----------
+=== Word: 2DUP
+
+....
+Data stack: ( v1 v2 -- v1 v2 v1 v2 )
+....
+"2DUP" is a function word that duplicates the top 2 cells on the data
+stack.
+
+====
+.Word: 2DUP
+[caption='Definition concept {counter:exec}: ']
----
-stack.asm: WORD p_2dup, '2DUP',fasm
+: 2DUP OVER OVER ;
----
-
+====
+// stack.asm: WORD p_2over, '2OVER',fasm
+
anchor:p_2over[]
-Word: 2OVER
-----------
+=== Word: 2OVER
+
+....
+Data stack: ( v1 v2 v3 v4 -- v1 v2 v3 v4 v1 v2 )
+....
+
+"2OVER" is a function word that replicates the second duble-cell pair
+onto the top of the data stack. This is similar to <<p_over,OVER>> but
+working with cell pairs rather than single cells.
+====
+.Word: 2OVER
+[caption='Definition concept {counter:exec}: ']
----
-stack.asm: WORD p_2over, '2OVER',fasm
+: 2OVER 3 PICK 3 PICK ;
----
+====
+// stack.asm: WORD p_2swap, '2SWAP',fasm
+
anchor:p_2swap[]
-Word: 2SWAP
-----------
+=== Word: 2SWAP
+
+....
+Data stack: ( v1 v2 v3 v4 -- v3 v4 v1 v2 )
+....
+"2SWAP" is a function word the reorgnizes the top 4 cells swappping
+the upper and lower pair. This is similar to <<p_swap,SWAP>> but
+working with cell pairs rather than single cells.
+
+====
+.Word: 2SWAP
+[caption='Definition concept {counter:exec}: ']
----
-stack.asm: WORD p_2swap, '2SWAP',fasm
+: 2SWAP 3 ROLL 3 ROOL ;
----
-
+====
-Word: C,
---------
+// compile.asm: WORD p_Ccomma,'C,',fasm
+
anchor:p_Ccomma[]
-----
-compile.asm: WORD p_Ccomma,'C,',fasm
-----
+=== Word: C,
+
+
+....
Data stack: ( v -- )
+....
-"C," is a function word that puts a byte on the heap. It stores the
-least significant byte of the value to the current free heap address,
-and increments that.
+"C," (C-comma) is a function word that puts a byte on the
+<<p_here,HERE>> heap. The least significant byte of the value is put
+at the current free head address, which also is incremented.
-.Execution semantics expressed in RRQFORTH
====
-: C,
- HERE @ 1 ALLOT C! ( v -- ; Claim 1 byte and put lsb value there )
-;
+.Word: C,
+[caption='Definition concept {counter:exec}: ']
+----
+: C, HERE @ 1 ALLOT C! ; ( v -- ; Claim 1 byte and put lsb value there )
+----
====
+See also <<p_colon,:>>, <<p_comma>>. <<p_here,HERE>>, <<p_get,@>>,
+<<p_allot,ALLOT>>, <<p_Cput,C!>> and <<p_semicolon,;>>.
+// stack.asm: WORD p_Rget, 'R@',fasm
+
anchor:p_Rget[]
-Word: R@
---------
+=== Word: R@
+
+....
+Data stack: ( -- v ) Return stack: ( v -- v )
+....
-----
-stack.asm: WORD p_Rget, 'R@',fasm
-----
+"R@" is a function word that "copies" the top return stack value onto
+the data stack.
+// stack.asm: WORD p_Rgt, 'R>',fasm
+
anchor:p_Rgt[]
-Word: R>
-----------
+=== Word: R>
-----
-stack.asm: WORD p_Rgt, 'R>',fasm
-----
+....
+Data stack: ( -- v ) Return stack: ( v -- )
+....
+"R>" is a function word that "moves" the top return stack value onto
+the data stack.
+// math.asm: WORD p_abs, 'ABS',fasm
+
anchor:p_abs[]
-Word: ABS
----------
+=== Word: ABS
-----
-math.asm: WORD p_abs, 'ABS',fasm
-----
+....
+Data stack: ( v1 -- v2 )
+....
+"ABS" is a function word that replaces a value with its absolute
+value. To that end, the values are 64-bit signed integers.
+// compile.asm: WORD p_allot,'ALLOT',fasm
+
anchor:p_allot[]
-Word: ALLOT
------------
-
-----
-compile.asm: WORD p_allot,'ALLOT',fasm
-----
+=== Word: ALLOT
+....
Data stack: ( n -- )
+....
-"ALLOT" is a function word that merely increments the "HERE" variable
-with +n+ so as to claim that amount of the allocation space.
+"ALLOT" is a function word that merely increments the <<p_here,HERE>>
+variable with +n+ so as to claim that amount of the heap.
-.Execution semantics expressed in RRQFORTH
====
-: ALLOT
- HERE @ + HERE !
-;
+.Word: ALLOT
+[caption='Defintion concept {counter:exec}: ']
+----
+: ALLOT HERE @ + HERE ! ;
+----
====
-.Usage example
====
+.Usage example
+****
HERE @ 16 ALLOT ( -- p ; Claiming 16 bytes )
+****
====
+See also <<p_colon,:>>, <<p_here,HERE>>, <<p_get,@>>, <<p_plus,+>>,
+<<p_put,!>> and <<p_semicolon,;>>.
+
+// logic.asm: WORD p_and, 'AND',fasm
+
anchor:p_and[]
-Word: AND
-----------
+=== Word: AND
+
+....
+Data stack: ( v1 v2 -- v3 )
+....
+
+"AND" is a function word that replaces a value pair with their bitwise
+conjunction; each bit is 1 if the corresponding bits of both operands
+are 1 and 0 if not.
-----
-logic.asm: WORD p_and, 'AND',fasm
-----
+//rrqforth.asm: WORD p_args,'ARGS',dostring
+
anchor:p_args[]
-Word: ARGS
-----------
+=== Word: ARGS
+
+....
+Data stack: ( -- argv** argc )
+....
-----
-rrqforth.asm: WORD p_args,'ARGS',dostring
-----
+"ARGS" is a value word that results in pusing the command line
+argument block. Here argc is the length of the block, and argv** is a
+pointer to a data block of that many asciiz pointers, which are the
+command line arguments given to RRQFORTH at start.
-Word: BASE
-----------
+// compile.asm: WORD p_base,'BASE',dovariable
anchor:p_base[]
-----
-compile.asm: WORD p_base,'BASE',dovariable
-----
+=== Word: BASE
+
+....
+Data stack: ( -- a )
+....
+
+"BASE" is a variable word for the numerical base used by input and
+output functions, <<p_number,NUMBER>> and <<p_dot>>, when
+translating numbers between cell value form and text form. The
+numerical base is set to 10 or 16 by <<p_decimal,DECIMAL>> and
+<<p_hex,HEX>> respectively, and those are the only two bases currently
+supported.
+
+See also <<p_digits,DIGITS>>, which holds the mapping table from
+digits to text.
+// rrqforth.asm: WORD p_branch,'BRANCH',fasm
+
anchor:p_branch[]
-Word: BRANCH
-----------
+=== Word: BRANCH
-----
-rrqforth.asm: WORD p_branch,'BRANCH',fasm
-----
+....
+Data stack: ( -- )
+....
+"BRANCH" is a function word that implements execution transfer by
+means of adding the subsequent branch offset to the point of
+execution.
+// stdio.asm: WORD p_clear_stream,'CLEAR-STREAM',fasm
+
anchor:p_clear_stream[]
-Word: CLEAR-STREAM
-------------------
+=== Word: CLEAR-STREAM
+
+....
+Data stack: ( stream -- )
+....
-----
-stdio.asm: WORD p_clear_stream,'CLEAR-STREAM',fasm
-----
+"CLEAR-STREAM" is a function word that discards whatever is currently
+remaining in the buffer for the stream, so that a subsequent read will
+pull in more data from its source.
+See also <<p_read_stream_char,READ-STREAM-CHAR>>.
-anchor:p_evaluate_stream[]
+// compile.asm: WORD p_colon[],':'
-Word: :
--------
+anchor:p_colon[]
+=== Word: :
+
+
+....
+Data stack: ( -- ) Input stream: word
+....
+
+":" (colon) is a function word that starts a new forth definition.
+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}: ']
----
-compile.asm: WORD p_colon[],':'
+: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;
----
+====
+
+See also <<p_doforth,doFORTH>>, <<p_read_word,READ-WORD>>,
+<<p_create,CREATE>>, <<p_tfa2cfa,TFA>CFA>>, <<p_put,!>>,
+<<p_left_bracket,]>> and <<p_semicolon,;>>.
-Word: ,
--------
+// compile.asm: WORD p_comma,',',fasm
+
anchor:p_comma[]
-----
-compile.asm: WORD p_comma,',',fasm
-----
+=== Word: ,
+
+
+....
Data stack: ( v -- )
+....
-"," is a function word that puts a cell on the heap.
+"," (comma) is a function word that puts a cell value on the
+<<p_here,HERE>> heap.
-.Execution semantics expressed in RRQFORTH
====
-: ,
- HERE @ 8 ALLOT ! ( v -- ; Claim 8 bytes and put value there )
-;
+.Word: ,
+[caption='Definition concept{counter:exec}: ']
+----
+: , HERE @ 8 ALLOT ! ; ( v -- ; Claim 8 bytes and put value there )
+----
====
-
+See also <<p_colon,:>>, <<p_Ccomma>>. <<p_here,HERE>>, <<p_get,@>>,
+<<p_allot,ALLOT>>, <<p_put,!>> and <<p_semicolon,;>>.
+// compile.asm: WORD p_create,'CREATE',fasm
+
anchor:p_create[]
-Word: CREATE
-------------
+=== Word: CREATE
-----
-compile.asm: WORD p_create,'CREATE',fasm
-----
+....
Data stack: ( char* n -- tfa )
+....
"CREATE" is a function word that allocates a "word header" with the
indicated [n:char*] print name, and returns the "TFA" (Token Field
function words initiated by ":" (aka "COLON") or changed to "dovalue"
for RRQFORTH constants created by "CONSTANT".
-See "<<p_execute,EXECUTE>>" about range of +doer+ assignments and
-their meanings.
-
-.Execution semantics expressed in RRQFORTH
====
+.Word: CREATE
+[caption='Definition concept {counter:exec}: ']
+----
HERE @ R> ( save tfa on RS )
R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
DUP 49 + R@ + , ( pCFA )
DUP , ( length )
HERE @ ROT ROT MEMCPY 0 C, ( pname + NUL )
R@ , ( pTFA )
- 0, ( OFF )
+ 0 , ( OFF )
doVARIABLE ( CFA, default semantics )
+----
====
-.Usage example
-====
-\ A possible definition of the word CONSTANT
-: CONSTANT
- READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! !
-;
-====
+.Usage example: a possible definition of CONSTANT
+****
+: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;
+****
+See also <<p_put,!>>, <<p_plus,+>>, <<p_comma>>, <<p_get,@>>,
+<<p_Ccomma>>, <<p_current_word,CURRENT-WORD>>, <<p_dup,DUP>>,
+<<p_here,HERE>>, <<p_herememcpy,HERE>>, <<p_Rget,R@>>, <<p_rot,ROT>>,
+and <<p_dovariable,doVARIABLE>>,
+as well as <<p_execute,EXECUTE>>
+about the range of "doer" assignments and their meanings.
+// wordlists.asm: WORD p_wordlist,'CURRENT-WORDLIST',dovariable
+
anchor:p_wordlist[]
-Word: CURRENT-WORDLIST
-----------------------
+=== Word: CURRENT-WORDLIST
+....
+Data stack: ( -- a )
+....
+"CURRENT-WORDLIST" is a variable word that points out the DFA of the
+current word list word for <<p_find,FIND>> to use finding words. The
+word list word content is as follows:
+====
+.word list word content
+[caption='Layout {counter:layout}: ']
----
-wordlists.asm: WORD p_wordlist,'CURRENT-WORDLIST',dovariable
+ 8 TFA of latest word in the word list
+ 8 DFA of the/a subsequent word list to search through
----
+====
+
+Note that word lists are chained by "extension" and in general it ends
+with the <<p_forth,FORTH>> word list. Initially the
+<<p_system,SYSTEM>> word list is the only other word list.
-Word: DECIMAL
--------------
+// compile.asm: WORD p_decimal,'DECIMAL',fasm
anchor:p_decimal[]
+
+=== Word: DECIMAL
+
+
+....
+Data stack: ( -- )
+....
+
+"DECIMAL" is a function word that sets <<p_base,BASE>> to 10.
+
+====
+.Word: DECIMAL
+[caption='Definition concept {counter:exec}: ']
----
-compile.asm: WORD p_decimal,'DECIMAL',fasm
+: DECIMAL 10 BASE ! ;
----
-
+====
+// stack.asm: WORD p_depth,'DEPTH',fasm
+
anchor:p_depth[]
-Word: DEPTH
-----------
+=== Word: DEPTH
-----
-stack.asm: WORD p_depth,'DEPTH',fasm
-----
+....
+Data stack: ( -- v )
+....
+"DEPTH" is a function word that pushes the count of data stack cells
+onto the data stack.
+// stdio.asm: WORD p_digits,'DIGITS',dovariable
+
anchor:p_digits[]
-Word: DIGITS
-------------
+=== Word: DIGITS
-----
-stdio.asm: WORD p_digits,'DIGITS',dovariable
-----
+....
+Data stack: ( -- a )
+....
+"DIGITS" is a variable word that holds the character array for mapping
+digit values to characters. It contains the 16 characters 0-9 and a-f.
+// math.asm: WORD p_divmod,'/MOD',fasm
+
anchor:p_divmod[]
-Word: /MOD
-----------
+=== Word: /MOD
+
+....
+Data stack: ( v1 v2 -- q r )
+....
+
+"/MOD" (div-mod) is a function word that replaces a pair of values
+with the results of signed integer division of the first, v1, divided
+by the scond, v2. To that end, the values are 64-bit signed integers.
+The result is the integer quotient, q, and the remainder, r, where q
+and r are the respectively largest and smallest integers to satisfy
+the formula:
+....
+ v1 = q * v2 + r
+....
-----
-math.asm: WORD p_divmod,'/MOD',fasm
-----
+// rrqforth.asm: WORD p_dodoes,'doDOES',dovariable
+
anchor:p_dodoes[]
-Word: doDOES
-----------
+=== Word: doDOES
-----
-rrqforth.asm: WORD p_dodoes,'doDOES',dovariable
-----
+....
+Data stack: ( -- a )
+....
+"doDOES" is a variable word whose value is the implementation of the
+<<p_does>> execution semantics. This is the same as
+<<p_doforth,doFORTH>> but it starts at an offset into the word
+concerned.
-WORD: DOES>
------------
+// compile.asm: WORD p_does,'DOES>',fasm,IMMEDIATE
+
anchor:p_does[]
-----
-compile.asm: WORD p_does,'DOES>',fasm,IMMEDIATE
-----
+=== WORD: DOES>
+
+....
Data stack: ( -- )
+....
"DOES>" is a function that in execution mode does nothing but in
compilation mode it changes the execution semantics assignments for
-the most recent word to use the "dodoes" sematics with adjustment
+the most recent word to use the +dodoes+ sematics with adjustment
offset to the current heap address. I.e., the word being defined will
have its execution start at whatever comes after "DOES>".
-.Execution semantics expressed in RRQFORTH
====
+.Word: 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
+ THEN
;
+----
====
+See also
+<<p_put,!>>,
+<<p_unequal,!=>>,
+<<p_plus,+>>,
+<<p_minus,->>,
+<<p_semicolon,;>>,
+<<p_get,@>>,
+<<p_current_wordlist,CURRENT-WORDLIST>>,
+<<p_here,HERE>>,
+<<p_if,IF>>,
+<<p_immediate,IMMEDIATE>>,
+<<p_over,OVER>>,
+<<p_state,STATE>>,
+<<p_swap,SWAP>>,
+<<p_tfa2cfa,TFA>CFA>>,
+<<p_then,THEN>>,
+<<p_dodoes,doDOES>>,
+as well as <<p_execute,EXECUTE>>
+about the range of "doer" assignments and their meanings.
+
-anchor:p_dofasm[]
+// rrqforth.asm: WORD p_dofasm,'doFASM',dovariable
-Word: doFASM
-------------
+anchor:p_dofasm[]
-----
-rrqforth.asm: WORD p_dofasm,'doFASM',dovariable
-----
+=== Word: doFASM
+....
+Data stack: ( -- a )
+....
+"doFASM" is a variable word whose value is the implementation of the
+execution semantics for assembly code content.
+// rrqforth.asm: WORD p_doforth,'doFORTH',dovariable ;
+
anchor:p_doforth[]
-Word: doFORTH
--------------
+=== Word: doFORTH
+
+....
+Data stack: ( -- a )
+....
-----
-rrqforth.asm: WORD p_doforth,'doFORTH',dovariable ;
-----
+"doFORTH" is a variable word whose value is the implementation of the
+RRQFORTH execution semantics.
+// rrqforth.asm: WORD p_dostring,'doSTRING',dovariable
+
anchor:p_dostring[]
-Word: doSTRING
---------------
+=== Word: doSTRING
+
+....
+Data stack: ( -- a )
+....
+
+"doFASM" is a variable word whose value is the implementation of the
+execution semantics for assembly code implemented words. In those
+cases the execution leads to the word content.
+
+The register context at entry to an assembly code implemented word is
+as follows:
----
-rrqforth.asm: WORD p_dostring,'doSTRING',dovariable
+ rax = cfa* of word to execute
+ rsi = cell* in the calling definition, after calling cell
+ rsp = data stack pointer
+ rbp = return stack pointer
----
+The assembly code must ensure that +rsi+ is preserved and that +rsp+
+and +rbp+ are used according to their roles.
-anchor:p_dot[]
+// stdio.asm: WORD p_dot,'.',fasm
-Word: .
--------
+anchor:p_dot[]
-----
-stdio.asm: WORD p_dot,'.',fasm
-----
+=== Word: .
+....
Data stack: ( v -- )
+....
-"." is a function word that prints the top stack value to stdout usonb
-<<p_base,BASE>> (either <<p_decimal,DECIMAL>> or <<p_hex,HEX>>).
-
+"." is a function word that prints the top stack value to stdout using
+the current <<p_base,BASE>> (either <<p_decimal,DECIMAL>> or
+<<p_hex,HEX>>).
+// stdio.asm: WORD p_double_quote,'"',fasm ;; " (fool emacs)
+
anchor:p_double_quote[]
-Word: "
--------
+=== Word: "
+....
+data stack: ( -- char n ) Input stream: ...."
+....
+
+""" (double quote) is a function word that copies the input stream
+text up to next double quote to <<p_pad,PAD>>, and returns the
+[n:char*] cell pair for that string.
+
-----
-stdio.asm: WORD p_double_quote,'"',fasm ;; " (fool emacs)
-----
+// rrqforth.asm: WORD p_dovalue,'doVALUE',dovariable
+
anchor:p_dovalue[]
-Word: doVALUE
--------------
+=== Word: doVALUE
+
+....
+Data stack: ( -- a )
+....
+
+"doVALUE" is a variable word whose value is the implementation of the
+execution semantics for cell values, which are variables with a single
+64-bit cell holding the value.
+
+The execution of this result in pushing the value:
+....
+Resulting data stack: ( -- v )
+....
-----
-rrqforth.asm: WORD p_dovalue,'doVALUE',dovariable
-----
+// rrqforth.asm: WORD p_dovariable,'doVARIABLE',dovariable
+
anchor:p_dovariable[]
-Word: doVARIABLE
-----------------
+=== Word: doVARIABLE
+
+....
+Data stack: ( -- a )
+....
+
+"doVARIABLE" is a variable word whose value is the implementation of
+the execution semantics for "variables", which basically are markers
+into the heap for some number block of memory.
+
+The execution of a variable results in pushing its content address:
+....
+Resulting data stack: ( -- a )
+....
-----
-rrqforth.asm: WORD p_dovariable,'doVARIABLE',dovariable
-----
+// stack.asm: WORD p_drop, 'DROP',fasm
+
anchor:p_drop[]
-Word: DROP
-----------
+=== Word: DROP
+
+....
+Data stack: ( v -- )
+....
-----
-stack.asm: WORD p_drop, 'DROP',fasm
-----
+"DROP" is a function word that discards the top stack cell.
+// stack.asm: WORD p_dup, 'DUP',fasm
+
anchor:p_dup[]
-Word: DUP
-----------
+=== Word: DUP
+
+....
+Data stack: ( v -- v v )
+....
-----
-stack.asm: WORD p_dup, 'DUP',fasm
-----
+"DUP" is a function word that duplicates the top stack cell.
+// stdio.asm: WORD p_emit,'EMIT',fasm
+
anchor:p_emit[]
-Word: EMIT
-----------
+=== Word: EMIT
+
+....
+Data stack: ( c -- )
+....
-----
-stdio.asm: WORD p_emit,'EMIT',fasm
-----
+"EMIT" is a function word that puts the given character code to
+standard output (file descriptor 1). The character is the least
+significant byte of the top cell.
+// logic.asm: WORD p_equal, '=',fasm
+
anchor:p_equal[]
-Word: =
--------
+=== Word: =
-----
-logic.asm: WORD p_equal, '=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....
+"=" is a function word that replaces a pair of values with -1 of the
+values are equal, and 0 otherwise.
-anchor:p_evaluate_stream[]
+// compile.asm: WORD p_evaluate_stream,'EVALUATE-STREAM'
-Word: EVALUATE-STREAM
----------------------
+anchor::p_evaluate_stream[]
+=== Word: EVALUATE-STREAM
+
+....
+Data stack: ( stream -- ??? 0/1 ) Input stream: ......
+....
+
+"EVALUATE-STREAM" is a function word that reads words separated by
+whitespace from the stream until it discovers an unknown word, or the
+stream is exhausted. Depending on <<p_state,STATE>>, the words are
+either executed or compiled, and all ther stack and heap effects are
+preserved. "EVALUATE-STREAM" returns with an additional 0 or 1 on the
+stack to respectively indicate that the last word was unkown, i.e. not
+found (<<p_find,FIND>>) in the current word list
+(<<p_current_wordlist,CURRENT-WORDLIST>>) and not a
+<<p_number,NUMBER>> of the current <<p_base,BASE>>.
+
+Note that numbers in the current <<p_base,BASE>> are treated as known
+words that are parsed into cell values. If interpreting, then the
+value is left on the stack. If compiling, then the value is added to
+the heap subsequent to first adding <<p_literal,LIT>>, which is done
+so as to make that value be push to the data stack upon a later
+execution.
+
+In the <<p_decimal,DECIMAL>> base, the number word may begin with a
+minus sign.
+
+The words are read and executed one by one, accounting for whether its
+a number word or not, whether it is an <<p_immediate,IMMEDIATE>> word
+or not, and whether the state at the time of execution indicates
+"compiling" of "interpreting". Immediate words are executed in both
+interpreting and compiling state, while other words have their CFA get
+added to the heap so as to gain their execution effect upon a later
+execution.
+
+Note that "EVALUATE-STREAM" keeps the stream (pointer) on the return
+stack while reading, parsing and executing.
+
+If "EVALUATE-STREAM" ends with 0, then <<p_this_word,THIS-WORD>> holds
+the [n:chars] reference of the offending word in the stream buffer.
+
+====
+.Word: EVALUATE-STREAM
+[caption='Definition concept {counter:exec}: ']
----
-compile.asm: WORD p_evaluate_stream,'EVALUATE-STREAM'
+( too complex to include here )
----
-
+====
+// rrqforth.asm: WORD p_execute,'EXECUTE',fasm
+
anchor:p_execute[]
-Word: EXECUTE
--------------
+=== Word: EXECUTE
+
+....
+Data stack: ( cfa -- )
+....
+
+"EXECUTE" is a function word that transfers the execution to the
+indicated "Code Field Address", which typically is the CFA of an
+RRQFORTH word with the CFA cell containing a jump address for the code
+that implements the execution semnatics of the word.
+
+The following execution semantics are predefined:
+
+ * assembler implemented words constitute their own execution
+ semantics;
+
+ * <<p_doforth>> implements the FORTH machine. This treats the word
+ content as a succession of cells that hold the cfa pointers for the
+ words that make of the definition. As is customary in FORTH
+ machines, the advance through that succession is provided by each
+ word code ending making an explicit jump to its successor. The
+ <<p_return_stack,RETURN-STACK>> serves as a call stack for tracking
+ the nesting of FORTH executions by saving the "addresses" of the
+ successor cells.
+
+ * <<p_dodoes>> implements the variation of starting the FORTH
+ execution somewhere within a definition rather than at the
+ beginning.
-----
-rrqforth.asm: WORD p_execute,'EXECUTE',fasm
-----
+ * <<p_dostring>>, <<p_dovalue>> and <<p_dovariable>> implement
+ different common ways of using word content other the as FORTH
+ definitions.
+
+// rrqforth.asm: WORD p_exit, 'EXIT',fasm
+
anchor:p_exit[]
-Word: EXIT
-----------
+=== Word: EXIT
+
+....
+Data stack: ( -- )
+....
-----
-rrqforth.asm: WORD p_exit, 'EXIT',fasm
-----
+"EXIT" is a function word that implements the ending of a FORTH
+definition and its threading to the subsequent step of the calling
+definition.
+// logic.asm: WORD p_false, 'FALSE',dovalue
+
anchor:p_false[]
-Word: FALSE
-----------
+=== Word: FALSE
-----
-logic.asm: WORD p_false, 'FALSE',fasm
-----
+....
+Data stack: ( -- 0 )
+....
+"FALSE" is a value word representing logical false.
+// wordlists.asm: WORD p_find,'FIND',fasm
+
anchor:p_find[]
-Word: FIND
-----------
+=== Word: FIND
+....
+Data stack: ( char* n -- [ char* n 0 ]/[ tfa ] )
+....
+
+"FIND" is a function word that searches the current word list search
+path for the given [n:char*] word, and returns the TFA of the matching
+word if any. Otherwise FIND preserves the initial data stack but adds
+0 to it.
-----
-wordlists.asm: WORD p_find,'FIND',fasm
-----
+The word is sought starting with the
+<<p_current_wordlist,CURRENT-WORDLIST>> word list, for the first
+occurence of a match. If not found, the search continues with the
+subsequent word list, and so on.
+When a word is found, then the data stack is changed by discarding the
+[n:char*] double cell string pointer and pushing (only) the TFA of the
+matching word instead.
+// wordlists.asm: WORD p_forth,'FORTH',dovariable
+
anchor:p_forth[]
-Word: FORTH
------------
+=== Word: FORTH
+....
+data stack: ( -- a )
+....
-----
-wordlists.asm: WORD p_forth,'FORTH',dovariable
-----
+"FORTH" is a variable word for the FORTH word list, which does not
+have any subsequent word list.
+// logic.asm: WORD p_greaterequal, '>=',fasm
+
anchor:p_greaterequal[]
-Word: >=
-----------
+=== Word: >=
-----
-logic.asm: WORD p_greaterequal, '>=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....
+">=" is a function word that replaces a pair of values with -1 if the
+first, v1, is greater than or equal to the second, v1, otherwise 0. To
+that end, the values are 64-bit signed integers.
+// logic.asm: WORD p_greaterthan, '>',fasm
+
anchor:p_greaterthan[]
-Word: >
--------
+=== Word: >
-----
-logic.asm: WORD p_greaterthan, '>',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....
+">" is a function word that replaces a pair of values with -1 if the
+first, v1, is greater than the second, v1, otherwise 0. To that end,
+the values are 64-bit signed integers.
--- /dev/null
+// stack.asm: WORD p_gtR, '>R',fasm
+
+anchor:p_gtR[]
+
+=== Word: >R
+
+....
+Data stack: ( v -- ) Return stack: ( -- v )
+....
+
+">R" is a function word that "moves" the top data stack value onto the
+return stack.
+// compile.asm: WORD p_here,'HERE',dovariable
+
anchor:p_here[]
-Word: HERE
-----------
-----
-compile.asm: WORD p_here,'HERE',dovariable
-----
+=== Word: HERE
+
+....
+Data stack: ( -- a )
+....
"HERE" is a variable word that keeps the lowest address of the free
-allocation space. It get updated by all words that allocate space.
+allocation space. It get updated by all words that allocate memory.
+
+.Usage example
+****
+1024 HEAP @ + HEAP ! ( allocate 1024 bytes on the heap )
+****
+See also <<p_allot,ALLOT>>.
-Word: HEX
-----------
+// compile.asm: WORD p_hex,'HEX',fasm
+
anchor:p_hex[]
+
+=== Word: HEX
+
+....
+Data stack: ( -- )
+....
+
+"HEX" is a function word that sets <<p_base,BASE>> to 16, which uses
+letters a-f as additional digits. (Uppercase letter are also accepted
+on input).
+
+====
+.Word: HEX
+[caption='Definition concept {counter:exec}: ']
----
-compile.asm: WORD p_hex,'HEX',fasm
+: HEX 16 BASE ! ;
----
-
+====
--- /dev/null
+// compile.asm: WORD p_immediate,'IMMEDIATE',fasm,IMMEDIATE
+
+anchor::p_immediate[]
+
+=== Word: IMMEDIATE
+
+....
+Data stack: ( -- )
+....
+
+"IMMEDIATE" is an immediate function word that sets the flags field of
+the most recent word to 1, thereby making that word an immediate word.
+
+====
+.Word: IMMEDIATE
+[caption='Definition concept {counter:exec}:']
+----
+: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;
+----
+====
+
+See also <<p_colon,:>>, <<p_current_wordlist,CURRENT-WORDLIST>>,
+<<p_get,@>>, <<p_plus,+>>, <<p_put,!>>, and <<p_semicolon;>>.
+
+
+// compile.asm: WORD p_left_bracket,'[',fasm,IMMEDIATE
+
anchor:p_left_bracket[]
-Word: [
--------
+=== Word: [
-----
-compile.asm: WORD p_left_bracket,'[',fasm,IMMEDIATE
-----
+....
+Data stack: ( -- )
+....
-"[" (left bracket) is function word that sets the stream evaluation
+"[" (left bracket) is a function word that sets the stream evaluation
mode to be intepreting. In this mode, words are executed immediately
after parsing, by invoking their "doer".
-.Execution semantics expressed in RRQFORTH
====
-: [ IMMEDIATE 1 STATE ! ;
+.Word: [
+[caption='Definition concept {counter:exec}: ']
+----
+: [ IMMEDIATE 0 STATE ! ;
+----
====
+// logic.asm: WORD p_lessequal, '<=',fasm
+
anchor:p_lessequal[]
-Word: <=
-----------
+=== Word: \<=
-----
-logic.asm: WORD p_lessequal, '<=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....
+"\<=" is a function word that replaces a pair of values with -1 if the
+first, v1, is less than or equal to the second, v1, otherwise 0. To
+that end, the values are 64-bit signed integers.
+// logic.asm: WORD p_lessthan, '<',fasm
+
anchor:p_lessthan[]
-Word: <
--------
+=== Word: <
-----
-logic.asm: WORD p_lessthan, '<',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....
+"<" is a function word that replaces a pair of values with -1 if the
+first, v1, is less than the second, v1, otherwise 0. To that end, the
+values are 64-bit signed integers.
-Word: LIT
----------
+// compile.asm: WORD p_literal,'LIT',fasm
anchor:p_literal[]
-----
-compile.asm: WORD p_literal,'LIT',fasm
-----
-Data stack: compiling ( v -- ) interpreting ( -- v )
+=== Word: LIT
-"LIT" is a function word for, in compiling mode, creating a literal
-value the gets pushed in interpreting mode. In compiling mode, it a
-lays out its own CFA pointer, then grabs the current stack value onto
-the heap. In interpreting mode it recreates the value onto the stack.
+....
+Data stack: ( -- v )
+....
-Note that the value is layed out as if a subsequent CFA poitnter in
-the containing definition, but the LIT execution will make the
-execution skip past that and instead contine with the CFA pointer
-folling the value.
+"LIT" is a function word that pushes the cell subsequent and moves
+excution past that. The literal value is thus layed out as if a
+subsequent CFA pointer in the containing definition, and the LIT
+execution will make the execution skip past that and instead contine
+with the CFA pointer following the value.
It's not a good idea to use "LIT" interactively.
-.Execution semantics expressed in RRQFORTH
====
-: LIT IMMEDIATE
- STATE @ IF p_literal , ELSE R> DUP 8 + >R @ THEN
-;
+.Word: LIT
+[caption='Definition concept {counter:exec}: ']
+----
+: LIT R> DUP 8 + >R @ ;
+----
====
-Word: S"
-----------
+//compile.asm: WORD p_literal_string,'S"',fasm ;; " (fool emacs)
anchor:p_literal_string[]
-----
-compile.asm: WORD p_literal_string,'S"',fasm ;; " (fool emacs)
-----
-"S"" is a function word for, in compaling mode, creating a string
-literal whose pname ( char* n ) gets pushed in interpreting mode.
+=== Word: S"
+
+....
+Data stack: ( -- chars* n )
+....
-Similar to "LIT", "S"" will insert the string into the containing
-definition, and use it from there.
+"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 <<p_lit,LIT>> but for a string literal.
+
+====
+.Word: LIT
+[caption='Definition concept {counter:exec}: ']
+----
+: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;
+----
+====
--- /dev/null
+// stdio.asm: WORD p_lparen,'(',fasm,IMMEDIATE
+
+anchor:p_tell[]
+
+=== Word: (
+....
+Data stack: ( -- )
+....
+
+"(" (left parenthesis) is a function word that scans and ignores words
+until the next right parenthesis, or the end of the stream. This is
+used for comments in RRQFORTH code.
+++ /dev/null
-anchor:p_ltR[]
-
-Word: >R
-----------
-
-----
-stack.asm: WORD p_ltR, '>R',fasm
-----
-
+// stdio.asm: WORD p_malloc,'MALLOC',fasm
+
anchor:p_malloc[]
-Word: MALLOC
-------------
+=== Word: MALLOC
+
+....
+Data stack: ( n -- a )
+....
+
+"MALLOC" is a word that allocates memory using mmap of at least n
+bytes and returns the lowest address of the allocated block.
+
+Note that this makes new page allocations for the process from the
+kernel, and the granularity is in pages, i.e. a multiple of 4 kb.
-----
-stdio.asm: WORD p_malloc,'MALLOC',fasm
-----
+The memory is allocated with READ and WRITE access but not EXEC
+access, and flagged as PRIVATE, ANONYMOUS and LOCKED. See the "man
+page" of mmap for details.
+See also <<p_stream,STREAM>>
+// math.asm: WORD p_minus, '-',fasm
+
anchor:p_minus[]
-Word: -
--------
+=== Word: -
-----
-math.asm: WORD p_minus, '-',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....
+"-" (minus) is a function word that replaces a pair of values with the
+result of reducing the first, v1, with the second, v2. To that end,
+the values are 64-bit signed integers.
+// math.asm: WORD p_mult, '*',fasm
+
anchor:p_mult[]
-Word: *
--------
+=== Word: *
-----
-math.asm: WORD p_mult, '*',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....
+"*" is a function word that replaces a pair of values with the result
+of multiplying them. To that end, the values are 64-bit signed
+integers, and clipping the result to the least signifcant 64 bits.
+// math.asm: WORD p_negate, 'NEGATE',fasm
+
anchor:p_negate[]
-Word: NEGATE
-----------
+=== Word: NEGATE
-----
-math.asm: WORD p_negate, 'NEGATE',fasm
-----
+....
+Data stack: ( v1 -- v2 )
+....
+"NEGATE" is a function word that replaces a value with its
+2's-complement negation. To that end, the values are 64-bit signed
+integers.
+// stack.asm: WORD p_nip, 'NIP',fasm
+
anchor:p_nip[]
-Word: NIP
-----------
+=== Word: NIP
+
+....
+Data stack: ( v1 v2 -- v2 )
+....
+"NIP" is a function word that discards the second of the top two cells
+on the data stack.
+
+====
+.Word: NIP
+[caption='Definition concept {counter:exec}: ']
----
-stack.asm: WORD p_nip, 'NIP',fasm
+: NIP SWAP DROP ;
----
-
+====
+// stdio.asm: WORD p_nl,'NL',dovalue
+
anchor:p_nl[]
-Word: NL
---------
+=== Word: NL
-----
-stdio.asm: WORD p_nl,'NL',dovalue
-----
+....
+Data stack: ( -- v )
+....
+"NL" is a value word pushing a newline character onto the data stack.
+// logic.asm: WORD p_not, 'NOT',fasm
+
anchor:p_not[]
-Word: NOT
-----------
+=== Word: NOT
+
+....
+Data stack: ( v1 -- v2 )
+....
-----
-logic.asm: WORD p_not, 'NOT',fasm
-----
+"NOT" is a function word that replaces a value with its bitwise
+complement; each bit is zero if non-zero, and non-zero if zero.
+Compare with <<p_0equal,0=>>.
-Word: NUMBER
-----------
+// compile.asm: WORD p_number,'NUMBER',fasm
anchor:p_number[]
+
+=== Word: NUMBER
+
+....
+Data stack: ( char n -- [ 0 ]/[ v 1 ] )
+....
+
+"NUMBER" is a function word that parses a text number using
+<<p_base,BASE>> as numerical base, then returns the result number and
+a 1 on top, or just a 0 if the word didn't parse.
+
+A number consists of, first an optional minus sign, if in
+<<p_decimal,DECIMAL>> base, then digits 0-9 and, if in <<p_hex,HEX>>
+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}: ']
----
-compile.asm: WORD p_number,'NUMBER',fasm
+( too complex to include here )
----
-
+====
+// logic.asm: WORD p_or, 'OR',fasm
+
anchor:p_or[]
-Word: OR
-----------
+=== Word: OR
+
+....
+Data stack: ( v1 v2 -- v3 )
+....
+
+"OR" is a function word that replaces a value pair with their bitwise
+disjunction; each bit is 1 if the corresponding bits of any operand
+is 1 and 0 if not.
-----
-logic.asm: WORD p_or, 'OR',fasm
-----
+// stack.asm: WORD p_over, 'OVER',fasm
+
anchor:p_over[]
-Word: OVER
-----------
+=== Word: OVER
+
+....
+Data stack: ( v1 v2 -- v1 v2 v1 )
+....
+
+"OVER" is a function word that duplicates the second top stack cell on
+the data stack.
-----
-stack.asm: WORD p_over, 'OVER',fasm
-----
+// stdio.asm: WORD p_pad,'PAD',dovariable
+
anchor:p_pad[]
-Word: PAD
----------
+=== Word: PAD
-----
-stdio.asm: WORD p_pad,'PAD',dovariable
-----
+....
+Data stack: ( -- a )
+....
+"PAD" is a variable word for a 1 kb data space that is used by
+<<p_double_quote>> (only), and otherwise free for temporary use.
+// stack.asm: WORD p_pick, 'PICK',fasm
+
anchor:p_pick[]
-Word: PICK
-----------
+=== Word: PICK
+
+....
+Data stack: ( vu...v1 v0 u -- vu...v1 v0 vu )
+....
+
+"PICK" is a function word that pushes the u:th data stack cell down
+from top onto the data stack. 0 indicates the top cell making it the
+same as <<p_dup,DUP>>, and 1 indicates the second top cell making it
+the same as <<p_over,OVER>>.
-----
-stack.asm: WORD p_pick, 'PICK',fasm
-----
+// math.asm: WORD p_plus, '+',fasm
anchor:p_plus[]
-Word: +
--------
+// note that asciidoc takes offence to a plain + in the title an
+// therefore we here rely an a convenince macro
+=== Word: {plus}
-----
-math.asm: WORD p_plus, '+',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....
+"+" (plus) is a function word that replaces a pair of values with the
+result of adding them. To that end, the values are 64-bit signed
+integers.
+// rrqforth.asm: WORD p_program_version,'PROGRAM_VERSION',dostring
+
anchor:p_program_version[]
-Word: PROGRAM_VERSION
----------------------
+=== Word: PROGRAM_VERSION
-----
-rrqforth.asm: WORD p_program_version,'PROGRAM_VERSION',dostring
-----
+....
+Data stack: ( -- char* length )
+....
+"PROGRAM_VERSION" is a string variable hilding the version string.
+// rrqforth.asm: WORD p_quit,'QUIT',fasm
+
anchor:p_quit[]
-Word: QUIT
-----------
+=== Word: QUIT
-----
-rrqforth.asm: WORD p_quit,'QUIT',fasm
-----
+....
+Data stack: ??
+....
+"QUIT" is a function word that implements the root execution loop of
+RRQFORTH. First it resets the stacks to their original settings, and
+thereafter it enters loop of reading words from <<p_stdin,STDIN>> and
+executing them.
+// stdio.asm: WORD p_read_stream_char,'READ-STREAM-CHAR',fasm
+
anchor:p_read_stream_char[]
-Word: READ-STREAM-CHAR
-----------------------
+=== Word: READ-STREAM-CHAR
+
+....
+Data stack: ( stream -- c )
+....
-----
-stdio.asm: WORD p_read_stream_char,'READ-STREAM-CHAR',fasm
-----
+"READ-STREAM-CHAR" is a function word that gets the next character
+from the given stream buffer, possibly refilling the buffer if it is
+backed by a file descriptor. The refill is done by a SYS_READ call
+when more characters are needed. The next character is pushed on the
+stack, unless the stream is exhausted in which case the -1 is pushed
+instead.
+See also <<p_stream,STREAM>>.
+// stdio.asm: WORD p_read_word,'READ-WORD',fasm
+
anchor:p_read_word[]
-Word: READ-WORD
----------------
+=== Word: READ-WORD
+....
+Data stack: ( stream -- char* n )
+....
-----
-stdio.asm: WORD p_read_word,'READ-WORD',fasm
-----
+"READ-WORD" is a function word that "reads" the next whitespace
+separated word from the given stream and returns the [n:char*] duoble
+cell pointer for it. The characters of the word are copied to
+<<p_pad,PAD>>, and there is a limit of 1024 characters.
+At the end of the stream READ-WORD returns 0 length.
+compile.asm: WORD p_right_bracket,']',fasm
+
anchor:p_right_bracket[]
-Word: ]
--------
+=== Word: ]
-----
-compile.asm: WORD p_right_bracket,']',fasm
-----
+....
+Data stack: ( -- )
+....
-"]" (right bracket) is function word that sets the stream evaluation
-mode to be compiling. In this mode, words are not executed immediately
-after parsing but rather having their CFA placed on the heap. However,
-words marked as IMMEDIATE (flags&1 != 0) are executed as if
-interpreting mode. Likewise for numbers.
+"]" (right bracket) is a function word that sets the stream evaluation
+mode to be compiling. In this mode words parsed into CFA pointers
+which are placed on the heap in the given order, unless the word is
+flagged as <<p_immediate,IMMEDIATE>> or a <<p_number,NUMBER>>. An
+immediate word is executed immediately, and a number is parsed and
+left on the stack.
+
+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.
-.Execution semantics expressed in RRQFORTH
====
-: [ IMMEDIATE 1 STATE ! ;
+.Word: ]
+[caption='Definition concept {counter:exec}: ']
+----
+: ] 1 STATE ! ;
+----
====
-
-
+// stack.asm: WORD p_roll, 'ROLL',fasm
+
anchor:p_roll[]
-Word: ROLL
-----------
+=== Word: ROLL
+
+....
+Data stack: ( vu...v1 v0 u -- ...v1 v0 vu )
+....
+
+"ROLL" is a function word that "moves" the u:th data stack cell down
+from top onto the data stack while discarding it. 0 indicates the top
+cell; 1 indicates the second top cell making it the same as
+<<p_swap,SWAP>>; 2 indicates the third top cell making it the same as
+<<p_rot,ROT>>.
+
+
-----
-stack.asm: WORD p_roll, 'ROLL',fasm
-----
+// stack.asm: WORD p_rot, 'ROT',fasm
+
anchor:p_rot[]
-Word: ROT
-----------
+=== Word: ROT
+
+....
+Data stack: ( v1 v2 v3 -- v2 v3 v1 )
+....
-----
-stack.asm: WORD p_rot, 'ROT',fasm
-----
+"ROT" is a function word that "rotates" the top three data stack cells
+such that the third becomes the first while the second becomes third
+and the first becomes the second.
+See also <<p_roll,ROLL>>.
-anchor:p_sp[]
+// stdio.asm: WORD p_sp,'SP',dovalue
-Word: SP
---------
+anchor:p_sp[]
-----
-stdio.asm: WORD p_sp,'SP',dovalue
-----
+=== Word: SP
+....
+Data stack: ( -- v )
+....
+"SP" is a value word pushing a space character onto the data stack.
-Word: STATE
-----------
+// compile.asm: WORD p_state,'STATE',dovariable
anchor:p_state[]
-----
-compile.asm: WORD p_state,'STATE',dovariable
-----
+
+=== Word: STATE
+
+....
+Data stack: ( -- a )
+....
"STATE" is a variable word marking whether the stream evaluator is in
compiling mode (1) or intepreting (0) mode.
+// rrqforth.asm: WORD p_stdin,'STDIN',dovalue
+
anchor:p_stdin[]
-Word: STDIN
------------
+=== Word: STDIN
-----
-rrqforth.asm: WORD p_stdin,'STDIN',dovalue
-----
+....
+Data stack: ( -- stream )
+....
+"STDIN" is a value word referring to the stream buffer for the
+standard input file descriptor.
+// stdio.asm: WORD p_stream,'STREAM',fasm
+
anchor:p_stream[]
-Word: STREAM
-------------
+=== Word: STREAM
+....
+Data stack: ( fd size -- addr ) or ( block -1 -- addr )
+....
+
+"STREAM" is a function word that sets up a buffer for an input file
+descriptor or for a memory block (of size+data).
+
+==== File descriptor backed STREAM
+
+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 ']
+----
+ 8 bytes = size of buffer (excluding the 32 byte header)
+ 8 bytes source file descriptor
+ 8 bytes current fill
+ 8 current read position
+----
+====
+
+==== Memory block backed STREAM
+
+A memory block stream is only the header (though allocated via
+<<p_malloc,MALLOC>> which reserves a full kernel page) with the
+following layout:
+====
+.memory block
+[caption='Stream layout {counter:layout}, for ']
----
-stdio.asm: WORD p_stream,'STREAM',fasm
+ 8 bytes = block address
+ 8 -1 (indicates memory block)
+ 8 size of block (taken from the block's first 8 bytes)
+ 8 current read position
----
+====
+// stdio.asm: WORD p_stream_nchars,'STREAM-NCHARS',fasm
+
anchor:p_stream_nchars[]
-Word: STREAM-NCHARS
--------------------
+=== Word: STREAM-NCHARS
+....
+Data stack: ( stream -- n )
+....
-----
-stdio.asm: WORD p_stream_nchars,'STREAM-NCHARS',fasm
-----
+"STREAM-NCHARS" is a function word that scans ahead in the stream
+buffer for the next non-whitespace character, and returns its position
+relative to the end of the buffer. This is done without changing the
+stream (or filling it by reading the backing file).
+// wordlists.asm: WORD p_strncmp,'STRNCMP',fasm
+
anchor:p_strncmp[]
-Word: STRNCMP
--------------
+=== Word: STRNCMP
+....
+Data stack: ( s1 s2 n -- v )
+....
-----
-wordlists.asm: WORD p_strncmp,'STRNCMP',fasm
-----
+"STRNCMP" is a function words that compares up to n characters of
+character sequences s1 and s2, and returns the difference of the first
+differing characters, as in +s2[i] - s1[i]+, or 0 if all n characters
+are the same.
+I.e., the value v is less than 0 if string [n:s1] is alpha-numerically
+less than [n:s2],
+v is greater than 0 if [n:s1] is greater than [n:s2],
+and v is 0 if [n:s1] and [n:s2] are equal.
+// stack.asm: WORD p_swap, 'SWAP',fasm
+
anchor:p_swap[]
-Word: SWAP
-----------
+=== Word: SWAP
-----
-stack.asm: WORD p_swap, 'SWAP',fasm
-----
+....
+Data stack: ( v1 v2 -- v2 v1 )
+....
+"SWAP" is a function word the swaps the top two data stack cells.
+// rrqforth.asm: WORD p_system,'SYSTEM',dovariable
+
anchor:p_system[]
-Word: SYSTEM
-----------
+=== Word: SYSTEM
+
+....
+Data value: ( -- a )
+....
-----
-rrqforth.asm: WORD p_system,'SYSTEM',dovariable
-----
+"SYSTEM" is a variable that holds the word list data for the system
+calls. This is set up as separate word list from <<p_forth,FORTH>>
+merely as a matter of segregation.
-anchor:p_tell[]
+// stdio.asm: WORD p_tell,'TELL',fasm
-Word: TELL
-----------
+anchor:p_tell[]
-----
-stdio.asm: WORD p_tell,'TELL',fasm
-----
+=== Word: TELL
+....
+Data stack: ( char* n -- )
+....
+"TELL" is a function word that prints a string to stdout (file
+descriptor 1).
+// rrqforth.asm: WORD p_terminate0, 'TERMINATE0',fasm
+
anchor:p_terminate0[]
-Word: TERMINATE0
-----------------
+=== Word: TERMINATE0
-----
-rrqforth.asm: WORD p_terminate0, 'TERMINATE0',fasm
-----
+....
+Data stack: ( -- )
+....
+"TERMINATE0" is a function word that terminates the program with exit
+code 0.
+// compile.asm: WORD p_this_word,'THIS-WORD',dovariable
+
anchor:p_this_word[]
-Word: THIS-WORD
----------------
+=== Word: THIS-WORD
-----
-compile.asm: WORD p_this_word,'THIS-WORD',dovariable
-----
+....
+Data stack: ( -- a )
+....
"THIS-WORD" is a variable word used in
<<p_evaluate_stream:EVALUATE-STREAM>> as cache for the [n:char*]
+// logic.asm: WORD p_true, 'TRUE',fasm
+
anchor:p_true[]
-Word: TRUE
-----------
+=== Word: TRUE
-----
-logic.asm: WORD p_true, 'TRUE',fasm
-----
+....
+Data stack: ( -- -1 )
+....
+"TRUE" is a value word representing logical true.
+// stack.asm: WORD p_tuck, 'TUCK',fasm
+
anchor:p_tuck[]
-Word: TUCK
-----------
+=== Word: TUCK
+
+....
+Data stack ( v1 v2 -- v2 v1 v2 )
+....
+"TUCK" is a function word that "inserts" the top cell below the second
+cell on the data stack.
+
+====
+.Word: TUCK
+[caption='Definition concept {counter:exec}: ']
----
-stack.asm: WORD p_tuck, 'TUCK',fasm
+: TUCK SWAP OVER ;
----
-
+====
+// logic.asm: WORD p_unequal, '!=',fasm
+
anchor:p_unequal[]
-Word: !=
-----------
+=== Word: !=
-----
-logic.asm: WORD p_unequal, '!=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....
+"!=" is a function word that replaces a pair of values with -1 of the
+values are unequal, and 0 otherwise.
+// logic.asm: WORD p_within, 'WITHIN',fasm
+
anchor:p_within[]
-Word: WITHIN
-----------
+=== Word: WITHIN
+
+....
+Data stack: ( v lo hi -- 0/-1
+....
+"WITHIN" is a function word that replaces a triple of values with -1
+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}: ']
----
-logic.asm: WORD p_within, 'WITHIN',fasm
+: WITHIN 2 PICK > ROT ROT <= AND ;
----
-
+====
-anchor:p_words[]
+// wordlists.asm: WORD p_words,'WORDS',fasm
-Word: WORDS
------------
+anchor:p_words[]
-----
-wordlists.asm: WORD p_words,'WORDS',fasm
-----
+=== Word: WORDS
+....
+Data stack: ( wl -- )
+....
+"WORDS" is a function word that prints all words of teh given word
+list to stdout (file descriptor 1).
+// logic.asm: WORD p_xor, 'XOR',fasm
+
anchor:p_xor[]
-Word: XOR
-----------
+=== Word: XOR
-----
-logic.asm: WORD p_xor, 'XOR',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....
+"XOR" is a function word that replaces a value pair with their bitwise
+exclusion; each bit is 1 if the corresponding bits of the two operands
+differ and 0 if not.
+// rrqforth.asm: WORD return_stack,'RETURN-STACK',dovariable
+
anchor:return_stack[]
-Word: RETURN-STACK
-------------------
+=== Word: RETURN-STACK
+
+....
+Data stack: ( -- a )
+....
-----
-rrqforth.asm: WORD return_stack,'RETURN-STACK',dovariable
-----
+"RETURN-STACK" is a variable word harbouring the return stack.
-RRQFORTH Reference Documentation
-================================
-// :toc:
+= RRQFORTH Reference Documentation
+:author: Ralph Ronnquist <ralph.ronnquist@gmail.com>
+:plus: +
+
+== Compilation words
// include::compile.adoc[]
include::adoc/p_allot.adoc[]
include::adoc/p_base.adoc[]
include::adoc/p_evaluate_stream.adoc[]
include::adoc/p_here.adoc[]
include::adoc/p_hex.adoc[]
+include::adoc/p_immediate.adoc[]
include::adoc/p_left_bracket.adoc[]
include::adoc/p_literal.adoc[]
include::adoc/p_literal_string.adoc[]
include::adoc/p_state.adoc[]
include::adoc/p_this_word.adoc[]
+== Logic operation words
//include::logic.adoc[]
include::adoc/p_0equal.adoc[]
include::adoc/p_0less.adoc[]
include::adoc/p_within.adoc[]
include::adoc/p_xor.adoc[]
+== Math operation words
// include::math.adoc[]
include::adoc/p_abs.adoc[]
include::adoc/p_divmod.adoc[]
include::adoc/p_negate.adoc[]
include::adoc/p_plus.adoc[]
+== RRQFORTH main words
//include::rrqforth.adoc[]
include::adoc/data_stack.adoc[]
include::adoc/inline_code.adoc[]
include::adoc/p_dovariable.adoc[]
include::adoc/p_execute.adoc[]
include::adoc/p_exit.adoc[]
+include::adoc/p_lparen.adoc[]
include::adoc/p_program_version.adoc[]
include::adoc/p_quit.adoc[]
include::adoc/p_stdin.adoc[]
include::adoc/p_terminate0.adoc[]
include::adoc/return_stack.adoc[]
+== Stack operation words
//include::stack.adoc[]
include::adoc/p_2drop.adoc[]
include::adoc/p_2dup.adoc[]
include::adoc/p_depth.adoc[]
include::adoc/p_drop.adoc[]
include::adoc/p_dup.adoc[]
-include::adoc/p_ltR.adoc[]
+include::adoc/p_gtR.adoc[]
include::adoc/p_nip.adoc[]
include::adoc/p_over.adoc[]
include::adoc/p_pick.adoc[]
include::adoc/p_swap.adoc[]
include::adoc/p_tuck.adoc[]
+== Input/output words
//include::stdio.adoc[]
include::adoc/p_clear_stream.adoc[]
include::adoc/p_digits.adoc[]
include::adoc/p_stream_nchars.adoc[]
include::adoc/p_tell.adoc[]
+== Wordlist words
//include::wordlists.adoc[]
include::adoc/p_current_wordlist.adoc[]
include::adoc/p_find.adoc[]
include::adoc/p_strncmp.adoc[]
include::adoc/p_words.adoc[]
+== System calls
//include::syscalls.adoc[]
+
+RRQFORTH includes function wrapping for all "Linux syscalls", which
+generally are described in their "man pages. This wrapping takes the
+arguments fro the data stack in reverse order, i.e. the first argument
+is deepest.
+
+Use +SYSTEM WORDS+ to get a list of all (321) available syscalls.
+
+
+include::wordindex.adoc[]
--- /dev/null
+
+== Index of word links
+
+<<data_stack>>
+<<inline_code>>
+<<return_stack>>
+
+<<p_0branch>>
+<<p_0equal>>
+<<p_0less>>
+
+<<p_2drop>>
+<<p_2dup>>
+<<p_2over>>
+<<p_2swap>>
+
+<<p_abs>>
+<<p_allot>>
+<<p_and>>
+<<p_args>>
+
+<<p_base>>
+<<p_branch>>
+
+<<p_Ccomma>>
+<<p_clear_stream>>
+<<p_colon>>
+<<p_comma>>
+<<p_create>>
+<<p_current_wordlist>>
+
+<<p_decimal>>
+<<p_depth>>
+<<p_digits>>
+<<p_divmod>>
+<<p_dodoes>>
+<<p_does>>
+<<p_dofasm>>
+<<p_doforth>>
+<<p_dostring>>
+<<p_dot>>
+<<p_double_quote>>
+<<p_dovalue>>
+<<p_dovariable>>
+<<p_drop>>
+<<p_dup>>
+
+<<p_emit>>
+<<p_equal>>
+<<p_evaluate_stream>>
+<<p_execute>>
+<<p_exit>>
+
+<<p_false>>
+<<p_find>>
+<<p_forth>>
+
+<<p_greaterequal>>
+<<p_greaterthan>>
+<<p_gtR>>
+
+<<p_here>>
+<<p_hex>>
+
+<<p_immediate>>
+
+<<p_left_bracket>>
+<<p_lessequal>>
+<<p_lessthan>>
+<<p_literal>>
+<<p_literal_string>>
+
+<<p_malloc>>
+<<p_minus>>
+<<p_mult>>
+
+<<p_negate>>
+<<p_nip>>
+<<p_nl>>
+<<p_not>>
+<<p_number>>
+
+<<p_or>>
+<<p_over>>
+<<p_pad>>
+
+<<p_pick>>
+<<p_plus>>
+<<p_program_version>>
+
+<<p_quit>>
+
+<<p_read_stream_char>>
+<<p_read_word>>
+<<p_Rget>>
+<<p_Rgt>>
+<<p_right_bracket>>
+<<p_roll>>
+<<p_rot>>
+
+<<p_sp>>
+<<p_state>>
+<<p_stdin>>
+<<p_stream>>
+<<p_stream_nchars>>
+<<p_strncmp>>
+<<p_swap>>
+<<p_system>>
+
+<<p_tell>>
+<<p_terminate0>>
+<<p_this_word>>
+<<p_true>>
+<<p_tuck>>
+
+<<p_unequal>>
+
+<<p_within>>
+<<p_words>>
+
+<<p_xor>>
projects / rrq / rrqforth.git / commitdiff