From 656f37efbd89db1b1088281047a9633cf74e92ec Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Wed, 26 May 2021 13:58:58 +1000 Subject: [PATCH] major touch-up into presentable form --- adoc/data_stack.adoc | 12 ++-- adoc/inline_code.adoc | 23 +++++-- adoc/p_0branch.adoc | 17 +++-- adoc/p_0equal.adoc | 17 +++-- adoc/p_0less.adoc | 20 +++++- adoc/p_2drop.adoc | 13 ++-- adoc/p_2dup.adoc | 19 ++++-- adoc/p_2over.adoc | 19 +++++- adoc/p_2swap.adoc | 20 ++++-- adoc/p_Ccomma.adoc | 29 +++++---- adoc/p_Rget.adoc | 14 ++-- adoc/p_Rgt.adoc | 13 ++-- adoc/p_abs.adoc | 13 ++-- adoc/p_allot.adoc | 31 +++++---- adoc/p_and.adoc | 16 +++-- adoc/p_args.adoc | 16 +++-- adoc/p_base.adoc | 21 ++++-- adoc/p_branch.adoc | 14 ++-- adoc/p_clear_stream.adoc | 16 +++-- adoc/p_colon.adoc | 26 ++++++-- adoc/p_comma.adoc | 27 ++++---- adoc/p_create.adoc | 37 ++++++----- adoc/p_current_wordlist.adoc | 22 ++++++- adoc/p_decimal.adoc | 20 ++++-- adoc/p_depth.adoc | 13 ++-- adoc/p_digits.adoc | 13 ++-- adoc/p_divmod.adoc | 22 +++++-- adoc/p_dodoes.adoc | 15 +++-- adoc/p_does.adoc | 39 ++++++++--- adoc/p_dofasm.adoc | 14 ++-- adoc/p_doforth.adoc | 14 ++-- adoc/p_dostring.adoc | 23 ++++++- adoc/p_dot.adoc | 17 +++-- adoc/p_double_quote.adoc | 16 +++-- adoc/p_dovalue.adoc | 21 ++++-- adoc/p_dovariable.adoc | 21 ++++-- adoc/p_drop.adoc | 13 ++-- adoc/p_dup.adoc | 13 ++-- adoc/p_emit.adoc | 15 +++-- adoc/p_equal.adoc | 13 ++-- adoc/p_evaluate_stream.adoc | 52 +++++++++++++-- adoc/p_execute.adoc | 39 +++++++++-- adoc/p_exit.adoc | 15 +++-- adoc/p_false.adoc | 12 ++-- adoc/p_find.adoc | 23 +++++-- adoc/p_forth.adoc | 13 ++-- adoc/p_greaterequal.adoc | 14 ++-- adoc/p_greaterthan.adoc | 14 ++-- adoc/p_gtR.adoc | 12 ++++ adoc/p_here.adoc | 20 ++++-- adoc/p_hex.adoc | 22 +++++-- adoc/p_immediate.adoc | 25 ++++++++ adoc/p_left_bracket.adoc | 20 +++--- adoc/p_lessequal.adoc | 14 ++-- adoc/p_lessthan.adoc | 14 ++-- adoc/p_literal.adoc | 33 +++++----- adoc/p_literal_string.adoc | 26 +++++--- adoc/p_lparen.adoc | 12 ++++ adoc/p_ltR.adoc | 9 --- adoc/p_malloc.adoc | 22 +++++-- adoc/p_minus.adoc | 14 ++-- adoc/p_mult.adoc | 14 ++-- adoc/p_negate.adoc | 14 ++-- adoc/p_nip.adoc | 19 ++++-- adoc/p_nl.adoc | 12 ++-- adoc/p_not.adoc | 15 +++-- adoc/p_number.adoc | 27 ++++++-- adoc/p_or.adoc | 16 +++-- adoc/p_over.adoc | 15 +++-- adoc/p_pad.adoc | 13 ++-- adoc/p_pick.adoc | 17 +++-- adoc/p_plus.adoc | 15 +++-- adoc/p_program_version.adoc | 12 ++-- adoc/p_quit.adoc | 15 +++-- adoc/p_read_stream_char.adoc | 19 ++++-- adoc/p_read_word.adoc | 16 +++-- adoc/p_right_bracket.adoc | 34 ++++++---- adoc/p_roll.adoc | 20 ++++-- adoc/p_rot.adoc | 16 +++-- adoc/p_sp.adoc | 13 ++-- adoc/p_state.adoc | 12 ++-- adoc/p_stdin.adoc | 13 ++-- adoc/p_stream.adoc | 42 +++++++++++- adoc/p_stream_nchars.adoc | 15 +++-- adoc/p_strncmp.adoc | 19 ++++-- adoc/p_swap.adoc | 12 ++-- adoc/p_system.adoc | 15 +++-- adoc/p_tell.adoc | 14 ++-- adoc/p_terminate0.adoc | 13 ++-- adoc/p_this_word.adoc | 11 ++-- adoc/p_true.adoc | 12 ++-- adoc/p_tuck.adoc | 19 ++++-- adoc/p_unequal.adoc | 13 ++-- adoc/p_within.adoc | 20 ++++-- adoc/p_words.adoc | 14 ++-- adoc/p_xor.adoc | 14 ++-- adoc/return_stack.adoc | 13 ++-- reference.adoc | 29 +++++++-- wordindex.adoc | 121 +++++++++++++++++++++++++++++++++++ 99 files changed, 1391 insertions(+), 534 deletions(-) create mode 100644 adoc/p_gtR.adoc create mode 100644 adoc/p_immediate.adoc create mode 100644 adoc/p_lparen.adoc delete mode 100644 adoc/p_ltR.adoc create mode 100644 wordindex.adoc diff --git a/adoc/data_stack.adoc b/adoc/data_stack.adoc index 0055cfe..3d536a9 100644 --- a/adoc/data_stack.adoc +++ b/adoc/data_stack.adoc @@ -1,9 +1,11 @@ +// 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. diff --git a/adoc/inline_code.adoc b/adoc/inline_code.adoc index 91bb246..b1a9c46 100644 --- a/adoc/inline_code.adoc +++ b/adoc/inline_code.adoc @@ -1,11 +1,22 @@ +// 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: +---- +==== diff --git a/adoc/p_0branch.adoc b/adoc/p_0branch.adoc index 16c69c0..4f396c3 100644 --- a/adoc/p_0branch.adoc +++ b/adoc/p_0branch.adoc @@ -1,9 +1,16 @@ +// 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. diff --git a/adoc/p_0equal.adoc b/adoc/p_0equal.adoc index 63980d4..827c0f1 100644 --- a/adoc/p_0equal.adoc +++ b/adoc/p_0equal.adoc @@ -1,9 +1,16 @@ +// 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 <>. diff --git a/adoc/p_0less.adoc b/adoc/p_0less.adoc index 6ce109c..b068b63 100644 --- a/adoc/p_0less.adoc +++ b/adoc/p_0less.adoc @@ -1,9 +1,23 @@ +// 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 <> and +<>. diff --git a/adoc/p_2drop.adoc b/adoc/p_2drop.adoc index 4d5942f..92d1b6f 100644 --- a/adoc/p_2drop.adoc +++ b/adoc/p_2drop.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_2dup.adoc b/adoc/p_2dup.adoc index 17c0005..0b39b08 100644 --- a/adoc/p_2dup.adoc +++ b/adoc/p_2dup.adoc @@ -1,9 +1,20 @@ +// 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 ; ---- - +==== diff --git a/adoc/p_2over.adoc b/adoc/p_2over.adoc index 772d238..058bfdd 100644 --- a/adoc/p_2over.adoc +++ b/adoc/p_2over.adoc @@ -1,9 +1,22 @@ +// 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 <> 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 ; ---- +==== diff --git a/adoc/p_2swap.adoc b/adoc/p_2swap.adoc index 7b0694c..6c123cf 100644 --- a/adoc/p_2swap.adoc +++ b/adoc/p_2swap.adoc @@ -1,9 +1,21 @@ +// 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 <> 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 ; ---- - +==== diff --git a/adoc/p_Ccomma.adoc b/adoc/p_Ccomma.adoc index 0cb1900..a0b07cd 100644 --- a/adoc/p_Ccomma.adoc +++ b/adoc/p_Ccomma.adoc @@ -1,20 +1,25 @@ -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 +<> 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 <>, <>. <>, <>, +<>, <> and <>. diff --git a/adoc/p_Rget.adoc b/adoc/p_Rget.adoc index 8eb5f6d..236e2ee 100644 --- a/adoc/p_Rget.adoc +++ b/adoc/p_Rget.adoc @@ -1,8 +1,12 @@ +// 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. diff --git a/adoc/p_Rgt.adoc b/adoc/p_Rgt.adoc index 65fef54..c3dcaee 100644 --- a/adoc/p_Rgt.adoc +++ b/adoc/p_Rgt.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_abs.adoc b/adoc/p_abs.adoc index 51726f2..8a9ed22 100644 --- a/adoc/p_abs.adoc +++ b/adoc/p_abs.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_allot.adoc b/adoc/p_allot.adoc index cf6e3b9..7844010 100644 --- a/adoc/p_allot.adoc +++ b/adoc/p_allot.adoc @@ -1,26 +1,31 @@ +// 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 <> +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 <>, <>, <>, <>, +<> and <>. + diff --git a/adoc/p_and.adoc b/adoc/p_and.adoc index ec2f20e..11a3d1c 100644 --- a/adoc/p_and.adoc +++ b/adoc/p_and.adoc @@ -1,9 +1,15 @@ +// 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 ----- diff --git a/adoc/p_args.adoc b/adoc/p_args.adoc index 7575bd1..a003e7a 100644 --- a/adoc/p_args.adoc +++ b/adoc/p_args.adoc @@ -1,9 +1,15 @@ +//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. diff --git a/adoc/p_base.adoc b/adoc/p_base.adoc index 43c2e9e..a8748b7 100644 --- a/adoc/p_base.adoc +++ b/adoc/p_base.adoc @@ -1,8 +1,19 @@ -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, <> and <>, when +translating numbers between cell value form and text form. The +numerical base is set to 10 or 16 by <> and +<> respectively, and those are the only two bases currently +supported. + +See also <>, which holds the mapping table from +digits to text. diff --git a/adoc/p_branch.adoc b/adoc/p_branch.adoc index b555fd6..9e4d0d2 100644 --- a/adoc/p_branch.adoc +++ b/adoc/p_branch.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_clear_stream.adoc b/adoc/p_clear_stream.adoc index 7672daf..5ecd9fa 100644 --- a/adoc/p_clear_stream.adoc +++ b/adoc/p_clear_stream.adoc @@ -1,9 +1,15 @@ +// 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 <>. diff --git a/adoc/p_colon.adoc b/adoc/p_colon.adoc index 2fb446b..3a5acec 100644 --- a/adoc/p_colon.adoc +++ b/adoc/p_colon.adoc @@ -1,8 +1,26 @@ -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 <>, <>, +<>, <CFA>>, <>, +<> and <>. diff --git a/adoc/p_comma.adoc b/adoc/p_comma.adoc index cca9e0b..ae00035 100644 --- a/adoc/p_comma.adoc +++ b/adoc/p_comma.adoc @@ -1,19 +1,24 @@ -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 +<> 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 <>, <>. <>, <>, +<>, <> and <>. diff --git a/adoc/p_create.adoc b/adoc/p_create.adoc index dc6926a..cf8914e 100644 --- a/adoc/p_create.adoc +++ b/adoc/p_create.adoc @@ -1,13 +1,13 @@ +// 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 @@ -41,11 +41,10 @@ its DFA when executed. This is changed to "doforth" for RRQFORTH function words initiated by ":" (aka "COLON") or changed to "dovalue" for RRQFORTH constants created by "CONSTANT". -See "<>" 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 ) @@ -53,15 +52,19 @@ HERE @ R> ( save tfa on RS ) 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 <>, <>, <>, <>, +<>, <>, <>, +<>, <>, <>, <>, +and <>, +as well as <> +about the range of "doer" assignments and their meanings. diff --git a/adoc/p_current_wordlist.adoc b/adoc/p_current_wordlist.adoc index 340cabd..6f086a6 100644 --- a/adoc/p_current_wordlist.adoc +++ b/adoc/p_current_wordlist.adoc @@ -1,9 +1,25 @@ +// 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 <> 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 <> word list. Initially the +<> word list is the only other word list. diff --git a/adoc/p_decimal.adoc b/adoc/p_decimal.adoc index df737ee..b06e5f2 100644 --- a/adoc/p_decimal.adoc +++ b/adoc/p_decimal.adoc @@ -1,8 +1,20 @@ -Word: DECIMAL -------------- +// compile.asm: WORD p_decimal,'DECIMAL',fasm anchor:p_decimal[] + +=== Word: DECIMAL + + +.... +Data stack: ( -- ) +.... + +"DECIMAL" is a function word that sets <> to 10. + +==== +.Word: DECIMAL +[caption='Definition concept {counter:exec}: '] ---- -compile.asm: WORD p_decimal,'DECIMAL',fasm +: DECIMAL 10 BASE ! ; ---- - +==== diff --git a/adoc/p_depth.adoc b/adoc/p_depth.adoc index 8a92b13..6b6c0cd 100644 --- a/adoc/p_depth.adoc +++ b/adoc/p_depth.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_digits.adoc b/adoc/p_digits.adoc index 3bbfdf4..4c3d8a1 100644 --- a/adoc/p_digits.adoc +++ b/adoc/p_digits.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_divmod.adoc b/adoc/p_divmod.adoc index bae6cbb..5e8f2a9 100644 --- a/adoc/p_divmod.adoc +++ b/adoc/p_divmod.adoc @@ -1,9 +1,21 @@ +// 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 ----- diff --git a/adoc/p_dodoes.adoc b/adoc/p_dodoes.adoc index 19319f5..9a1c320 100644 --- a/adoc/p_dodoes.adoc +++ b/adoc/p_dodoes.adoc @@ -1,9 +1,14 @@ +// 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 +<> execution semantics. This is the same as +<> but it starts at an offset into the word +concerned. diff --git a/adoc/p_does.adoc b/adoc/p_does.adoc index 6517157..a9ac349 100644 --- a/adoc/p_does.adoc +++ b/adoc/p_does.adoc @@ -1,26 +1,49 @@ -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 +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<CFA>>, +<>, +<>, +as well as <> +about the range of "doer" assignments and their meanings. + diff --git a/adoc/p_dofasm.adoc b/adoc/p_dofasm.adoc index 920a16c..31ec84e 100644 --- a/adoc/p_dofasm.adoc +++ b/adoc/p_dofasm.adoc @@ -1,9 +1,11 @@ -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. diff --git a/adoc/p_doforth.adoc b/adoc/p_doforth.adoc index 8fa70ef..0fd4d2f 100644 --- a/adoc/p_doforth.adoc +++ b/adoc/p_doforth.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_dostring.adoc b/adoc/p_dostring.adoc index 54725c1..3645b06 100644 --- a/adoc/p_dostring.adoc +++ b/adoc/p_dostring.adoc @@ -1,9 +1,26 @@ +// 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. diff --git a/adoc/p_dot.adoc b/adoc/p_dot.adoc index 621bee2..1a884ed 100644 --- a/adoc/p_dot.adoc +++ b/adoc/p_dot.adoc @@ -1,14 +1,13 @@ -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 -<> (either <> or <>). - +"." is a function word that prints the top stack value to stdout using +the current <> (either <> or +<>). diff --git a/adoc/p_double_quote.adoc b/adoc/p_double_quote.adoc index 1c8e09f..8568180 100644 --- a/adoc/p_double_quote.adoc +++ b/adoc/p_double_quote.adoc @@ -1,9 +1,15 @@ +// 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 <>, and returns the +[n:char*] cell pair for that string. + ----- -stdio.asm: WORD p_double_quote,'"',fasm ;; " (fool emacs) ----- diff --git a/adoc/p_dovalue.adoc b/adoc/p_dovalue.adoc index 1670131..696e9e5 100644 --- a/adoc/p_dovalue.adoc +++ b/adoc/p_dovalue.adoc @@ -1,9 +1,20 @@ +// 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 ----- diff --git a/adoc/p_dovariable.adoc b/adoc/p_dovariable.adoc index dd27a6e..38c2c5e 100644 --- a/adoc/p_dovariable.adoc +++ b/adoc/p_dovariable.adoc @@ -1,9 +1,20 @@ +// 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 ----- diff --git a/adoc/p_drop.adoc b/adoc/p_drop.adoc index 123afdb..fe0ec11 100644 --- a/adoc/p_drop.adoc +++ b/adoc/p_drop.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_dup.adoc b/adoc/p_dup.adoc index 8f2a8c4..f8ac7f1 100644 --- a/adoc/p_dup.adoc +++ b/adoc/p_dup.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_emit.adoc b/adoc/p_emit.adoc index 26651f2..b20ecfc 100644 --- a/adoc/p_emit.adoc +++ b/adoc/p_emit.adoc @@ -1,9 +1,14 @@ +// 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. diff --git a/adoc/p_equal.adoc b/adoc/p_equal.adoc index d15a8e7..2082981 100644 --- a/adoc/p_equal.adoc +++ b/adoc/p_equal.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_evaluate_stream.adoc b/adoc/p_evaluate_stream.adoc index aae56c4..2a051af 100644 --- a/adoc/p_evaluate_stream.adoc +++ b/adoc/p_evaluate_stream.adoc @@ -1,11 +1,53 @@ -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 <>, 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 (<>) in the current word list +(<>) and not a +<> of the current <>. + +Note that numbers in the current <> 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 <>, which is done +so as to make that value be push to the data stack upon a later +execution. + +In the <> 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 <> 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 <> 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 ) ---- - +==== diff --git a/adoc/p_execute.adoc b/adoc/p_execute.adoc index 8197f0c..7b73566 100644 --- a/adoc/p_execute.adoc +++ b/adoc/p_execute.adoc @@ -1,9 +1,38 @@ +// 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; + + * <> 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 + <> serves as a call stack for tracking + the nesting of FORTH executions by saving the "addresses" of the + successor cells. + + * <> implements the variation of starting the FORTH + execution somewhere within a definition rather than at the + beginning. ----- -rrqforth.asm: WORD p_execute,'EXECUTE',fasm ----- + * <>, <> and <> implement + different common ways of using word content other the as FORTH + definitions. + diff --git a/adoc/p_exit.adoc b/adoc/p_exit.adoc index c1f4a90..1d9d78a 100644 --- a/adoc/p_exit.adoc +++ b/adoc/p_exit.adoc @@ -1,9 +1,14 @@ +// 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. diff --git a/adoc/p_false.adoc b/adoc/p_false.adoc index 467e458..489082d 100644 --- a/adoc/p_false.adoc +++ b/adoc/p_false.adoc @@ -1,9 +1,11 @@ +// 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. diff --git a/adoc/p_find.adoc b/adoc/p_find.adoc index c8f355c..01c4579 100644 --- a/adoc/p_find.adoc +++ b/adoc/p_find.adoc @@ -1,9 +1,22 @@ +// 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 +<> 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. diff --git a/adoc/p_forth.adoc b/adoc/p_forth.adoc index 15c2695..e76b2fb 100644 --- a/adoc/p_forth.adoc +++ b/adoc/p_forth.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_greaterequal.adoc b/adoc/p_greaterequal.adoc index 8a11ab8..e89cb8c 100644 --- a/adoc/p_greaterequal.adoc +++ b/adoc/p_greaterequal.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_greaterthan.adoc b/adoc/p_greaterthan.adoc index b355859..2975d00 100644 --- a/adoc/p_greaterthan.adoc +++ b/adoc/p_greaterthan.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_gtR.adoc b/adoc/p_gtR.adoc new file mode 100644 index 0000000..c185ffb --- /dev/null +++ b/adoc/p_gtR.adoc @@ -0,0 +1,12 @@ +// 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. diff --git a/adoc/p_here.adoc b/adoc/p_here.adoc index 116c817..5a6c416 100644 --- a/adoc/p_here.adoc +++ b/adoc/p_here.adoc @@ -1,12 +1,20 @@ +// 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 <>. diff --git a/adoc/p_hex.adoc b/adoc/p_hex.adoc index 4ea5b7b..35ef0ff 100644 --- a/adoc/p_hex.adoc +++ b/adoc/p_hex.adoc @@ -1,7 +1,21 @@ -Word: HEX ----------- +// compile.asm: WORD p_hex,'HEX',fasm + anchor:p_hex[] + +=== Word: HEX + +.... +Data stack: ( -- ) +.... + +"HEX" is a function word that sets <> 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 ! ; ---- - +==== diff --git a/adoc/p_immediate.adoc b/adoc/p_immediate.adoc new file mode 100644 index 0000000..4c4b613 --- /dev/null +++ b/adoc/p_immediate.adoc @@ -0,0 +1,25 @@ +// 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 <>, <>, +<>, <>, <>, and <>. + + diff --git a/adoc/p_left_bracket.adoc b/adoc/p_left_bracket.adoc index 4907988..ead7d3b 100644 --- a/adoc/p_left_bracket.adoc +++ b/adoc/p_left_bracket.adoc @@ -1,18 +1,22 @@ +// 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 ! ; +---- ==== diff --git a/adoc/p_lessequal.adoc b/adoc/p_lessequal.adoc index 781c29c..9bf7f36 100644 --- a/adoc/p_lessequal.adoc +++ b/adoc/p_lessequal.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_lessthan.adoc b/adoc/p_lessthan.adoc index ce86406..99a0dff 100644 --- a/adoc/p_lessthan.adoc +++ b/adoc/p_lessthan.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_literal.adoc b/adoc/p_literal.adoc index b469880..35d98da 100644 --- a/adoc/p_literal.adoc +++ b/adoc/p_literal.adoc @@ -1,30 +1,27 @@ -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 @ ; +---- ==== diff --git a/adoc/p_literal_string.adoc b/adoc/p_literal_string.adoc index 5eaaec5..218f443 100644 --- a/adoc/p_literal_string.adoc +++ b/adoc/p_literal_string.adoc @@ -1,15 +1,23 @@ -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 <> but for a string literal. + +==== +.Word: LIT +[caption='Definition concept {counter:exec}: '] +---- +: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ; +---- +==== diff --git a/adoc/p_lparen.adoc b/adoc/p_lparen.adoc new file mode 100644 index 0000000..027d3d4 --- /dev/null +++ b/adoc/p_lparen.adoc @@ -0,0 +1,12 @@ +// 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. diff --git a/adoc/p_ltR.adoc b/adoc/p_ltR.adoc deleted file mode 100644 index f3c1b56..0000000 --- a/adoc/p_ltR.adoc +++ /dev/null @@ -1,9 +0,0 @@ -anchor:p_ltR[] - -Word: >R ----------- - ----- -stack.asm: WORD p_ltR, '>R',fasm ----- - diff --git a/adoc/p_malloc.adoc b/adoc/p_malloc.adoc index f1dd801..4a86f0b 100644 --- a/adoc/p_malloc.adoc +++ b/adoc/p_malloc.adoc @@ -1,9 +1,21 @@ +// 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 <> diff --git a/adoc/p_minus.adoc b/adoc/p_minus.adoc index 629c926..fddf23a 100644 --- a/adoc/p_minus.adoc +++ b/adoc/p_minus.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_mult.adoc b/adoc/p_mult.adoc index 5689d8a..083321f 100644 --- a/adoc/p_mult.adoc +++ b/adoc/p_mult.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_negate.adoc b/adoc/p_negate.adoc index b47e603..6c65a15 100644 --- a/adoc/p_negate.adoc +++ b/adoc/p_negate.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/p_nip.adoc b/adoc/p_nip.adoc index cc74eb7..8e14946 100644 --- a/adoc/p_nip.adoc +++ b/adoc/p_nip.adoc @@ -1,9 +1,20 @@ +// 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 ; ---- - +==== diff --git a/adoc/p_nl.adoc b/adoc/p_nl.adoc index 15b1a99..58bcae9 100644 --- a/adoc/p_nl.adoc +++ b/adoc/p_nl.adoc @@ -1,9 +1,11 @@ +// 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. diff --git a/adoc/p_not.adoc b/adoc/p_not.adoc index 1a70035..1582cf5 100644 --- a/adoc/p_not.adoc +++ b/adoc/p_not.adoc @@ -1,9 +1,14 @@ +// 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 <>. diff --git a/adoc/p_number.adoc b/adoc/p_number.adoc index 94d5a3c..d3bcce5 100644 --- a/adoc/p_number.adoc +++ b/adoc/p_number.adoc @@ -1,8 +1,27 @@ -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 +<> 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 +<> base, then digits 0-9 and, if in <> +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 ) ---- - +==== diff --git a/adoc/p_or.adoc b/adoc/p_or.adoc index ab5cbe7..7d8401f 100644 --- a/adoc/p_or.adoc +++ b/adoc/p_or.adoc @@ -1,9 +1,15 @@ +// 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 ----- diff --git a/adoc/p_over.adoc b/adoc/p_over.adoc index 78be243..5746eb6 100644 --- a/adoc/p_over.adoc +++ b/adoc/p_over.adoc @@ -1,9 +1,14 @@ +// 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 ----- diff --git a/adoc/p_pad.adoc b/adoc/p_pad.adoc index 3903cd0..1bd1638 100644 --- a/adoc/p_pad.adoc +++ b/adoc/p_pad.adoc @@ -1,9 +1,12 @@ +// 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 +<> (only), and otherwise free for temporary use. diff --git a/adoc/p_pick.adoc b/adoc/p_pick.adoc index 8f0376f..32f76b2 100644 --- a/adoc/p_pick.adoc +++ b/adoc/p_pick.adoc @@ -1,9 +1,16 @@ +// 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 <>, and 1 indicates the second top cell making it +the same as <>. ----- -stack.asm: WORD p_pick, 'PICK',fasm ----- diff --git a/adoc/p_plus.adoc b/adoc/p_plus.adoc index 9bf9cd7..ffabee2 100644 --- a/adoc/p_plus.adoc +++ b/adoc/p_plus.adoc @@ -1,10 +1,15 @@ +// 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. diff --git a/adoc/p_program_version.adoc b/adoc/p_program_version.adoc index 80d00a4..debc57d 100644 --- a/adoc/p_program_version.adoc +++ b/adoc/p_program_version.adoc @@ -1,9 +1,11 @@ +// 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. diff --git a/adoc/p_quit.adoc b/adoc/p_quit.adoc index 737421b..ff847d9 100644 --- a/adoc/p_quit.adoc +++ b/adoc/p_quit.adoc @@ -1,9 +1,14 @@ +// 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 <> and +executing them. diff --git a/adoc/p_read_stream_char.adoc b/adoc/p_read_stream_char.adoc index ba1579e..1472c27 100644 --- a/adoc/p_read_stream_char.adoc +++ b/adoc/p_read_stream_char.adoc @@ -1,9 +1,18 @@ +// 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 <>. diff --git a/adoc/p_read_word.adoc b/adoc/p_read_word.adoc index f917434..76bb0e6 100644 --- a/adoc/p_read_word.adoc +++ b/adoc/p_read_word.adoc @@ -1,9 +1,15 @@ +// 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 +<>, and there is a limit of 1024 characters. +At the end of the stream READ-WORD returns 0 length. diff --git a/adoc/p_right_bracket.adoc b/adoc/p_right_bracket.adoc index 4f8589d..218873a 100644 --- a/adoc/p_right_bracket.adoc +++ b/adoc/p_right_bracket.adoc @@ -1,21 +1,27 @@ +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 <> or a <>. 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 ! ; +---- ==== - - diff --git a/adoc/p_roll.adoc b/adoc/p_roll.adoc index 79083f2..a4d4419 100644 --- a/adoc/p_roll.adoc +++ b/adoc/p_roll.adoc @@ -1,9 +1,19 @@ +// 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 +<>; 2 indicates the third top cell making it the same as +<>. + + ----- -stack.asm: WORD p_roll, 'ROLL',fasm ----- diff --git a/adoc/p_rot.adoc b/adoc/p_rot.adoc index 5764e0e..649a406 100644 --- a/adoc/p_rot.adoc +++ b/adoc/p_rot.adoc @@ -1,9 +1,15 @@ +// 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 <>. diff --git a/adoc/p_sp.adoc b/adoc/p_sp.adoc index 01e770a..8f0ce9b 100644 --- a/adoc/p_sp.adoc +++ b/adoc/p_sp.adoc @@ -1,9 +1,10 @@ -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. diff --git a/adoc/p_state.adoc b/adoc/p_state.adoc index 460f7f9..62ed9c7 100644 --- a/adoc/p_state.adoc +++ b/adoc/p_state.adoc @@ -1,10 +1,12 @@ -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. diff --git a/adoc/p_stdin.adoc b/adoc/p_stdin.adoc index 5bb09b0..a013210 100644 --- a/adoc/p_stdin.adoc +++ b/adoc/p_stdin.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_stream.adoc b/adoc/p_stream.adoc index 37ffb5a..cec3e9a 100644 --- a/adoc/p_stream.adoc +++ b/adoc/p_stream.adoc @@ -1,9 +1,45 @@ +// 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 +<> 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 ---- +==== diff --git a/adoc/p_stream_nchars.adoc b/adoc/p_stream_nchars.adoc index c56b88a..0a9e85a 100644 --- a/adoc/p_stream_nchars.adoc +++ b/adoc/p_stream_nchars.adoc @@ -1,9 +1,14 @@ +// 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). diff --git a/adoc/p_strncmp.adoc b/adoc/p_strncmp.adoc index 19f2e69..54642bd 100644 --- a/adoc/p_strncmp.adoc +++ b/adoc/p_strncmp.adoc @@ -1,9 +1,18 @@ +// 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. diff --git a/adoc/p_swap.adoc b/adoc/p_swap.adoc index 981bde7..f2e27c7 100644 --- a/adoc/p_swap.adoc +++ b/adoc/p_swap.adoc @@ -1,9 +1,11 @@ +// 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. diff --git a/adoc/p_system.adoc b/adoc/p_system.adoc index 11224d6..11cc731 100644 --- a/adoc/p_system.adoc +++ b/adoc/p_system.adoc @@ -1,9 +1,14 @@ +// 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 <> +merely as a matter of segregation. diff --git a/adoc/p_tell.adoc b/adoc/p_tell.adoc index 4a607d7..a84fb1a 100644 --- a/adoc/p_tell.adoc +++ b/adoc/p_tell.adoc @@ -1,9 +1,11 @@ -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). diff --git a/adoc/p_terminate0.adoc b/adoc/p_terminate0.adoc index 4f39e85..e9644fe 100644 --- a/adoc/p_terminate0.adoc +++ b/adoc/p_terminate0.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_this_word.adoc b/adoc/p_this_word.adoc index 3380093..7372603 100644 --- a/adoc/p_this_word.adoc +++ b/adoc/p_this_word.adoc @@ -1,11 +1,12 @@ +// 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 <> as cache for the [n:char*] diff --git a/adoc/p_true.adoc b/adoc/p_true.adoc index 30e1fcc..8392542 100644 --- a/adoc/p_true.adoc +++ b/adoc/p_true.adoc @@ -1,9 +1,11 @@ +// 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. diff --git a/adoc/p_tuck.adoc b/adoc/p_tuck.adoc index d06a678..965f0d3 100644 --- a/adoc/p_tuck.adoc +++ b/adoc/p_tuck.adoc @@ -1,9 +1,20 @@ +// 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 ; ---- - +==== diff --git a/adoc/p_unequal.adoc b/adoc/p_unequal.adoc index 2a1791d..640c2a6 100644 --- a/adoc/p_unequal.adoc +++ b/adoc/p_unequal.adoc @@ -1,9 +1,12 @@ +// 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. diff --git a/adoc/p_within.adoc b/adoc/p_within.adoc index 3d7ea49..911325f 100644 --- a/adoc/p_within.adoc +++ b/adoc/p_within.adoc @@ -1,9 +1,21 @@ +// 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 ; ---- - +==== diff --git a/adoc/p_words.adoc b/adoc/p_words.adoc index b2cae3d..d51c9d8 100644 --- a/adoc/p_words.adoc +++ b/adoc/p_words.adoc @@ -1,9 +1,11 @@ -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). diff --git a/adoc/p_xor.adoc b/adoc/p_xor.adoc index 04f763a..5c8b637 100644 --- a/adoc/p_xor.adoc +++ b/adoc/p_xor.adoc @@ -1,9 +1,13 @@ +// 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. diff --git a/adoc/return_stack.adoc b/adoc/return_stack.adoc index 649902c..900d316 100644 --- a/adoc/return_stack.adoc +++ b/adoc/return_stack.adoc @@ -1,8 +1,11 @@ +// 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. diff --git a/reference.adoc b/reference.adoc index 0d71f8f..d44db88 100644 --- a/reference.adoc +++ b/reference.adoc @@ -1,7 +1,9 @@ -RRQFORTH Reference Documentation -================================ -// :toc: += RRQFORTH Reference Documentation +:author: Ralph Ronnquist +:plus: + + +== Compilation words // include::compile.adoc[] include::adoc/p_allot.adoc[] include::adoc/p_base.adoc[] @@ -14,6 +16,7 @@ include::adoc/p_does.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[] @@ -22,6 +25,7 @@ include::adoc/p_right_bracket.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[] @@ -39,6 +43,7 @@ include::adoc/p_unequal.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[] @@ -47,6 +52,7 @@ include::adoc/p_mult.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[] @@ -61,6 +67,7 @@ include::adoc/p_dovalue.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[] @@ -68,6 +75,7 @@ include::adoc/p_system.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[] @@ -76,7 +84,7 @@ include::adoc/p_2swap.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[] @@ -87,6 +95,7 @@ include::adoc/p_rot.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[] @@ -103,6 +112,7 @@ include::adoc/p_stream.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[] @@ -110,4 +120,15 @@ include::adoc/p_forth.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[] diff --git a/wordindex.adoc b/wordindex.adoc new file mode 100644 index 0000000..c6bcd71 --- /dev/null +++ b/wordindex.adoc @@ -0,0 +1,121 @@ + +== Index of word links + +<> +<> +<> + +<> +<> +<> + +<> +<> +<> +<> + +<> +<> +<> +<> + +<> +<> + +<> +<> +<> +<> +<> +<> + +<> +<> +<> +<> +<> +<> +<> +<> +<> +<> +<> +<> +<> +<> +<> + +<> +<> +<> +<> +<> + +<> +<> +<> + +<> +<> +<> + +<> +<> + +<> + +<> +<> +<> +<> +<> + +<> +<> +<> + +<> +<> +<> +<> +<> + +<> +<> +<> + +<> +<> +<> + +<> + +<> +<> +<> +<> +<> +<> +<> + +<> +<> +<> +<> +<> +<> +<> +<> + +<> +<> +<> +<> +<> + +<> + +<> +<> + +<> -- 2.39.2