core/definitions/definitions-docs.factor

   1 USING: compiler.units generic hash-sets help.markup help.syntax
   2 parser ;
   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 { $subsections
  10     where
  11     set-where
  12 }
  13 "Definitions can be removed:"
  14 { $subsections forget }
  15 "Definitions must implement a few operations used for printing them in source form:"
  16 { $subsections
  17     definer
  18     definition
  19 }
  20 { $see-also "see" } ;
  21
  22 ARTICLE: "definition-checking" "Definition sanity checking"
  23 "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 } "."
  24 $nl
  25 "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" } ":"
  26 { $code
  27     "USING: io sequences ;"
  28     "IN: a"
  29     ": hello ( -- str ) \"Hello\" ;"
  30     ": world ( -- str ) \"world\" ;"
  31     ": hello-world ( -- ) hello \" \" world 3append print ;"
  32 }
  33 "The definitions for " { $snippet "hello" } ", " { $snippet "world" } ", and " { $snippet "hello-world" } " are in the dictionary."
  34 $nl
  35 "Now, after some heavily editing and refactoring, the file looks like this:"
  36 { $code
  37     "USING: make ;"
  38     "IN: a"
  39     ": hello ( -- ) \"Hello\" % ;"
  40     ": hello-world ( -- str ) [ hello \" \" % world ] \"\" make ;"
  41     ": world ( -- ) \"world\" % ;"
  42 }
  43 "Note that the developer has made a mistake, placing the definition of " { $snippet "world" } " " { $emphasis "after" } " its usage in " { $snippet "hello-world" } "."
  44 $nl
  45 "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."
  46 $nl
  47 "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."
  48 $nl
  49 "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."
  50 { $subsections redefine-error } ;
  51
  52 ARTICLE: "definitions" "Definitions"
  53 "A " { $emphasis "definition" } " is an artifact read from a source file. Words for working with definitions are found in the " { $vocab-link "definitions" } " vocabulary."
  54 $nl
  55 "Definitions are defined using parsing words. Examples of definitions together with their defining parsing words are words (" { $link POSTPONE: : } "), methods (" { $link POSTPONE: M: } "), and vocabularies (" { $link POSTPONE: IN: } ")."
  56 $nl
  57 "All definitions share some common traits:"
  58 { $list
  59   "There is a word to list all definitions of a given type"
  60   "There is a parsing word for creating new definitions"
  61   "There is an ordinary word which is the runtime equivalent of the parsing word, for introspection"
  62   "Instances of the definition may be introspected and modified with the definition protocol"
  63 }
  64 "For every source file loaded into the system, a list of definitions is maintained. Pathname objects implement the definition protocol, acting over the definitions their source files contain. See " { $link "source-files" } " for details."
  65 { $subsections
  66     "definition-protocol"
  67     "definition-checking"
  68     "compilation-units"
  69 }
  70 "A parsing word to remove definitions:"
  71 { $subsections POSTPONE: FORGET: }
  72 { $see-also "see" "parser" "source-files" "words" "generic" "help-impl" } ;
  73
  74 ABOUT: "definitions"
  75
  76 HELP: changed-definition
  77 { $values { "defspec" "definition" } }
  78 { $description "Adds the definition to the unit's " { $link changed-definitions } "." } ;
  79
  80 HELP: changed-definitions
  81 { $var-description "A set that contains all words and vocabs whose definitions have changed or are new." }
  82 { $see-also changed-definition } ;
  83
  84 HELP: changed-effects
  85 { $var-description "A set that contains all words whose stack effects have changed in the compilation unit." } ;
  86
  87 HELP: forget
  88 { $values { "defspec" "a definition specifier" } }
  89 { $description "Forgets about a definition. For example, if it is a word, it will be removed from its vocabulary." }
  90 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
  91
  92 HELP: forget-all
  93 { $values { "definitions" { $sequence "definition specifiers" } } }
  94 { $description "Forgets every definition in a sequence." }
  95 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
  96
  97 HELP: maybe-changed
  98 { $var-description "The set of definitions that has maybe changed in the compilation unit. For example, if a union class is redefined it will be added to this set because it is possible but not certain that it has become different." } ;
  99
 100 HELP: outdated-generics
 101 { $var-description "A " { $link hash-set } " where newly defined generic words are kept until they are being remade." }
 102 { $see-also remake-generic remake-generics } ;
 103
 104 HELP: set-where
 105 { $values { "loc" "a " { $snippet "{ path line# }" } " pair" } { "defspec" "a definition specifier" } }
 106 { $description "Sets the definition's location." }
 107 { $notes "This word is used by the parser." } ;
 108
 109 HELP: where
 110 { $values { "defspec" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
 111 { $description "Outputs the location of a definition. If the location is not known, will output " { $link f } "." } ;