core/definitions/definitions-docs.factor

   1 USING: help.markup help.syntax words math source-files
   2 parser quotations compiler.units ;
   3 IN: definitions
   4
   5 ARTICLE: "definition-protocol" "Definition protocol"
   6 "A common protocol is used to build generic tools for working with all definitions."
   7 $nl
   8 "Definitions must know what source file they were loaded from, and provide a way to set this:"
   9 { $subsection where }
  10 { $subsection set-where }
  11 "Definitions can be removed:"
  12 { $subsection forget }
  13 "Definitions can answer a sequence of definitions they directly depend on:"
  14 { $subsection uses }
  15 "Definitions must implement a few operations used for printing them in source form:"
  16 { $subsection synopsis* }
  17 { $subsection definer }
  18 { $subsection definition } ;
  19
  20 ARTICLE: "definition-crossref" "Definition cross referencing"
  21 "A common cross-referencing system is used to track definition usages:"
  22 { $subsection crossref }
  23 { $subsection xref }
  24 { $subsection unxref }
  25 { $subsection delete-xref }
  26 { $subsection usage } ;
  27
  28 ARTICLE: "definition-checking" "Definition sanity checking"
  29 "When a source file is reloaded, the parser compares the previous list of definitions with the current list; any definitions which are no longer present in the file are removed by a call to " { $link forget } ". A warning message is printed if any other definitions still depend on the removed definitions."
  30 $nl
  31 "The parser also catches forward references when reloading source files. This is best illustrated with an example. Suppose we load a source file " { $snippet "a.factor" } ":"
  32 { $code
  33     "USING: io sequences ;"
  34     "IN: a"
  35     ": hello \"Hello\" ;"
  36     ": world \"world\" ;"
  37     ": hello-world hello " " world 3append print ;"
  38 }
  39 "The definitions for " { $snippet "hello" } ", " { $snippet "world" } ", and " { $snippet "hello-world" } " are in the dictionary."
  40 $nl
  41 "Now, after some heavily editing and refactoring, the file looks like this:"
  42 { $code
  43     "USING: namespaces ;"
  44     "IN: a"
  45     ": hello \"Hello\" % ;"
  46     ": hello-world [ hello " " % world ] \"\" make ;"
  47     ": world \"world\" % ;"
  48 }
  49 "Note that the developer has made a mistake, placing the definition of " { $snippet "world" } " " { $emphasis "after" } " its usage in " { $snippet "hello-world" } "."
  50 $nl
  51 "If the parser did not have special checks for this case, then the modified source file would still load, because when the definition of " { $snippet "hello-world" } " on line 4 is being parsed, the " { $snippet "world" } " word is already present in the dictionary from an earlier run. The developer would then not discover this mistake until attempting to load the source file into a fresh image."
  52 $nl
  53 "Since this is undesirable, the parser explicitly raises a " { $link no-word } " error if a source file refers to a word which is in the dictionary, but defined after it is used."
  54 $nl
  55 "The parser also catches duplicate definitions. If an artifact is defined twice in the same source file, the earlier definition will never be accessible, and this is almost always a mistake, perhaps due to a bad choice of word names, or a copy and paste error. The parser raises an error in this case."
  56 { $subsection redefine-error } ;
  57
  58 ARTICLE: "definitions" "Definitions"
  59 "A " { $emphasis "definition" } " is an artifact read from a source file. This includes words, methods, and help articles. Words for working with definitions are found in the " { $vocab-link "definitions" } " vocabulary. Implementations of the definition protocol include pathnames, words, methods, and help articles."
  60 { $subsection "definition-protocol" }
  61 { $subsection "definition-crossref" }
  62 { $subsection "definition-checking" }
  63 { $subsection "compilation-units" }
  64 { $see-also "parser" "source-files" "words" "generic" "help-impl" } ;
  65
  66 ABOUT: "definitions"
  67
  68 HELP: where
  69 { $values { "defspec" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
  70 { $description "Outputs the location of a definition. If the location is not known, will output " { $link f } "." } ;
  71
  72 HELP: set-where
  73 { $values { "loc" "a " { $snippet "{ path line# }" } " pair" } { "defspec" "a definition specifier" } }
  74 { $description "Sets the definition's location." }
  75 { $notes "This word is used by the parser." } ;
  76
  77 HELP: forget
  78 { $values { "defspec" "a definition specifier" } }
  79 { $description "Forgets about a definition. For example, if it is a word, it will be removed from its vocabulary." }
  80 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
  81
  82 HELP: forget-all
  83 { $values { "definitions" "a sequence of definition specifiers" } }
  84 { $description "Forgets every definition in a sequence." }
  85 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
  86
  87 HELP: uses
  88 { $values { "defspec" "a definition specifier" } { "seq" "a sequence of definition specifiers" } }
  89 { $description "Outputs a sequence of definitions directory called by the given definition." }
  90 { $notes "The sequence might include the definition itself, if it is a recursive word." }
  91 { $examples
  92     "We can ask the " { $link sq } " word to produce a list of words it calls:"
  93     { $unchecked-example "\ sq uses ." "{ dup * }" }
  94 } ;
  95
  96 HELP: crossref
  97 { $var-description "A graph whose vertices are definition specifiers and edges are usages. See " { $link "graphs" } "." } ;
  98
  99 HELP: xref
 100 { $values { "defspec" "a definition specifier" } }
 101 { $description "Adds a vertex representing this definition, along with edges representing dependencies to the " { $link crossref } " graph." }
 102 $low-level-note ;
 103
 104 HELP: usage
 105 { $values { "defspec" "a definition specifier" } { "seq" "a sequence of definition specifiers" } }
 106 { $description "Outputs a sequence of definitions that directly call the given definition." }
 107 { $notes "The sequence might include the definition itself, if it is a recursive word." } ;
 108
 109 HELP: unxref
 110 { $values { "defspec" "a definition specifier" } }
 111 { $description "Remove edges leaving the vertex which represents the definition from the " { $link crossref } " graph." }
 112 { $notes "This word is called before a word is redefined." } ;
 113
 114 HELP: delete-xref
 115 { $values { "defspec" "a definition specifier" } }
 116 { $description "Remove the vertex which represents the definition from the " { $link crossref } " graph." }
 117 { $notes "This word is called before a word is forgotten." }
 118 { $see-also forget } ;