basis/tools/vocabs/vocabs-docs.factor

   1 USING: help.markup help.syntax strings ;\r
   2 IN: tools.vocabs\r
   3 \r
   4 ARTICLE: "tools.vocabs" "Vocabulary tools"\r
   5 "Reloading source files changed on disk:"\r
   6 { $subsection refresh }\r
   7 { $subsection refresh-all }\r
   8 "Vocabulary summaries:"\r
   9 { $subsection vocab-summary }\r
  10 { $subsection set-vocab-summary }\r
  11 "Vocabulary tags:"\r
  12 { $subsection vocab-tags }\r
  13 { $subsection set-vocab-tags }\r
  14 { $subsection add-vocab-tags }\r
  15 "Getting and setting vocabulary meta-data:"\r
  16 { $subsection vocab-file-contents }\r
  17 { $subsection set-vocab-file-contents }\r
  18 "Global meta-data:"\r
  19 { $subsection all-vocabs }\r
  20 { $subsection all-vocabs-seq }\r
  21 { $subsection all-tags }\r
  22 { $subsection all-authors }\r
  23 "Because loading the above data is expensive, it is cached. The cache is flushed by the " { $vocab-link "tools.vocabs.monitor" } " vocabulary. It can also be flushed manually when file system change monitors are not available:"\r
  24 { $subsection reset-cache } ;\r
  25 \r
  26 ABOUT: "tools.vocabs"\r
  27 \r
  28 HELP: vocab-files\r
  29 { $values { "vocab" "a vocabulary specifier" } { "seq" "a sequence of pathname strings" } }\r
  30 { $description "Outputs a sequence of files comprising this vocabulary, or " { $link f } " if the vocabulary does not have a directory on disk." } ;\r
  31 \r
  32 HELP: vocab-tests\r
  33 { $values { "vocab" "a vocabulary specifier" } { "tests" "a sequence of pathname strings" } }\r
  34 { $description "Outputs a sequence of pathnames where the unit tests for " { $snippet "vocab" } " are located." } ;\r
  35 \r
  36 HELP: source-modified?\r
  37 { $values { "path" "a pathname string" } { "?" "a boolean" } }\r
  38 { $description "Tests if the source file has been modified since it was last loaded. This compares the file's CRC32 checksum of the file's contents against the previously-recorded value." } ;\r
  39 \r
  40 HELP: refresh\r
  41 { $values { "prefix" string } }\r
  42 { $description "Reloads source files and documentation belonging to loaded vocabularies whose names are prefixed by " { $snippet "prefix" } " which have been modified on disk." } ;\r
  43 \r
  44 HELP: refresh-all\r
  45 { $description "Reloads source files and documentation for all loaded vocabularies which have been modified on disk." } ;\r
  46 \r
  47 { refresh refresh-all } related-words\r
  48 \r
  49 HELP: vocab-file-contents\r
  50 { $values { "vocab" "a vocabulary specifier" } { "name" string } { "seq" "a sequence of lines, or " { $link f } } }\r
  51 { $description "Outputs the contents of the file named " { $snippet "name" } " from the vocabulary's directory, or " { $link f } " if the file does not exist." } ;\r
  52 \r
  53 HELP: set-vocab-file-contents\r
  54 { $values { "seq" "a sequence of lines" } { "vocab" "a vocabulary specifier" } { "name" string } }\r
  55 { $description "Stores a sequence of lines to the file named " { $snippet "name" } " from the vocabulary's directory." } ;\r
  56 \r
  57 HELP: vocab-summary\r
  58 { $values { "vocab" "a vocabulary specifier" } { "summary" "a string or " { $link f } } }\r
  59 { $description "Outputs a one-line string description of the vocabulary's intended purpose from the " { $snippet "summary.txt" } " file in the vocabulary's directory. Outputs " { $link f } " if the file does not exist." } ;\r
  60 \r
  61 HELP: set-vocab-summary\r
  62 { $values { "string" "a string or " { $link f } } { "vocab" "a vocabulary specifier" } }\r
  63 { $description "Stores a one-line string description of the vocabulary to the " { $snippet "summary.txt" } " file in the vocabulary's directory." } ;\r
  64 \r
  65 HELP: vocab-tags\r
  66 { $values { "vocab" "a vocabulary specifier" } { "tags" "a sequence of strings" } }\r
  67 { $description "Outputs a list of short tags classifying the vocabulary from the " { $snippet "tags.txt" } " file in the vocabulary's directory. Outputs " { $link f } " if the file does not exist." } ;\r
  68 \r
  69 HELP: set-vocab-tags\r
  70 { $values { "tags" "a sequence of strings" } { "vocab" "a vocabulary specifier" } }\r
  71 { $description "Stores a list of short tags classifying the vocabulary to the " { $snippet "tags.txt" } " file in the vocabulary's directory." } ;\r
  72 \r
  73 HELP: all-vocabs\r
  74 { $values { "assoc" "an association list mapping vocabulary roots to sequences of vocabulary specifiers" } }\r
  75 { $description "Outputs an association list of all vocabularies which have been loaded or are available for loading." } ;\r