USING: help io parser definitions ;

HELP: file-vocabs
{ $description "Installs the initial the vocabulary search path for parsing a file." } ;

HELP: parse-lines
{ $values { "lines" "a sequence of strings" } { "quot" "a new quotation" } }
{ $description "Parses the Factor source code which has been tokenized into lines. The vocabulary search path is taken from the current scope." }
{ $errors "Throws a parse error if the input is malformed." } ;

HELP: with-parser
{ $values { "quot" "a quotation" } }
{ $description "Calls a quotation, wrapping any errors thrown inside parse errors." } ;

HELP: parse
{ $values { "str" "a string" } { "quot" "a new quotation" } }
{ $description "Parses Factor source code from a string. The current vocabulary search path is used." }
{ $errors "Throws a parse error if the input is malformed." } ;

HELP: eval
{ $values { "str" "a string" } }
{ $description "Parses Factor source code from a string, and calls the resulting quotation. The current vocabulary search path is used." }
{ $errors "Throws an error if the input is malformed, or if the quotation throws an error." } ;

HELP: parse-hook
{ $var-description "A quotation called by " { $link parse-stream } " after parsing the input stream. The default value recompiles new word definitions; see " { $link "recompile" } " for details." }
{ $see-also no-parse-hook } ;

HELP: no-parse-hook
{ $values { "quot" "a quotation" } }
{ $description "Runs the quotation in a new dynamic scope where " { $link parse-hook } " is set to " { $link f } ". This disables the default behavior of recompiling changed definitions after a source file is loaded." } ;

HELP: parse-stream
{ $values { "stream" "an input stream" } { "name" "a file name for error reporting" } { "quot" "a new quotation" } }
{ $description "Parses Factor source code read from the stream. The initial vocabulary search path is used." }
{ $errors "Throws an I/O error if there was an error reading from the stream. Throws a parse error if the input is malformed." } ;

HELP: parse-file
{ $values { "file" "a path name string" } { "quot" "a new quotation" } }
{ $description "Parses the Factor source code stored in a file. The initial vocabulary search path is used." }
{ $errors "Throws an I/O error if there was an error reading from the file. Throws a parse error if the input is malformed." } ;

HELP: run-file
{ $values { "file" "a path name string" } }
{ $description "Parses the Factor source code stored in a file and runs it. The initial vocabulary search path is used." }
{ $errors "Throws an error if loading the file fails, there input is malformed, or if a runtime error occurs while calling the parsed quotation." }  ;

HELP: ?run-file
{ $values { "file" "a path name string" } }
{ $description "Forgiving variant of " { $link run-file } " which does nothing if the file does not exist, and logs errors to the default stream without re-throwing them." }  ;

HELP: parse-resource
{ $values { "path" "a resource name string" } { "quot" "a new quotation" } }
{ $description "Parses a library resource." }
{ $notes "the source file name given to the parser is special for resources and begins with " { $snippet "resource:" } ". This allows words that operate on source files, like " { $link edit } ", to use a different resource path at run time than was used at parse time." }
{ $errors "Throws an I/O error if there was an error reading the resource. Throws a parse error if the input is malformed." } ;

HELP: run-resource
{ $values { "path" "a resource name string" } }
{ $description "Parses and runs a library resource." }
{ $errors "Throws an I/O error if there was an error reading the resource. Throws a parse error if the input is malformed." } ;