basis/vocabs/metadata/metadata-docs.factor

   1 USING: help.markup help.syntax strings ;
   2 IN: vocabs.metadata
   3
   4 ARTICLE: "vocabs.metadata" "Vocabulary metadata"
   5 "Vocabulary directories can contain text files with metadata:"
   6 { $list
   7     { { $snippet "authors.txt" } " - a series of lines, with one author name per line. These are listed under " { $link "vocab-authors" } "." }
   8     { { $snippet "platforms.txt" } " - a series of lines, with one operating system name per line." }
   9     { { $snippet "resources.txt" } " - a series of lines, with one file glob pattern per line. Files inside the vocabulary directory whose names match any of these glob patterns will be included with the compiled application as " { $link "deploy-resources" } "." }
  10     { { $snippet "summary.txt" } " - a one-line description." }
  11     { { $snippet "tags.txt" } " - a series of lines, with one tag per line. Tags help classify the vocabulary. Consult " { $link "vocab-tags" } " for a list of existing tags you can reuse." }
  12 }
  13 "Words for reading and writing " { $snippet "summary.txt" } ":"
  14 { $subsections
  15     vocab-summary
  16     set-vocab-summary
  17 }
  18 "Words for reading and writing " { $snippet "authors.txt" } ":"
  19 { $subsections
  20     vocab-authors
  21     set-vocab-authors
  22 }
  23 "Words for reading and writing " { $snippet "tags.txt" } ":"
  24 { $subsections
  25     vocab-tags
  26     set-vocab-tags
  27     add-vocab-tags
  28 }
  29 "Words for reading and writing " { $snippet "platforms.txt" } ":"
  30 { $subsections
  31     vocab-platforms
  32     set-vocab-platforms
  33 }
  34 "Words for reading and writing " { $snippet "resources.txt" } ":"
  35 { $subsections
  36     vocab-resources
  37     set-vocab-resources
  38 }
  39 "Getting and setting arbitrary vocabulary metadata:"
  40 { $subsections
  41     vocab-file-contents
  42     set-vocab-file-contents
  43 } ;
  44
  45 ABOUT: "vocabs.metadata"
  46
  47 HELP: vocab-file-contents
  48 { $values { "vocab" "a vocabulary specifier" } { "name" string } { "seq" { $maybe "a sequence of lines" } } }
  49 { $description "Outputs the contents of the file named " { $snippet "name" } " from the vocabulary's directory, or " { $link f } " if the file does not exist." } ;
  50
  51 HELP: set-vocab-file-contents
  52 { $values { "seq" "a sequence of lines" } { "vocab" "a vocabulary specifier" } { "name" string } }
  53 { $description "Stores a sequence of lines to the file named " { $snippet "name" } " from the vocabulary's directory." } ;
  54
  55 HELP: vocab-summary
  56 { $values { "vocab" "a vocabulary specifier" } { "summary" { $maybe string } } }
  57 { $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." } ;
  58
  59 HELP: set-vocab-summary
  60 { $values { "string" { $maybe string } } { "vocab" "a vocabulary specifier" } }
  61 { $description "Stores a one-line string description of the vocabulary to the " { $snippet "summary.txt" } " file in the vocabulary's directory." } ;
  62
  63 HELP: vocab-tags
  64 { $values { "vocab" "a vocabulary specifier" } { "tags" "a sequence of strings" } }
  65 { $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." } ;
  66
  67 HELP: set-vocab-tags
  68 { $values { "tags" "a sequence of strings" } { "vocab" "a vocabulary specifier" } }
  69 { $description "Stores a list of short tags classifying the vocabulary to the " { $snippet "tags.txt" } " file in the vocabulary's directory." } ;
  70
  71 HELP: vocab-platforms
  72 { $values { "vocab" "a vocabulary specifier" } { "platforms" "a sequence of operating system symbols" } }
  73 { $description "Outputs a list of operating systems supported by " { $snippet "vocab" } ", as specified by the " { $snippet "platforms.txt" } " file in the vocabulary's directory. Outputs an empty array if the file doesn't exist." }
  74 { $notes "Operating system symbols are defined in the " { $vocab-link "system" } " vocabulary." } ;
  75
  76 HELP: set-vocab-platforms
  77 { $values { "platforms" "a sequence of operating system symbols" } { "vocab" "a vocabulary specifier" } }
  78 { $description "Stores a list of operating systems supported by " { $snippet "vocab" } " to the " { $snippet "platforms.txt" } " file in the vocabulary's directory." }
  79 { $notes "Operating system symbols are defined in the " { $vocab-link "system" } " vocabulary." } ;
  80
  81 HELP: vocab-resources
  82 { $values { "vocab" "a vocabulary specifier" } { "patterns" "a sequence of glob patterns" } }
  83 { $description "Outputs a list of glob patterns matching files that will be deployed with an application that includes " { $snippet "vocab" } ", as specified by the " { $snippet "resources.txt" } " file in the vocabulary's directory. Outputs an empty array if the file doesn't exist." }
  84 { $notes "The " { $vocab-link "vocabs.metadata.resources" } " vocabulary contains words that will expand the glob patterns and directory names in " { $snippet "patterns" } " and return all the matching files." } ;
  85
  86 HELP: set-vocab-resources
  87 { $values { "patterns" "a sequence of glob patterns" } { "vocab" "a vocabulary specifier" } }
  88 { $description "Stores a list of glob patterns matching files that will be deployed with an application that includes " { $snippet "vocab" } " to the " { $snippet "resources.txt" } " file in the vocabulary's directory." } ;