// compile.asm:	WORD p_evaluate_stream,'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.