factor/library/syntax/parser.facts

USING: help kernel parser sequences words ;

HELP: skip
{ $values { "n" "a starting index" } { "seq" "a sequence" } { "quot" "a quotation with stack effect " { $snippet "( elt -- ? )" } } }
{ $description "Variant of " { $link find* } " that outputs the length of the sequence instead of -1 if no elements satisfy the predicate." } ;

HELP: skip-blank
{ $description "Skips whitespace characters in the line currently being parsed." }
$parsing-note ;

HELP: skip-word
{ $values { "m" "a non-negative integer" } { "line" "a string" } { "n" "a non-negative integer" } }
{ $description "Searches forward in the line for the end of a word starting at index " { $snippet "n" } ". This is a word in the Factor sense; that is, any character other than whitespace is a constituent of the word, and a quote (\") is a word by itself." }
{ $errors "Throws an error if " { $snippet "n" } " is out of bounds." } ;

HELP: (scan)
{ $values { "n" "a non-negative integer" } { "line" "a string" } { "start" "start offset of next word" } { "end" "end offset of next word" } }
{ $description "Scans forward for the next word in the line. If the end of the line is reached, both outputs equal the length of the line." } ;

HELP: scan
{ $values { "token" "a string" } }
{ $description "Reads the next token from the line currently being parsed. This is the key word that the Factor parser is built on." }
$parsing-note ;

HELP: CREATE
{ $values { "word" "a word" } }
{ $description "Reads the next token from the line currently being parsed, and creates a word with that name in the current vocabulary." }
{ $errors "Throws an error if the end of the line is reached." }
$parsing-note ;

HELP: string-mode
{ $var-description
    "Variable toggling string mode. In string mode, the parser does not look up words, and instead just appends strings to the parse tree as they are read."
    $terpri
    "Since no parsing words are invoked in string mode, there is a special case that ends it; if the token " { $snippet ";" } " is read, string mode is switched off and the " { $link POSTPONE: ; } " parsing word is called."
} ;

HELP: no-word
{ $values { "name" "a string" } { "word" "a word" } }
{ $description "Throws a " { $link no-word } " error." }
{ $error-description "Thrown if the parser encounters a token which does not name a word in the current vocabulary search path. If any words with this name exist in vocabularies not part of the search path, a number of restarts will offer to add those vocabularies to the search path and use the chosen word." }
{ $notes "Apart from a missing " { $link POSTPONE: USE: } ", this error can also indicate an ordering issue. In Factor, words must be defined before they can be called. Mutual recursion can be implemented via " { $link POSTPONE: DEFER: } "." } ;

HELP: scan-word
{ $values { "obj" "a word or a number" } }
{ $description "Reads the next token from the line currently being parsed. First tries to look up the word in the dictionary, and if the lookup fails, attempts to convert the token to a number." }
{ $errors "Throws an error if the token does not name a word, and does not parse as a number." }
$parsing-note ;

HELP: bad-escape
{ $error-description "This error is thrown if the parser encounters an invalid escape code following a backslash (" { $snippet "\\" } ") in a string literal. See " { $link "escape" } " for a list of valid escape codes." } ;

HELP: escape
{ $values { "escape" "a single-character escape" } { "ch" "a character" } }
{ $description "Converts from a single-character escape code and the corresponding character." }
{ $examples { $example "CHAR: n escape CHAR: \n = ." "t" } } ;

HELP: parse-string
{ $values { "str" "a new string" } }
{ $description "Parses the line until a quote (\"), interpreting escape codes along the way." } ;

HELP: parse-effect
{ $values { "effect" "an instance of " { $link effect } } }
{ $description "Parses a stack effect from the current input line." }
{ $notes "This word is used by " { $link POSTPONE: ( } " to parse stack effect declarations." } ;

HELP: parse-base
{ $values { "base" "an integer between 2 and 36" } }
{ $description "Reads an integer in a specific numerical base from the parser input. This word can only be called from parsing words." } ;