factor/library/syntax/parser.facts

USING: help kernel parser sequences ;

HELP: skip "( i seq quot -- n )"
{ $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 "( n line -- n )"
{ $values { "n" "a non-negative integer" } { "line" "a string" } }
{ $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) "( n line -- start end )"
{ $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 "( -- token )"
{ $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 "( -- word )"
{ $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 f
{ $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: scan-word "( -- obj )"
{ $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 "( escape -- ch )"
{ $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 "( -- str )"
{ $values { "str" "a new string" } }
{ $description "Parses the line until a quote (\"), interpreting escape codes along the way." } ;