core/vocabs/vocabs-docs.factor

   1 USING: help.markup help.syntax strings words ;
   2 IN: vocabs
   3
   4 ARTICLE: "vocabularies" "Vocabularies"
   5 "A " { $emphasis "vocabulary" } " is a named collection of words. Vocabularies are defined in the " { $vocab-link "vocabs" } " vocabulary."
   6 $nl
   7 "Vocabularies are stored in a global hashtable:"
   8 { $subsection dictionary }
   9 "Vocabularies form a class."
  10 { $subsection vocab }
  11 { $subsection vocab? }
  12 "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 } ":"
  13 { $subsection vocab-link }
  14 { $subsection >vocab-link }
  15 "Looking up vocabularies by name:"
  16 { $subsection vocab }
  17 "Accessors for various vocabulary attributes:"
  18 { $subsection vocab-name }
  19 { $subsection vocab-root }
  20 { $subsection vocab-main }
  21 { $subsection vocab-help }
  22 "Looking up existing vocabularies and creating new vocabularies:"
  23 { $subsection vocab }
  24 { $subsection child-vocabs }
  25 { $subsection create-vocab }
  26 "Getting words from a vocabulary:"
  27 { $subsection vocab-words }
  28 { $subsection words }
  29 { $subsection all-words }
  30 { $subsection words-named }
  31 "Removing a vocabulary:"
  32 { $subsection forget-vocab }
  33 { $see-also "words" "vocabs.loader" } ;
  34
  35 ABOUT: "vocabularies"
  36
  37 HELP: dictionary
  38 { $var-description "Holds a hashtable mapping vocabulary names to vocabularies." } ;
  39
  40 HELP: vocabs
  41 { $values { "seq" "a sequence of strings" } }
  42 { $description "Outputs a sequence of all defined vocabulary names." } ;
  43
  44 HELP: vocab
  45 { $values { "name" string } { "vocab" vocab } }
  46 { $description "Outputs a named vocabulary, or " { $link f } " if no vocabulary with this name exists." }
  47 { $class-description "Instances represent vocabularies." } ;
  48
  49 HELP: vocab-name
  50 { $values { "vocab" "a vocabulary specifier" } { "name" string } }
  51 { $description "Outputs the name of a vocabulary." } ;
  52
  53 HELP: vocab-root
  54 { $values { "vocab" "a vocabulary specifier" } { "root" "a pathname string or " { $link f } } }
  55 { $description "Outputs the vocabulary root where the source code for a vocabulary is located, or " { $link f } " if the vocabulary is not defined in source files." } ;
  56
  57 HELP: vocab-words
  58 { $values { "vocab" "a vocabulary specifier" } { "words" "an assoc mapping strings to words" } }
  59 { $description "Outputs the words defined in a vocabulary." } ;
  60
  61 HELP: vocab-source-loaded?
  62 { $values { "vocab" "a vocabulary specifier" } { "source-loaded?" "a boolean" } }
  63 { $description "Outputs if the source for this vocubulary has been loaded." } ;
  64
  65 HELP: vocab-docs-loaded?
  66 { $values { "vocab" "a vocabulary specifier" } { "docs-loaded?" "a boolean" } }
  67 { $description "Outputs if the documentation for this vocubulary has been loaded." } ;
  68
  69 HELP: words
  70 { $values { "vocab" string } { "seq" "a sequence of words" } }
  71 { $description "Outputs a sequence of words defined in the vocabulary, or " { $link f } " if no vocabulary with this name exists." } ;
  72
  73 HELP: all-words
  74 { $values { "seq" "a sequence of words" } }
  75 { $description "Outputs a sequence of all words in the dictionary." } ;
  76
  77 HELP: forget-vocab
  78 { $values { "vocab" string } }
  79 { $description "Removes a vocabulary. All words in the vocabulary become uninterned." } ;
  80
  81 HELP: load-vocab-hook
  82 { $var-description "a quotation with stack effect " { $snippet "( name -- vocab )" } " which loads a vocabulary. This quotation is called by " { $link load-vocab } ". The default value should not need to be changed; this functinality 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" } "." } ;
  83
  84 HELP: words-named
  85 { $values { "str" string } { "seq" "a sequence of words" } }
  86 { $description "Outputs a sequence of all words named " { $snippet "str" } " from the set of currently-loaded vocabularies." } ;
  87
  88 HELP: create-vocab
  89 { $values { "name" string } { "vocab" vocab } }
  90 { $description "Creates a new vocabulary if one does not exist with the given name, otherwise outputs an existing vocabulary." } ;
  91
  92 HELP: child-vocabs
  93 { $values { "vocab" "a vocabulary specifier" } { "seq" "a sequence of strings" } }
  94 { $description "Outputs all vocabularies which are conceptually under " { $snippet "vocab" } " in the hierarchy." }
  95 { $examples
  96     { $unchecked-example
  97         "\"io.streams\" child-vocabs ."
  98         "{\n    \"io.streams.c\"\n    \"io.streams.duplex\"\n    \"io.streams.lines\"\n    \"io.streams.nested\"\n    \"io.streams.plain\"\n    \"io.streams.string\"\n}"
  99     }
 100 } ;
 101
 102 HELP: vocab-link
 103 { $class-description "Instances of this class identify vocabularies which are potentially not loaded. The " { $link vocab-name } " slot is the vocabulary name, and " { $link vocab-root } " is a pathname string identifying the vocabulary root where the sources to this vocabulary are located, or " { $link f } " if the root is not known."
 104 $nl
 105 "Vocabulary links are created by calling " { $link >vocab-link } "."
 106 } ;
 107
 108 HELP: >vocab-link
 109 { $values { "name" string } { "root" "a pathname string or " { $link f } } { "vocab" "a vocabulary specifier" } }
 110 { $description "If the vocabulary is loaded, outputs the corresponding " { $link vocab } " instance, otherwise creates a new " { $link vocab-link } "." } ;