A recognizer is a word to which you pass a string. If the recognizer recognizes the string, it typically returns some data and the xt of a word for processing the data; this word is called the translator. If the recognizer does not recognize the string, it returns 0.
All recognizers have the stack effect ( c-addr u – i*x xt | 0 ).
Recognizers take a string and on success return some data and a
translator for interpreting that data. Gforth implements that
translator as xt (executing it will perform the appropriate action to
handle the token in the current state), but other Forth systems may
implement it as actual table, with three xts inside. The first xt is
the interpretation/run-time xt, it performs the interpretation semantics
on the data (usually, this means it just leaves the data on the stack).
The second xt performs the compilation semantics, it gets the data and
the run-time semantics xt. The third xt perfoms the postpone semantics,
it also gets the data and the run-time semantics xt. You can use
postponing to postpone the run-time xt.
Recognizers are organized as stack, so you can arrange the sequence of recognizers in the same way as the vocabulary stack. Recognizer stacks are themselves recognizers, i.e. they are executable, take a string and return a translator.
rec-nt ( addr u – nt translate-nt | 0 ) gforth-experimental “rec-nt”
recognize a name token
rec-num ( addr u – n/d table | 0 ) gforth-experimental “rec-num”
converts a number to a single/double integer
rec-float ( addr u – r translate-float | 0 ) gforth-experimental “rec-float”
recognize floating point numbers
rec-complex ( addr u – z translate-complex | 0 ) gforth-1.0 “rec-complex”
Complex numbers are always in the format a+bi, where a and b are floating point numbers including their signs
rec-string ( addr u – addr u’ scan-translate-string | 0 ) gforth-experimental “rec-string”
Convert strings enclosed in double quotes into string literals,
escapes are treated as in S\".
rec-to ( addr u – xt n translate-to | 0 ) gforth-experimental “rec-to”
words prefixed with -> are treated as if preceeded by
TO, with +> as +TO, with
'> as ADDR, with @> as ACTION-OF, and
with => as IS.
rec-tick ( addr u – xt translate-num | 0 ) gforth-experimental “rec-tick”
words prefixed with ` return their xt.
Example: `dup gives the xt of dup
rec-dtick ( addr u – nt translate-num | 0 ) gforth-experimental “rec-dtick”
words prefixed with `` return their nt.
Example: ``S" gives the nt of S"
rec-body ( addr u – xt translate-num | 0 ) gforth-experimental “rec-body”
words bracketed with '<' '>' return their body.
Example: <dup> gives the body of dup
rec-env ( addr u – addr u translate-env | 0 ) gforth-1.0 “rec-env”
words enclosed by ${ and } are passed to getenv
to get the OS-environment variable as string.
Example: ${HOME} gives the home directory.
rec-scope ( addr u – nt rectype-nt | 0 ) gforth-experimental “rec-scope”
Recognizes strings of the form (simplified)
wordlist:word, where wordlist is found in the
search order. The result is the same as for rec-nt for
word (the ordinary word recognizer) if the search order
consists only of wordlist. The general form can have
several wordlists preceding word, separated by :;
the first (leftmost) wordlist is found in the search order, the
second in the first, etc. word is the looked up in the
last (rightmost) wordlist.
rec-meta ( addr u – xt translate-to | 0 ) gforth-1.0 “rec-meta”
words prefixed with recognizer? are processed by
rec-recognizer to disambiguate recognizers.
Example: hex num?cafe num?add will be parsed as number only
Example: float?123. will be parsed as float
get-recognizers ( – xt1 .. xtn n ) gforth-obsolete “get-recognizers”
push the content on the recognizer stack
set-recognizers ( xt1 .. xtn n – ) gforth-obsolete “set-recognizers”
set the recognizer stack from content on the stack
recognize ( addr u rec-addr – ... rectype ) gforth-experimental “recognize”
apply a recognizer stack to a string, delivering a token
recognizer-sequence: ( xt1 .. xtn n "name" – ) gforth-experimental “recognizer-sequence:”
concatenate a stack of recognizers to one recognizer with the name "name". xtn is tried first, xt1 last, just like on the recognizer stack
forth-recognize ( c-addr u – ... translate-xt ) recognizer “forth-recognize”
The system recognizer
forth-recognizer ( – xt ) gforth-obsolete “forth-recognizer”
backward compatible to Matthias Trute recognizer API. This construct turns a deferred word into a value-like word.
set-forth-recognize ( xt – ) gforth-obsolete “set-forth-recognize”
Change the system recognizer
?found ( token|0 – token|never ) gforth-experimental “?found”
performs an undefined word throw if the token is 0.
translate: ( int-xt comp-xt post-xt "name" – ) gforth-experimental “translate:”
create a new recognizer table. Items are in order of STATE value, which are 0 or negative. Up to 7 slots are available for extensions.
translate-nt ( i*x nt – j*x ) gforth-experimental “translate-nt”
translate a name token
translate-num ( x – | x ) gforth-experimental “translate-num”
translate a number
translate-dnum ( dx – | dx ) gforth-experimental “translate-dnum”
translate a double number
translate-float ( r – | r ) gforth-experimental “translate-float”
A translator for a float number.
try-recognize ( addr u xt – results | false ) gforth-experimental “try-recognize”
For nested recognizers: try to recognize addr u, and execute xt to check if the result is desired. If xt returns false, clean up all side effects of the recognizer, and return false. Otherwise return the results of the call to xt, of which the topmost is non-zero.
interpreting ( translator – ) gforth-experimental “interpreting”
perform interpreter action of translator
compiling ( translator – ) gforth-experimental “compiling”
perform compile action of translator
postponing ( translator – ) gforth-experimental “postponing”
perform postpone action of translator
translate-method: ( "name" – ) gforth-experimental “translate-method:”
create a new translate method, extending the translator table.
You can assign an xt to an existing rectype by using
xt rectype to translator.
set-state ( xt – ) gforth-experimental “set-state”
change the current state of the system so that executing a translator matches the translate-method passed as xt
get-state ( – xt ) gforth-experimental “get-state”
return the currently used translate-method xt