1 USING: vocabs help.markup help.syntax words strings io ;
4 ARTICLE: "vocabs.roots" "Vocabulary roots"
5 "The vocabulary loader searches for it in one of the root directories:"
6 { $subsection vocab-roots }
7 "The default set of roots includes the following directories in the Factor source directory:"
9 { { $snippet "core" } " - essential system vocabularies such as " { $vocab-link "parser" } " and " { $vocab-link "sequences" } ". The vocabularies in this root constitute the boot image; see " { $link "bootstrap.image" } "." }
10 { { $snippet "basis" } " - useful libraries and tools, such as " { $vocab-link "compiler" } ", " { $vocab-link "ui" } ", " { $vocab-link "calendar" } ", and so on." }
11 { { $snippet "extra" } " - additional contributed libraries." }
12 { { $snippet "work" } " - a root for vocabularies which are not intended to be contributed back to Factor." }
14 "Your own vocabularies should go into " { $snippet "extra" } " or " { $snippet "work" } ", depending on whether or not you intend to contribute them back to the Factor project. If you wish to work on vocabularies outside of the Factor source directory, create a " { $snippet "~/.factor-rc" } " file like the following,"
16 "USING: namespaces sequences vocabs.loader ;"
17 "\"/home/jane/sources/\" vocab-roots get push"
19 "See " { $link "rc-files" } " for details." ;
21 ARTICLE: "vocabs.loader" "Vocabulary loader"
22 "The vocabulary loader is defined in the " { $vocab-link "vocabs.loader" } " vocabulary."
24 "Vocabularies are searched for in vocabulary roots."
25 { $subsection "vocabs.roots" }
26 "Vocabulary names map directly to source files. A vocabulary named " { $snippet "foo.bar" } " must be defined in a " { $snippet "bar" } " directory nested inside a " { $snippet "foo" } " directory of a vocabulary root. Any level of vocabulary nesting is permitted."
28 "The vocabulary directory - " { $snippet "bar" } " in our example - can contain the following files; the first is required while the rest are optional:"
30 { { $snippet "foo/bar/bar.factor" } " - the source file, defines words in the " { $snippet "foo.bar" } " vocabulary" }
31 { { $snippet "foo/bar/bar-docs.factor" } " - documentation, see " { $link "writing-help" } }
32 { { $snippet "foo/bar/bar-tests.factor" } " - unit tests, see " { $link "tools.test" } }
33 { { $snippet "foo/bar/summary.txt" } " - a one-line description" }
34 { { $snippet "foo/bar/tags.txt" } " - a whitespace-separated list of tags which classify the vocabulary" }
36 "While " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " load vocabularies which have not been loaded before adding them to the search path, it is also possible to load a vocabulary without adding it to the search path:"
37 { $subsection require }
38 "Forcing a reload of a vocabulary, even if it has already been loaded:"
39 { $subsection reload }
40 "Application vocabularies can define a main entry point, giving the user a convenient way to run the application:"
41 { $subsection POSTPONE: MAIN: }
43 { $see-also "vocabularies" "parser-files" "source-files" } ;
45 ABOUT: "vocabs.loader"
48 { $values { "name" "a string" } { "vocab" "a hashtable or " { $link f } } }
49 { $description "Outputs a named vocabulary. If the vocabulary does not exist, throws a restartable " { $link no-vocab } " error. If the user invokes the restart, this word outputs " { $link f } "." }
50 { $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." } ;
53 { $values { "vocab-spec" "a vocabulary specifier" } { "main" word } }
54 { $description "Outputs the main entry point for a vocabulary. The entry point can be executed with " { $link run } " and set with " { $link POSTPONE: MAIN: } "." } ;
57 { $var-description "A sequence of pathname strings to search for vocabularies." } ;
60 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string" } }
61 { $description "Searches for a vocabulary in the vocabulary roots." } ;
64 { $values { "name" "a vocabulary name" } }
65 { $description "Throws a " { $link no-vocab } "." }
66 { $error-description "Thrown when a " { $link POSTPONE: USE: } " or " { $link POSTPONE: USING: } " form refers to a non-existent vocabulary." } ;
69 { $var-description "If set to a true value, documentation will be automatically loaded when vocabularies are loaded. This variable is usually on, except when Factor has been bootstrapped without the help system." } ;
72 { $values { "vocab" "a vocabulary specifier" } }
73 { $description "Loads a vocabulary's source code." } ;
76 { $values { "vocab" "a vocabulary specifier" } }
77 { $description "If " { $link load-help? } " is on, loads a vocabulary's documentation." } ;
80 { $values { "name" "a vocabulary name" } }
81 { $description "Loads it's source code and documentation." }
82 { $errors "Throws a " { $link no-vocab } " error if the vocabulary does not exist on disk." } ;
85 { $values { "vocab" "a vocabulary specifier" } }
86 { $description "Loads a vocabulary if it has not already been loaded." }
87 { $notes "To unconditionally reload a vocabulary, use " { $link reload } ". To reload changed source files only, use the words in " { $link "tools.vocabs" } "." } ;
90 { $values { "vocab" "a vocabulary specifier" } }
91 { $description "Runs a vocabulary's main entry point. The main entry point is set with the " { $link POSTPONE: MAIN: } " parsing word." } ;
93 HELP: vocab-source-path
94 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
95 { $description "Outputs a pathname where source code for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a directory on disk." } ;
98 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
99 { $description "Outputs a pathname where the documentation for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a directory on disk." } ;