basis/tools/crossref/crossref-docs.factor

   1 USING: help.markup help.syntax words definitions prettyprint
   2 tools.crossref.private math quotations assocs kernel sets ;
   3 IN: tools.crossref
   4
   5 ARTICLE: "tools.crossref" "Definition cross referencing"
   6 "Definitions can answer a sequence of definitions they directly depend on:"
   7 { $subsections uses }
   8 "An inverted index of the above:"
   9 { $subsections get-crossref }
  10 "Words to access it:"
  11 { $subsections
  12     usage
  13     smart-usage
  14 }
  15 "Tools for interactive use:"
  16 { $subsections
  17     usage.
  18     vocab-uses.
  19     vocab-usage.
  20 }
  21 { $see-also "definitions" "words" "see" } ;
  22
  23 ABOUT: "tools.crossref"
  24
  25 HELP: uses
  26 { $values { "defspec" "a definition specifier" } { "seq" "a sequence of definition specifiers" } }
  27 { $description "Outputs a sequence of definitions directory called by the given definition." }
  28 { $notes "The sequence might include the definition itself, if it is a recursive word." }
  29 { $examples
  30     "We can ask the " { $link sq } " word to produce a list of words it calls:"
  31     { $unchecked-example "\\ sq uses ." "{ dup * }" }
  32 } ;
  33
  34 HELP: crossref
  35 { $var-description "A graph whose vertices are definition specifiers and edges are usages. See " { $link "graphs" } ". This variable is reset to " { $link f } " every time a definition is added or removed. Call " { $link get-crossref } " to lazily construct the graph instead of using this variable directly." } ;
  36
  37 HELP: get-crossref
  38 { $values { "crossref" assoc } }
  39 { $description "Outputs the cross-referencing index, mapping definitions to usages, building it first if necessary." }
  40 { $notes "This word is used to implement " { $link usage } " and " { $link usage. } "." } ;
  41
  42 HELP: crossref-def
  43 { $values { "defspec" "a definition specifier" } }
  44 { $description "Adds a vertex representing this definition, along with edges representing dependencies to the " { $link crossref } " graph." }
  45 $low-level-note ;
  46
  47 HELP: usage
  48 { $values { "defspec" "a definition specifier" } { "seq" "a sequence of definition specifiers" } }
  49 { $description "Outputs a sequence of definitions that directly call the given definition." }
  50 { $notes "The sequence might include the definition itself, if it is a recursive word." } ;
  51
  52 HELP: usage.
  53 { $values { "word" "a word" } }
  54 { $description "Prints an list of all callers of a word. This may include the word itself, if it is recursive." }
  55 { $examples { $code "\\ reverse usage." } } ;
  56
  57 HELP: quot-uses
  58 { $values { "obj" object } { "set" "a " { $link set } " of words" } }
  59 { $description "Outputs a set of words referenced by the quotation and any quotations it contains." } ;
  60
  61 { usage usage. } related-words