core/compiler/units/units-docs.factor

   1 USING: help.markup help.syntax words math source-files
   2 parser quotations definitions ;
   3 IN: compiler.units
   4
   5 ARTICLE: "compilation-units" "Compilation units"
   6 "A " { $emphasis "compilation unit" } " scopes a group of related definitions. They are compiled and entered into the system in one atomic operation."
   7 $nl
   8 "Words defined in a compilation unit may not be called until the compilation unit is finished. The parser detects this case for parsing words and throws a " { $link staging-violation } "; calling any other word from within its own compilation unit throws an " { $link undefined } " error."
   9 $nl
  10 "The parser groups all definitions in a source file into one compilation unit, and parsing words do not need to concern themselves with compilation units. However, if definitions are being created at run time, a compilation unit must be created explicitly:"
  11 { $subsection with-compilation-unit }
  12 "Compiling a set of words:"
  13 { $subsection compile }
  14 "Words called to associate a definition with a compilation unit and a source file location:"
  15 { $subsection remember-definition }
  16 { $subsection remember-class }
  17 "Forward reference checking (see " { $link "definition-checking" } "):"
  18 { $subsection forward-reference? }
  19 "A hook to be called at the end of the compilation unit. If the optimizing compiler is loaded, this compiles new words with the " { $link "compiler" } ":"
  20 { $subsection recompile-hook }
  21 "Low-level compiler interface exported by the Factor VM:"
  22 { $subsection modify-code-heap } ;
  23
  24 ABOUT: "compilation-units"
  25
  26 HELP: redefine-error
  27 { $values { "definition" "a definition specifier" } }
  28 { $description "Throws a " { $link redefine-error } "." }
  29 { $error-description "Indicates that a single source file contains two definitions for the same artifact, one of which shadows the other. This is an error since it indicates a likely mistake, such as two words accidentally named the same by the developer; the error is restartable." } ;
  30
  31 HELP: remember-definition
  32 { $values { "definition" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
  33 { $description "Saves the location of a definition and associates this definition with the current source file." } ;
  34
  35 HELP: old-definitions
  36 { $var-description "Stores an assoc where the keys form the set of definitions which were defined by " { $link file } " the most recent time it was loaded." } ;
  37
  38 HELP: new-definitions
  39 { $var-description "Stores an assoc where the keys form the set of definitions which were defined so far by the current parsing of " { $link file } "." } ;
  40
  41 HELP: with-compilation-unit
  42 { $values { "quot" quotation } }
  43 { $description "Calls a quotation in a new compilation unit. The quotation can define new words and classes, as well as forget words. When the quotation returns, any changed words are recompiled, and changes are applied atomically." }
  44 { $notes "Compilation units may be nested."
  45 $nl
  46 "The parser wraps every source file in a compilation unit, so parsing words may define new words without having to perform extra work; to define new words at any other time, you must wrap your defining code with this combinator."
  47 $nl
  48 "Since compilation is relatively expensive, you should try to batch up as many definitions into one compilation unit as possible." } ;
  49
  50 HELP: recompile-hook
  51 { $var-description "Quotation with stack effect " { $snippet "( words -- )" } ", called at the end of " { $link with-compilation-unit } "." } ;
  52
  53 HELP: no-compilation-unit
  54 { $values { "word" word } }
  55 { $description "Throws a " { $link no-compilation-unit } " error." }
  56 { $error-description "Thrown when an attempt is made to define a word outside of a " { $link with-compilation-unit } " combinator." } ;
  57
  58 HELP: modify-code-heap ( alist -- )
  59 { $values { "alist" "an alist" } }
  60 { $description "Stores compiled code definitions in the code heap. The alist maps words to the following:"
  61 { $list
  62     { { $link f } " - in this case, the word is compiled with the non-optimizing compiler part of the VM." }
  63     { { $snippet "{ code labels rel words literals }" } " - in this case, a code heap block is allocated with the given data." }
  64 } }
  65 { $notes "This word is called at the end of " { $link with-compilation-unit } "." } ;
  66
  67 HELP: compile
  68 { $values { "words" "a sequence of words" } }
  69 { $description "Compiles a set of words." } ;
  70
  71 HELP: compile-call
  72 { $values { "quot" "a quotation" } }
  73 { $description "Compiles and runs a quotation." } ;