adoc/p_evaluate_stream.adoc

   1 // compile.asm: WORD p_evaluate_stream,'EVALUATE-STREAM'
   2
   3 anchor:p_evaluate_stream[]
   4
   5 === Word: EVALUATE-STREAM
   6
   7 ....
   8 Data stack: ( stream -- ??? 0/1 )     Input stream: ......
   9 ....
  10
  11 "EVALUATE-STREAM" is a function word that reads words separated by
  12 whitespace from the stream until it discovers an unknown word, or the
  13 stream is exhausted. Depending on <<p_state,STATE>>, the words are
  14 either executed or compiled, and all ther stack and heap effects are
  15 preserved. "EVALUATE-STREAM" returns with an additional 0 or 1 on the
  16 stack to respectively indicate that the last word was unkown, i.e. not
  17 found (<<p_find,FIND>>) in the current word list
  18 (<<p_current_wordlist,CURRENT-WORDLIST>>) and not a
  19 <<p_number,NUMBER>> of the current <<p_base,BASE>>.
  20
  21 Note that numbers in the current <<p_base,BASE>> are treated as known
  22 words that are parsed into cell values. If interpreting, then the
  23 value is left on the stack. If compiling, then the value is added to
  24 the heap subsequent to first adding <<p_literal,LIT>>, which is done
  25 so as to make that value be push to the data stack upon a later
  26 execution.
  27
  28 In the <<p_decimal,DECIMAL>> base, the number word may begin with a
  29 minus sign.
  30
  31 The words are read and executed one by one, accounting for whether its
  32 a number word or not, whether it is an <<p_immediate,IMMEDIATE>> word
  33 or not, and whether the state at the time of execution indicates
  34 "compiling" of "interpreting". Immediate words are executed in both
  35 interpreting and compiling state, while other words have their CFA get
  36 added to the heap so as to gain their execution effect upon a later
  37 execution.
  38
  39 Note that "EVALUATE-STREAM" keeps the stream (pointer) on the return
  40 stack while reading, parsing and executing.
  41
  42 If "EVALUATE-STREAM" ends with 0, then <<p_this_word,THIS-WORD>> holds
  43 the [n:chars] reference of the offending word in the stream buffer.
  44