core/handbook/words.facts

   1 USING: definitions help kernel parser words ;
   2
   3 ARTICLE: "words" "Words"
   4 "Words are the fundamental unit of code in Factor, analogous to functions or procedures in other languages. Words are also objects, and this concept forms the basis for Factor's meta-programming facilities. A word consists of several parts:"
   5 { $list
   6     "a word name,"
   7     "a vocabulary name,"
   8     "a definition, specifying the behavior of the word when executed,"
   9     "a set of word properties, including documentation and other meta-data."
  10 }
  11 "Words for working with words are in the " { $vocab-link "words" } " vocabulary."
  12 { $subsection "vocabularies" }
  13 { $subsection "word-definition" }
  14 { $subsection "word-crossref" }
  15 { $subsection "word-internals" } ;
  16
  17 ARTICLE: "vocabularies" "Vocabularies"
  18 "Words are organized into named vocabularies, stored in a global variable."
  19 { $subsection vocabularies }
  20 "A word is said to be " { $emphasis "interned" } " if it is a member of the vocabulary named by its vocabulary slot. Otherwise, the word is " { $emphasis "uninterned" } "."
  21 $terpri
  22 "Words whose names are known at parse time -- that is, most words making up your program -- can be referenced in source code by stating their name. However, the parser itself, and sometimes code you write, will need to create look up words dynamically."
  23 $terpri
  24 "Parsing words add definitions to the current vocabulary. When a source file is being parsed, the current vocabulary is initially set to " { $vocab-link "scratchpad" } ". The current vocabulary may be changed with the " { $link POSTPONE: IN: } " parsing word (see " { $link "vocabulary-search" } ")."
  25 { $subsection create }
  26 { $subsection create-in }
  27 { $subsection gensym }
  28 { $subsection lookup }
  29 "Words can output their name and vocabulary:"
  30 { $subsection word-name }
  31 { $subsection word-vocabulary } ;
  32
  33 ARTICLE: "word-definition" "Defining words"
  34 "There are two approaches to creating word definitions:"
  35 { $list
  36     "using parsing words at parse time,"
  37     "using defining words at run-time."
  38 }
  39 "The latter is a more dynamic feature that can be used to implement code generation and such, and in fact parse-time defining words are implemented in terms of run-time defining words."
  40 { $subsection "colon-definition" }
  41 { $subsection "symbols" }
  42 { $subsection "primitives" }
  43 { $subsection "deferred" }
  44 { $subsection "undefining" }
  45 { $subsection "declarations" } ;
  46
  47 ARTICLE: "colon-definition" "Compound definitions"
  48 "A compound definition associates a word name with a quotation that is called when the word is executed."
  49 { $subsection POSTPONE: : }
  50 { $subsection define-compound }
  51 { $subsection compound? }
  52 { $subsection compound }
  53 "Colon definitions should declare their stack effect, unless the definition is completely trivial. See " { $link "effect-declaration" } "." ;
  54
  55 ARTICLE: "symbols" "Symbols"
  56 { $subsection POSTPONE: SYMBOL: }
  57 { $subsection define-symbol }
  58 { $subsection symbol? }
  59 { $subsection symbol } ;
  60
  61 ARTICLE: "primitives" "Primitives"
  62 "Executing a primitive invokes native code in the Factor runtime. Primitives cannot be defined through Factor code. Compiled definitions behave similarly to primitives in that the interpreter jumps to native code upon encountering them."
  63 { $subsection primitive? }
  64 { $subsection primitive } ;
  65
  66 ARTICLE: "deferred" "Deferred words and mutual recursion"
  67 { $subsection POSTPONE: DEFER: }
  68 { $subsection undefined? }
  69 { $subsection undefined } ;
  70
  71 ARTICLE: "undefining" "Undefining words"
  72 { $subsection POSTPONE: FORGET: }
  73 { $subsection forget }
  74 { $subsection interned? } ;
  75
  76 ARTICLE: "declarations" "Declarations"
  77 "Declarations give special behavior to a word. Declarations are parsing words that set a word property in the most recently defined word."
  78 $terpri
  79 "The first declaration specifies the time when a word runs. It affects both interpreted and compiled definitions."
  80 { $subsection POSTPONE: parsing }
  81 "The remaining declarations only affect compiled definitions. They do not change evaluation semantics of a word, but instead declare that the word follows a certain contract, and thus may be compiled differently."
  82 { $warning "If a generic word is declared " { $link POSTPONE: foldable } ", all methods must satisfy the contract, otherwise unpredicable behavior will occur." }
  83 { $subsection POSTPONE: inline }
  84 { $subsection POSTPONE: foldable }
  85 "Stack effect declarations are documented in " { $link "effect-declaration" } "." ;
  86
  87 ARTICLE: "word-props" "Word properties"
  88 "Each word has a hashtable of properties."
  89 { $subsection word-prop }
  90 { $subsection set-word-prop }
  91 { $subsection word-props }
  92 { $subsection set-word-props }
  93 "The stack effect of the above two words is designed so that it is most convenient when " { $snippet "name" } " is a literal pushed on the stack right before executing this word."
  94 $terpri
  95 "The following properties are set by the library:"
  96 { $list
  97     { { $snippet "\"parsing\"" } ", " { $snippet "\"inline\"" } ", " { $snippet "\"foldable\"" } " - declarations (see " { $link "declarations" } ")" }
  98     { { $snippet "\"file\"" } " - the source file storing the word definition" }
  99     { { $snippet "\"line\"" } " - the line number in the source file storing the word definition" }
 100     { { $snippet "\"methods\"" } ", " { $snippet "\"combination\"" } " - only defined on generic words (see " { $link "generic" } ")" }
 101     { { $snippet "\"predicate\"" } " - only defined on class words, stores a quotation that tests if the top of the stack is an instance of that class" }
 102     { { $snippet "\"predicating\"" } " - only defined on class predicate words, stores the corresponding class word" }
 103 } ;
 104
 105 ARTICLE: "word-crossref" "Cross-referencing"
 106 "The cross-reference database is updated every time a word is redefined."
 107 { $subsection crossref }
 108 "You can find all words called by a given word:"
 109 { $subsection uses }
 110 "As well as all words calling a given word:"
 111 { $subsection usage }
 112 "In most cases the cross-reference database is maintained automatically, but if you do something unusual you might need to update it manually."
 113 { $subsection xref-words } ;
 114
 115 ARTICLE: "word-internals" "Word implementation details"
 116 "The behavior of a word when executed depends on the values of two slots:"
 117 { $list
 118     "the primitive number"
 119     "the primitive parameter"
 120 }
 121 "The primitive number is an index into an array of native functions in the Factor runtime."
 122 $terpri
 123 "Primitive number accessors:"
 124 { $subsection word-primitive }
 125 { $subsection set-word-primitive }
 126 "Primitive parameter accessors:"
 127 { $subsection word-def }
 128 { $subsection set-word-def }
 129 "A lower-level facility for inspecting the machine code address of a word:"
 130 { $subsection word-xt }
 131 { $subsection update-xt } ;