upgrade

[rrq/rrqforth.git] / adoc / p_evaluate_stream.adoc

diff --git a/adoc/p_evaluate_stream.adoc b/adoc/p_evaluate_stream.adoc
index aae56c437ef46057b96120a13b0d5b9c48120767..abd86d5f40bce9063f415012d79c12fa251aaecf 100644 (file)
--- a/adoc/p_evaluate_stream.adoc
+++ b/adoc/p_evaluate_stream.adoc
@@ -1,11 +1,44 @@
+// compile.asm:        WORD p_evaluate_stream,'EVALUATE-STREAM'
+
 anchor:p_evaluate_stream[]
 
-Word: 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.
 
-----
-compile.asm:   WORD p_evaluate_stream,'EVALUATE-STREAM'
-----
+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.