Node:The Input Stream, Next:Word Lists, Previous:The Text Interpreter, Up:Words
The text interpreter reads from the input stream, which can come from
several sources (see Input Sources). Some words, in particular
defining words, but also words like
', read parameters from the
input stream instead of from the stack.
Such words are called parsing words, because they parse the input stream. Parsing words are hard to use in other words, because it is hard to pass program-generated parameters through the input stream. They also usually have an unintuitive combination of interpretation and compilation semantics when implemented naively, leading to various approaches that try to produce a more intuitive behaviour (see Combined words).
It should be obvious by now that parsing words are a bad idea. If you
want to implement a parsing word for convenience, also provide a factor
of the word that does not parse, but takes the parameters on the stack.
To implement the parsing word on top if it, you can use the following
Parse ccc, delimited by char, in the parse area. c-addr u specifies the parsed string within the parse area. If the parse area was empty, u is 0.
parsechar "ccc<char>" -- c-addr u core-ext ``parse''
Get the next word from the input buffer
parse-word"name" -- c-addr u gforth ``parse-word''
old name for
name-- c-addr u gforth-obsolete ``name''
Skip leading delimiters. Parse ccc, delimited by char, in the parse area. c-addr is the address of a transient region containing the parsed string in counted-string format. If the parse area was empty or contained no characters other than delimiters, the resulting string has zero length. A program may replace characters within the counted string. OBSOLESCENT: the counted string has a trailing space that is not included in its length.
wordchar "<chars>ccc<char>-- c-addr core ``word''
parses string, translating
\"-parse"string"<"> -- c-addr u unknown ``\"-parse''
\-escapes to characters (as in C). The resulting string resides at
here char+. The supported
\eESC (not in C99),
\[0-7]+ octal numerical character value,
\x[0-9a-f]+ hex numerical character value; a
\before any other character represents that character (only ', \, ? in C99).
Attempt to fill the input buffer from the input source. When the input source is the user input device, attempt to receive input into the terminal input device. If successful, make the result the input buffer, set
refill-- flag core-ext,block-ext,file-ext ``refill''
>INto 0 and return true; otherwise return false. When the input source is a block, add 1 to the value of
BLKto make the next block the input source and current input buffer, and set
>INto 0; return true if the new value of
BLKis a valid block number, false otherwise. When the input source is a text file, attempt to read the next line from the file. If successful, make the result the current input buffer, set
>INto 0 and return true; otherwise, return false. A successful result includes receipt of a line containing 0 characters.
Conversely, if you have the bad luck (or lack of foresight) to have to
deal with parsing words without having such factors, how do you pass a
string that is not in the input stream to it?
Make addr u the current input source, execute xt
execute-parsing... addr u xt -- ... unknown ``execute-parsing''
( ... -- ... ), then restore the previous input source.
If you want to run a parsing word on a file, the following word should
Make fileid the current input source, execute xt
execute-parsing-filei*x fileid xt -- j*x unknown ``execute-parsing-file''
( i*x -- j*x ), then restore the previous input source.