From: Ralph Ronnquist Date: Fri, 11 Jun 2021 09:48:06 +0000 (+1000) Subject: better documentation X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=661f002edaa942af5603d469ea28d9240c9542e2;p=rrq%2Frrqforth.git better documentation --- diff --git a/adoc/p_literal_string.adoc b/adoc/p_literal_string.adoc index ba94b0f..1d9ffdb 100644 --- a/adoc/p_literal_string.adoc +++ b/adoc/p_literal_string.adoc @@ -1,21 +1,22 @@ -//compile.asm: WORD p_literal_string,'S"',fasm ;; " (fool emacs) +//compile.asm: WORD p_literal_string,'LIT-STRING',fasm anchor:p_literal_string[] -=== Word: S" +=== Word: LIT-STRING .... Data stack: ( -- chars* n ) .... -"S"" is a function word that pushes the [n:char] pointer for a string -inlined subsequently to it in the containing definition. This is -similar to <> but for a string literal. +"LIT-STRING" is a function word that pushes the char* and length n of +a subsequent inline string, then advances execution to continue after +the string. This is similar to <> but for a block literal. + +Note that the inlined byte count includes the terminating NUL byte. ==== -.Definition concept for LIT +.Definition concept for LIT-STRING **** -: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ; +: LIT-STRING R@ DUP @ 8 + R@ @ 2DUP + R> + >R 1 - ; **** ==== - diff --git a/adoc/p_literal_string_compile.adoc b/adoc/p_literal_string_compile.adoc new file mode 100644 index 0000000..23b3c79 --- /dev/null +++ b/adoc/p_literal_string_compile.adoc @@ -0,0 +1,18 @@ +//compile.asm: WORD p_literal_string_compile,'S"',fasm ;; " (fool emacs) + +anchor:p_literal_string_compile[] + +=== Word: S" + +.... +Data stack: ( -- ) Input stream: " chars" +.... + +"S"" is an immediate function word that compiles the subseqent +characters up to terminating double-quote into the current definition, +preceded by a <> cell, and the count of +bytes scanned. The inline text includes a terminating NUL character +which also is included in the inlined count. + +Note that "S"" uses <> for reading the string. + diff --git a/adoc/p_semicolon.adoc b/adoc/p_semicolon.adoc index c16e147..0caf2f5 100644 --- a/adoc/p_semicolon.adoc +++ b/adoc/p_semicolon.adoc @@ -9,8 +9,9 @@ anchor:p_semicolon[] Data stack: ( -- ) .... -";" (semi-colon) is a function word that ends a new forth definition -by means of adding an <> +";" (semi-colon) is an immediate function word that ends a new forth +definition by means of adding an <> cell, then changing +< to interpreting. ==== .Definition concept for ; diff --git a/adoc/p_str2temp.adoc b/adoc/p_str2temp.adoc new file mode 100644 index 0000000..5415d5e --- /dev/null +++ b/adoc/p_str2temp.adoc @@ -0,0 +1,24 @@ +// temp.asm: WORD p_str2temp,'STR>TEMP' + +anchor:p_str2temp[] + +=== Word: STR>TEMP + +**** +Data stack: ( char* n -- char* n ) +**** + +"STR>TEMP" is a function word that copies a given string plus a +terminating NUL character into a <> snippet, +all preceded by a length cell. It returns a pointer for to the text in +the snippet and its length, excluding the NUL character at end and the +length cell before tie text. + +.copied string +[caption='Layout for '] +---- + length: 8 bytes +returned char*: n bytes + nul: 1 byte +---- + diff --git a/adoc/p_temp.adoc b/adoc/p_temp.adoc new file mode 100644 index 0000000..b928dd3 --- /dev/null +++ b/adoc/p_temp.adoc @@ -0,0 +1,21 @@ +// temp.asm: WORD p_temp,'TEMP',fasm + +anchor:p_temp[] + +=== Word: TEMP + +**** +Data stack: ( size -- addr ) +**** + +"TEMP" is a function word that "allocates" a <> +area of given size and returns its base address. The allocation is +temporary and only valid until there is a later allocation that +overruns this area. + +Allocations are done in succession until the requested size overruns +the <>. If so, the allocation pointer is reset +and the space is allocated from start again. This is all intended for +small and short-lived data areas. + + diff --git a/adoc/p_tempspace.adoc b/adoc/p_tempspace.adoc new file mode 100644 index 0000000..2afa2b4 --- /dev/null +++ b/adoc/p_tempspace.adoc @@ -0,0 +1,23 @@ +// temp.asm: WORD p_tempspace,'TEMPSPACE',dovariable + + +anchor:p_tempspace[] + +=== Word: TEMPSPACE + +.... +Data stack: ( -- a ) +.... + +"TEMPSPACE" is a variable word that holds three cells the for managing +"temporary memory": + + * the size of the temporary memory space (default 104857600 bytes) + * the base address for whole temporary memory area + * the amount currently used + +This memory is intended to be used by requesting snippets of memory in +a cyclic fashion via <> without concern about it possibly +overlapping a prior request. + + diff --git a/reference.adoc b/reference.adoc index e9e369f..7f1100e 100644 --- a/reference.adoc +++ b/reference.adoc @@ -177,6 +177,8 @@ include::adoc/p_literal.adoc[] include::separator.adoc[] include::adoc/p_literal_string.adoc[] include::separator.adoc[] +include::adoc/p_literal_string_compile.adoc[] +include::separator.adoc[] include::adoc/p_load_buffer_size.adoc[] include::separator.adoc[] include::adoc/p_load_file.adoc[] @@ -259,6 +261,8 @@ include::adoc/p_stream.adoc[] include::separator.adoc[] include::adoc/p_stream_nchars.adoc[] include::separator.adoc[] +include::adoc/p_str2temp.adoc[] +include::separator.adoc[] include::adoc/p_strlen.adoc[] include::separator.adoc[] include::adoc/p_strncmp.adoc[] @@ -271,6 +275,10 @@ include::adoc/p_system.adoc[] include::separator.adoc[] include::adoc/p_tell.adoc[] include::separator.adoc[] +include::adoc/p_temp.adoc[] +include::separator.adoc[] +include::adoc/p_tempspace.adoc[] +include::separator.adoc[] include::adoc/p_terminate0.adoc[] include::separator.adoc[] include::adoc/p_tfa2cfa.adoc[] diff --git a/wordindex.adoc b/wordindex.adoc index 66d0ae8..f849eb7 100644 --- a/wordindex.adoc +++ b/wordindex.adoc @@ -39,7 +39,7 @@ xref:p_put_plus[!{plus}] {nbsp} xref:p_get_n_increment[@n{plus}{plus}] {nbsp} xref:p_get_n_decrement[@n--] {nbsp} xref:p_Ccomma[C,] {nbsp} -xref:p_literal_string[S"] {nbsp} +xref:p_literal_string_compile[S"] {nbsp} xref:p_gtR[>R] {nbsp} xref:p_Rget[R@] {nbsp} xref:p_Rgt[R>] {nbsp} @@ -113,6 +113,7 @@ xref:p_immediate[IMMEDIATE] {nbsp} xref:p_input[INPUT] {nbsp} xref:p_literal[LIT] {nbsp} +xref:p_literal_string[LIT-STRING] {nbsp} xref:p_load_buffer_size[LOAD-BUFFER-SIZE] {nbsp} xref:p_load_file[LOAD-FILE] {nbsp} @@ -148,6 +149,7 @@ xref:p_state[STATE] {nbsp} xref:p_stdin[STDIN] {nbsp} xref:p_stream[STREAM] {nbsp} xref:p_stream_nchars[STREAM-NCHARS] {nbsp} +xref:p_str2temp[STR>TEMP] {nbsp} xref:p_strlen[STRLEN] {nbsp} xref:p_strncmp[STRNCMP] {nbsp} xref:p_strncpy[STRNCPY] {nbsp} @@ -156,6 +158,8 @@ xref:p_system[SYSTEM] {nbsp} xref:p_tell[TELL] {nbsp} xref:p_dot_temp[.TEMP] {nbsp} +xref:p_temp.adoc[TEMP] {nbsp} +xref:p_tempspace[TEMPSPACE] {nbsp} xref:p_terminate0[TERMINATE0] {nbsp} xref:p_tfa2cfa[TFA>CFA] {nbsp} xref:p_tfa2dfa[TFA>DFA] {nbsp}