core/vocabs/loader/loader-docs.factor

   1 USING: vocabs vocabs.loader.private help.markup help.syntax
   2 words strings io ;
   3 IN: vocabs.loader
   4
   5 ARTICLE: "add-vocab-roots" "Working with code outside of the Factor source tree"
   6 "You can work with code outside of the Factor source tree by adding additional directories to the list of vocabulary roots."
   7 $nl
   8 "There are three ways of doing this."
   9 $nl
  10 "The first way is to use an environment variable. Factor looks at the " { $snippet "FACTOR_ROOTS" } " environment variable for a list of " { $snippet ":" } "-separated paths (on Unix) or a list of " { $snippet ";" } "-separated paths (on Windows)."
  11 $nl
  12 "The second way is to create a configuration file. You can list additional vocabulary roots in a file that Factor reads at startup:"
  13 { $subsection "factor-roots" }
  14 "Finally, you can add vocabulary roots dynamically using a word:"
  15 { $subsection add-vocab-root } ;
  16
  17 ARTICLE: "vocabs.roots" "Vocabulary roots"
  18 "The vocabulary loader searches for it in one of the root directories:"
  19 { $subsection vocab-roots }
  20 "The default set of roots includes the following directories in the Factor source directory:"
  21 { $list
  22     { { $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" } "." }
  23     { { $snippet "basis" } " - useful libraries and tools, such as " { $vocab-link "compiler" } ", " { $vocab-link "ui" } ", " { $vocab-link "calendar" } ", and so on." }
  24     { { $snippet "extra" } " - additional contributed libraries." }
  25     { { $snippet "work" } " - a root for vocabularies which are not intended to be contributed back to Factor." }
  26 }
  27 "You can store your own vocabularies in the " { $snippet "work" } " directory."
  28 { $subsection "add-vocab-roots" } ;
  29
  30 ARTICLE: "vocabs.loader" "Vocabulary loader"
  31 "The vocabulary loader is defined in the " { $vocab-link "vocabs.loader" } " vocabulary."
  32 $nl
  33 "Vocabularies are searched for in vocabulary roots."
  34 { $subsection "vocabs.roots" }
  35 "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."
  36 $nl
  37 "The vocabulary directory - " { $snippet "bar" } " in our example - contains a source file:"
  38 { $list
  39   { { $snippet "foo/bar/bar.factor" } " - the source file, must define words in the " { $snippet "foo.bar" } " vocabulary with an " { $snippet "IN: foo.bar" } " form" }
  40 }
  41 "Two other Factor source files, storing documentation and tests, respectively, are optional:"
  42 { $list
  43     { { $snippet "foo/bar/bar-docs.factor" } " - documentation, see " { $link "writing-help" } }
  44     { { $snippet "foo/bar/bar-tests.factor" } " - unit tests, see " { $link "tools.test" } }
  45 }
  46 "Finally, three text files can contain meta-data:"
  47 { $list
  48     { { $snippet "foo/bar/authors.txt" } " - a series of lines, with one author name per line. These are listed under " { $link "vocab-authors" } }
  49     { { $snippet "foo/bar/summary.txt" } " - a one-line description" }
  50     { { $snippet "foo/bar/tags.txt" } " - a whitespace-separated list of tags which classify the vocabulary. Consult " { $link "vocab-tags" } " for a list of existing tags you can re-use" }
  51 }
  52 "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:"
  53 { $subsection require }
  54 "Forcing a reload of a vocabulary, even if it has already been loaded:"
  55 { $subsection reload }
  56 "Application vocabularies can define a main entry point, giving the user a convenient way to run the application:"
  57 { $subsection POSTPONE: MAIN: }
  58 { $subsection run }
  59 { $subsection runnable-vocab }
  60 { $see-also "vocabularies" "parser-files" "source-files" } ;
  61
  62 ABOUT: "vocabs.loader"
  63
  64 HELP: load-vocab
  65 { $values { "name" "a string" } { "vocab" "a hashtable or " { $link f } } }
  66 { $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 } "." }
  67 { $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." } ;
  68
  69 HELP: vocab-main
  70 { $values { "vocab-spec" "a vocabulary specifier" } { "main" word } }
  71 { $description "Outputs the main entry point for a vocabulary. The entry point can be executed with " { $link run } " and set with " { $link POSTPONE: MAIN: } "." } ;
  72
  73 HELP: vocab-roots
  74 { $var-description "A sequence of pathname strings to search for vocabularies." } ;
  75
  76 HELP: add-vocab-root
  77 { $values { "root" "a pathname string" } }
  78 { $description "Adds a directory pathname to the list of vocabulary roots." }
  79 { $see-also "factor-roots" } ;
  80
  81 HELP: find-vocab-root
  82 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string" } }
  83 { $description "Searches for a vocabulary in the vocabulary roots." } ;
  84
  85 HELP: no-vocab
  86 { $values { "name" "a vocabulary name" } }
  87 { $description "Throws a " { $link no-vocab } "." }
  88 { $error-description "Thrown when a " { $link POSTPONE: USE: } " or " { $link POSTPONE: USING: } " form refers to a non-existent vocabulary." } ;
  89
  90 HELP: load-help?
  91 { $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." } ;
  92
  93 HELP: load-source
  94 { $values { "vocab" "a vocabulary specifier" } }
  95 { $description "Loads a vocabulary's source code." } ;
  96
  97 HELP: load-docs
  98 { $values { "vocab" "a vocabulary specifier" } }
  99 { $description "If " { $link load-help? } " is on, loads a vocabulary's documentation." } ;
 100
 101 HELP: reload
 102 { $values { "name" "a vocabulary name" } }
 103 { $description "Loads it's source code and documentation." }
 104 { $errors "Throws a " { $link no-vocab } " error if the vocabulary does not exist on disk." } ;
 105
 106 HELP: require
 107 { $values { "vocab" "a vocabulary specifier" } }
 108 { $description "Loads a vocabulary if it has not already been loaded." }
 109 { $notes "To unconditionally reload a vocabulary, use " { $link reload } ". To reload changed source files only, use the words in " { $link "vocabs.refresh" } "." } ;
 110
 111 HELP: run
 112 { $values { "vocab" "a vocabulary specifier" } }
 113 { $description "Runs a vocabulary's main entry point. The main entry point is set with the " { $link POSTPONE: MAIN: } " parsing word." } ;
 114
 115 HELP: vocab-source-path
 116 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
 117 { $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." } ;
 118
 119 HELP: vocab-docs-path
 120 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
 121 { $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." } ;