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 { $subsections ".factor-roots" }
  14 "Finally, you can add vocabulary roots by calling a word from your " { $snippet ".factor-rc" } " file (see " { $link ".factor-rc" } "):"
  15 { $subsections add-vocab-root } ;
  16
  17 ARTICLE: "vocabs.roots" "Vocabulary roots"
  18 "The vocabulary loader searches for vocabularies in one of the root directories:"
  19 { $subsections 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 { $subsections "add-vocab-roots" } ;
  29
  30 ARTICLE: "vocabs.icons" "Vocabulary icons"
  31 "An icon file representing the vocabulary can be provided for use by " { $link "tools.deploy" } ". If any of the following files exist inside the vocabulary directory, they will be used as icons when the application is deployed."
  32 { $list
  33     { { $snippet "icon.ico" } " on Windows" }
  34     { { $snippet "icon.icns" } " on MacOS X" }
  35     { { $snippet "icon.png" } " on Linux and *BSD" }
  36 } ;
  37
  38 ARTICLE: "vocabs.loader" "Vocabulary loader"
  39 "The " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " words load vocabularies using the vocabulary loader. The vocabulary loader is implemented in the " { $vocab-link "vocabs.loader" } " vocabulary."
  40 $nl
  41 "The vocabulary loader searches for vocabularies in a set of directories known as vocabulary roots."
  42 { $subsections "vocabs.roots" }
  43 "Vocabulary names map directly to source files inside these roots. A vocabulary named " { $snippet "foo.bar" } " is defined in " { $snippet "foo/bar/bar.factor" } "; that is, a source file named " { $snippet "bar.factor" } " within a " { $snippet "bar" } " directory nested inside a " { $snippet "foo" } " directory of a vocabulary root. Any level of nesting, separated by dots, is permitted."
  44 $nl
  45 "The vocabulary directory - " { $snippet "bar" } " in our example - contains a source file:"
  46 { $list
  47   { { $snippet "foo/bar/bar.factor" } " - the source file must define words in the " { $snippet "foo.bar" } " vocabulary with an " { $snippet "IN: foo.bar" } " form" }
  48 }
  49 "Two other Factor source files, storing documentation and tests, respectively, may optionally be placed alongside the source file:"
  50 { $list
  51     { { $snippet "foo/bar/bar-docs.factor" } " - documentation, see " { $link "writing-help" } }
  52     { { $snippet "foo/bar/bar-tests.factor" } " - unit tests, see " { $link "tools.test" } }
  53 }
  54 "Optional text files may contain metadata."
  55 { $subsections "vocabs.metadata" "vocabs.icons" }
  56 "Vocabularies can also be loaded at run time, without altering the vocabulary search path. This is done by calling a word which loads a vocabulary if it is not in the image, doing nothing if it is:"
  57 { $subsections require }
  58 "The above word will only ever load a vocabulary once in a given session. Sometimes, two vocabularies require special code to interact. The following word is used to load one vocabulary when another is present:"
  59 { $subsections require-when }
  60 "There is another word which unconditionally loads vocabulary from disk, regardless of whether or not is has already been loaded:"
  61 { $subsections reload }
  62 "For interactive development in the listener, calling " { $link reload } " directly is usually not necessary, since a better facility exists for " { $link "vocabs.refresh" } "."
  63 $nl
  64 "Application vocabularies can define a main entry point, giving the user a convenient way to run the application:"
  65 { $subsections
  66     POSTPONE: MAIN:
  67     run
  68     runnable-vocab
  69 }
  70 { $see-also "vocabularies" "parser" "source-files" } ;
  71
  72 ABOUT: "vocabs.loader"
  73
  74 HELP: load-vocab
  75 { $values { "name" "a string" } { "vocab" "a hashtable or " { $link f } } }
  76 { $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 } "." }
  77 { $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." } ;
  78
  79 HELP: vocab-main
  80 { $values { "vocab-spec" "a vocabulary specifier" } { "main" word } }
  81 { $description "Outputs the main entry point for a vocabulary. The entry point can be executed with " { $link run } " and set with " { $link POSTPONE: MAIN: } "." } ;
  82
  83 HELP: vocab-roots
  84 { $var-description "A sequence of pathname strings to search for vocabularies." } ;
  85
  86 HELP: add-vocab-root
  87 { $values { "root" "a pathname string" } }
  88 { $description "Adds a directory pathname to the list of vocabulary roots." }
  89 { $see-also ".factor-roots" } ;
  90
  91 HELP: find-vocab-root
  92 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string" } }
  93 { $description "Searches for a vocabulary in the vocabulary roots." } ;
  94
  95 HELP: no-vocab
  96 { $values { "name" "a vocabulary name" } }
  97 { $description "Throws a " { $link no-vocab } "." }
  98 { $error-description "Thrown when a " { $link POSTPONE: USE: } " or " { $link POSTPONE: USING: } " form refers to a non-existent vocabulary." } ;
  99
 100 HELP: load-help?
 101 { $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." } ;
 102
 103 HELP: load-source
 104 { $values { "vocab" "a vocabulary specifier" } }
 105 { $description "Loads a vocabulary's source code." } ;
 106
 107 HELP: load-docs
 108 { $values { "vocab" "a vocabulary specifier" } }
 109 { $description "If " { $link load-help? } " is on, loads a vocabulary's documentation." } ;
 110
 111 HELP: reload
 112 { $values { "name" "a vocabulary name" } }
 113 { $description "Reloads the source code and documentation for a vocabulary." }
 114 { $errors "Throws a " { $link no-vocab } " error if the vocabulary does not exist on disk." } ;
 115
 116 HELP: require
 117 { $values { "vocab" "a vocabulary specifier" } }
 118 { $description "Loads a vocabulary if it has not already been loaded." }
 119 { $notes "To unconditionally reload a vocabulary, use " { $link reload } ". To reload changed source files only, use the words in " { $link "vocabs.refresh" } "." } ;
 120
 121 HELP: require-when
 122 { $values { "if" "a sequence of vocabulary specifiers" } { "then" "a vocabulary specifier" } }
 123 { $description "Loads the " { $snippet "then" } " vocabulary if it is not loaded and all of the " { $snippet "if" } " vocabulary is. If some of the " { $snippet "if" } " vocabularies are not loaded now, but they are later, then the " { $snippet "then" } " vocabulary will be loaded along with the final one." }
 124 { $notes "This is used to express a joint dependency of vocabularies. If vocabularies " { $snippet "a" } " and " { $snippet "b" } " use code in vocabulary " { $snippet "c" } " to interact, then the following line, which can be placed in " { $snippet "a" } " or " { $snippet "b" } ", expresses the dependency."
 125 { $code "{ \"a\" \"b\" } \"c\" require-when" } } ;
 126
 127 HELP: run
 128 { $values { "vocab" "a vocabulary specifier" } }
 129 { $description "Runs a vocabulary's main entry point. The main entry point is set with the " { $link POSTPONE: MAIN: } " parsing word." } ;
 130
 131 HELP: vocab-source-path
 132 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
 133 { $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." } ;
 134
 135 HELP: vocab-docs-path
 136 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
 137 { $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." } ;