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
words:
parse
char "ccc<char>" -- c-addr u core-ext ``parse''
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.
parse-word
"name" -- c-addr u gforth ``parse-word''
Get the next word from the input buffer
name
-- c-addr u gforth-obsolete ``name''
old name for parse-word
word
char "<chars>ccc<char>-- c-addr core ``word''
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.
\"-parse
"string"<"> -- c-addr u unknown ``\"-parse''
parses string, translating \
-escapes to characters (as in
C). The resulting string resides at here char+
. The
supported \-escapes
are: \a
BEL (alert), \b
BS, \e
ESC (not in C99), \f
FF, \n
newline,
\r
CR, \t
HT, \v
VT, \"
",
\
[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).
refill
-- flag core-ext,block-ext,file-ext ``refill''
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 >IN
to 0 and return true;
otherwise return false. When the input source is a block, add 1
to the value of BLK
to make the next block the input
source and current input buffer, and set >IN
to 0;
return true if the new value of BLK
is 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 >IN
to 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?
execute-parsing
... addr u xt -- ... unknown ``execute-parsing''
Make addr u the current input source, execute xt (
... -- ... )
, then restore the previous input source.
If you want to run a parsing word on a file, the following word should
help:
execute-parsing-file
i*x fileid xt -- j*x unknown ``execute-parsing-file''
Make fileid the current input source, execute xt ( i*x
-- j*x )
, then restore the previous input source.