147 lines
7.8 KiB
Plaintext
147 lines
7.8 KiB
Plaintext
USING: help kernel parser sequences words math strings vectors
|
|
quotations generic ;
|
|
|
|
IN: help
|
|
: $parsing-note
|
|
drop
|
|
"This word should only be called from parsing words."
|
|
$notes ;
|
|
|
|
HELP: use
|
|
{ $var-description "A variable holding the current vocabulary search path as a sequence of hashtables." } ;
|
|
|
|
{ use in use+ set-use set-in POSTPONE: USING: POSTPONE: USE: file-vocabs } related-words
|
|
|
|
HELP: in
|
|
{ $var-description "A variable holding the current vocabulary for new definitions." } ;
|
|
|
|
HELP: check-vocab
|
|
{ $values { "name" "a string" } { "vocab" "a hashtable or " { $link f } } }
|
|
{ $description "Outputs a named vocabulary. If the vocabulary does not exist, throws a restartable " { $link check-vocab } " error. If the user invokes the restart, this word outputs " { $link f } "." }
|
|
{ $error-description "Thrown by " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " when a given vocabulary does not exist. Vocabularies must be created by " { $link POSTPONE: IN: } " before being used." } ;
|
|
|
|
HELP: use+
|
|
{ $values { "vocab" "a string" } }
|
|
{ $description "Adds a new vocabulary at the front of the search path. Subsequent word lookups by the parser will search this vocabulary first." }
|
|
$parsing-note
|
|
{ $errors "Throws an error if the vocabulary does not exist." } ;
|
|
|
|
HELP: set-use
|
|
{ $values { "seq" "a sequence of strings" } }
|
|
{ $description "Sets the vocabulary search path. Later vocabularies take precedence." }
|
|
{ $errors "Throws an error if one of the vocabularies does not exist." }
|
|
$parsing-note ;
|
|
|
|
HELP: add-use
|
|
{ $values { "seq" "a sequence of strings" } }
|
|
{ $description "Adds multiple vocabularies to the search path, with later vocabularies taking precedence." }
|
|
{ $errors "Throws an error if one of the vocabularies does not exist." }
|
|
$parsing-note ;
|
|
|
|
HELP: set-in
|
|
{ $values { "name" "a string" } }
|
|
{ $description "Sets the current vocabulary where new words will be defined, creating the vocabulary first if it does not exist." }
|
|
$parsing-note ;
|
|
|
|
HELP: create-in
|
|
{ $values { "string" "a word name" } { "word" "a new word" } }
|
|
{ $description "Creates a word in the current vocabulary. Until re-defined, the word throws an error when invoked." }
|
|
$parsing-note ;
|
|
|
|
HELP: parse-tokens
|
|
{ $values { "end" string } { "vec" "a new vector of strings" } }
|
|
{ $description "Reads a sequence of tokens until the first occurrence of " { $snippet "end" } ". The tokens remain as strings and are not processed in any way." }
|
|
{ $examples "This word is used to implement " { $link POSTPONE: USING: } "." }
|
|
$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: 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 { "word/number/f" "a word, number or " { $link f } } }
|
|
{ $description "Reads the next token from parser input. If the token is a valid number literal, it is converted to a number, otherwise the dictionary is searched for a word named by the token. Outputs " { $link f } " if the end of the input has been reached." }
|
|
{ $errors "Throws an error if the token does not name a word, and does not parse as a number." }
|
|
$parsing-note ;
|
|
|
|
HELP: unexpected
|
|
{ $values { "want" "a " { $link word } " or " { $link f } } { "got" word } }
|
|
{ $description "Throws an " { $link unexpected } " error." }
|
|
{ $error-description "Thrown by the parser if an unmatched closing delimiter is encountered." }
|
|
{ $examples
|
|
"Parsing the following snippet will throw this error:"
|
|
{ $code "[ 1 2 3 }" }
|
|
} ;
|
|
|
|
HELP: parse-step
|
|
{ $values { "accum" vector } { "end" word } { "?" "a boolean" } }
|
|
{ $description "Parses a token. If the token is a number or an ordinary word, it is added to the accumulator. If it is a parsing word, calls the parsing word with the accumulator on the stack. Outputs " { $link f } " if " { $snippet "end" } " is encountered, " { $link t } " otherwise." }
|
|
$parsing-note ;
|
|
|
|
HELP: (parse-until)
|
|
{ $values { "accum" vector } { "end" word } }
|
|
{ $description "Parses objects from parser input until " { $snippet "end" } " is encountered, adding them to the accumulator." }
|
|
$parsing-note ;
|
|
|
|
HELP: parse-until
|
|
{ $values { "end" word } { "vec" "a new vector" } }
|
|
{ $description "Parses objects from parser input until " { $snippet "end" } ". Outputs a new vector with the results." }
|
|
{ $examples "This word is used to implement " { $link POSTPONE: PROVIDE: } "." }
|
|
$parsing-note ;
|
|
|
|
{ parse-tokens (parse-until) parse-until } related-words
|
|
|
|
HELP: parsed
|
|
{ $values { "accum" vector } { "obj" object } }
|
|
{ $description "Convenience word for parsing words. It behaves exactly the same as " { $link push } ", except the accumulator remains on the stack." }
|
|
$parsing-note ;
|
|
|
|
HELP: with-parser
|
|
{ $values { "lexer" lexer } { "quot" "a quotation with stack effect " { $snippet "( -- accum )" } } { "newquot" "a new " { $link quotation } } }
|
|
{ $description "Sets up the parser and calls the quotation. The quotation can make use of parsing words such as " { $link scan } " and " { $link parse-until } ". It must yield a sequence, which is converted to a quotation and output. Any errors thrown by the quotation are wrapped in parse errors." } ;
|
|
|
|
HELP: (parse-lines)
|
|
{ $values { "lexer" lexer } { "quot" "a new " { $link quotation } } }
|
|
{ $description "Parses Factor source code using a custom lexer. The vocabulary search path is taken from the current scope." }
|
|
{ $errors "Throws a " { $link parse-error } " if the input is malformed." } ;
|
|
|
|
HELP: parse-lines
|
|
{ $values { "lines" "a sequence of strings" } { "quot" "a new " { $link quotation } } }
|
|
{ $description "Parses Factor source code which has been tokenized into lines. The vocabulary search path is taken from the current scope." }
|
|
{ $errors "Throws a " { $link parse-error } " if the input is malformed." } ;
|
|
|
|
HELP: parse-effect
|
|
{ $values { "effect" "an instance of " { $link effect } } }
|
|
{ $description "Parses a stack effect from the current input line." }
|
|
{ $examples "This word is used by " { $link POSTPONE: ( } " to parse stack effect declarations." }
|
|
$parsing-note ;
|
|
|
|
HELP: parse-base
|
|
{ $values { "base" "an integer between 2 and 36" } { "parsed" integer } }
|
|
{ $description "Reads an integer in a specific numerical base from the parser input." }
|
|
$parsing-note ;
|
|
|
|
HELP: parse-literal
|
|
{ $values { "accum" vector } { "end" word } { "quot" "a quotation with stack effect " { $snippet "( seq -- obj )" } } }
|
|
{ $description "Parses objects from parser input until " { $snippet "end" } ", applies the quotation to the resulting sequence, and adds the output value to the accumulator." }
|
|
{ $examples "This word is used to implement " { $link POSTPONE: C{ } "." }
|
|
$parsing-note ;
|
|
|
|
HELP: parse-definition
|
|
{ $values { "quot" "a new " { $link quotation } } }
|
|
{ $description "Parses objects from parser input until " { $link POSTPONE: ; } " and outputs a quotation with the results." }
|
|
{ $examples "This word is used to implement " { $link POSTPONE: : } "." }
|
|
$parsing-note ;
|
|
|
|
HELP: in-target
|
|
{ $values { "accum" vector } { "quot" "a quotation" } }
|
|
{ $description "If bootstrapping, adds the quotation to the parse tree to be run as a top-level form, otherwise calls the quotation immediately." } ;
|