core/vocabs/vocabs-docs.factor

   1 USING: help.markup help.syntax strings words compiler.units
   2 vocabs.loader ;
   3 IN: vocabs
   4
   5 ARTICLE: "vocabularies" "Vocabularies"
   6 "A " { $emphasis "vocabulary" } " is a named collection of " { $link "words" } ". Vocabularies are defined in the " { $vocab-link "vocabs" } " vocabulary."
   7 $nl
   8 "Vocabularies are stored in a global hashtable:"
   9 { $subsections dictionary }
  10 "Vocabularies form a class."
  11 { $subsections
  12     vocab
  13     vocab?
  14 }
  15 "Various vocabulary words are overloaded to accept a " { $emphasis "vocabulary specifier" } ", which is a string naming the vocabulary, the " { $link vocab } " instance itself, or a " { $link vocab-link } ":"
  16 { $subsections
  17     vocab-link
  18     >vocab-link
  19 }
  20 "Looking up vocabularies by name:"
  21 { $subsections vocab }
  22 "Accessors for various vocabulary attributes:"
  23 { $subsections
  24     vocab-name
  25     vocab-main
  26     vocab-help
  27 }
  28 "Looking up existing vocabularies and creating new vocabularies:"
  29 { $subsections
  30     lookup-vocab
  31     child-vocabs
  32     create-vocab
  33 }
  34 "Getting words from a vocabulary:"
  35 { $subsections
  36     vocab-words
  37     words
  38     all-words
  39     words-named
  40 }
  41 "Removing a vocabulary:"
  42 { $subsections forget-vocab }
  43 { $see-also "words" "vocabs.loader" "word-search" } ;
  44
  45 ABOUT: "vocabularies"
  46
  47 HELP: dictionary
  48 { $var-description "Holds a hashtable mapping vocabulary names to vocabularies." } ;
  49
  50 HELP: vocabs
  51 { $values { "seq" "a sequence of strings" } }
  52 { $description "Outputs a sequence of all defined vocabulary names." } ;
  53
  54 HELP: lookup-vocab
  55 { $values { "vocab-spec" "a vocabulary specifier" } { "vocab" vocab } }
  56 { $description "Outputs a named vocabulary, or " { $link f } " if no vocabulary with this name exists." }
  57 { $class-description "Instances represent vocabularies." } ;
  58
  59 HELP: vocab-name
  60 { $values { "vocab-spec" "a vocabulary specifier" } { "name" string } }
  61 { $description "Outputs the name of a vocabulary." } ;
  62
  63 HELP: vocab-words
  64 { $values { "vocab-spec" "a vocabulary specifier" } { "words" "an assoc mapping strings to words" } }
  65 { $description "Outputs the words defined in a vocabulary." } ;
  66
  67 HELP: words
  68 { $values { "vocab" string } { "seq" "a sequence of words" } }
  69 { $description "Outputs a sequence of words defined in the vocabulary, or " { $link f } " if no vocabulary with this name exists." } ;
  70
  71 HELP: all-words
  72 { $values { "seq" "a sequence of words" } }
  73 { $description "Outputs a sequence of all words in the dictionary." } ;
  74
  75 HELP: forget-vocab
  76 { $values { "vocab" string } }
  77 { $description "Removes a vocabulary. All words in the vocabulary are forgotten." }
  78 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
  79
  80 HELP: require-hook
  81 { $var-description { $quotation "( name -- )" } " which loads a vocabulary. This quotation is called by " { $link require } ". The default value should not need to be changed; this functionality is implemented via a hook stored in a variable to break a circular dependency which would otherwise exist from " { $vocab-link "vocabs" } " to " { $vocab-link "vocabs.loader" } " to " { $vocab-link "parser" } " back to " { $vocab-link "vocabs" } "." } ;
  82
  83 HELP: require
  84 { $values { "object" "a vocabulary specifier" } }
  85 { $description "Loads a vocabulary if it has not already been loaded. Throws an error if the vocabulary does not exist on disk or in the dictionary." }
  86 { $notes "To unconditionally reload a vocabulary, use " { $link reload } ". To reload changed source files only, use the words in " { $link "vocabs.refresh" } "." } ;
  87
  88 HELP: words-named
  89 { $values { "str" string } { "seq" "a sequence of words" } }
  90 { $description "Outputs a sequence of all words named " { $snippet "str" } " from the set of currently-loaded vocabularies." } ;
  91
  92 HELP: create-vocab
  93 { $values { "name" string } { "vocab" vocab } }
  94 { $description "Creates a new vocabulary if one does not exist with the given name, otherwise outputs an existing vocabulary." } ;
  95
  96 HELP: child-vocabs
  97 { $values { "vocab" "a vocabulary specifier" } { "seq" "a sequence of strings" } }
  98 { $description "Outputs all vocabularies which are conceptually under " { $snippet "vocab" } " in the hierarchy." }
  99 { $examples
 100     { $unchecked-example
 101         "\"io.streams\" child-vocabs ."
 102         "{ \"io.streams.c\" \"io.streams.duplex\" \"io.streams.lines\" \"io.streams.nested\" \"io.streams.plain\" \"io.streams.string\" }"
 103     }
 104 } ;
 105
 106 HELP: vocab-link
 107 { $class-description "Instances of this class identify vocabularies which are potentially not loaded. The " { $link vocab-name } " slot is the vocabulary name."
 108 $nl
 109 "Vocabulary links are created by calling " { $link >vocab-link } "."
 110 } ;
 111
 112 HELP: >vocab-link
 113 { $values { "name" string } { "vocab" "a vocabulary specifier" } }
 114 { $description "If the vocabulary is loaded, outputs the corresponding " { $link vocab } " instance, otherwise creates a new " { $link vocab-link } "." } ;
 115
 116 HELP: runnable-vocab
 117 { $class-description "The class of vocabularies with a " { $slot "main" } " word." } ;