core/words/words-docs.factor

   1 USING: definitions help.markup help.syntax kernel parser
   2 kernel.private vocabs classes quotations
   3 strings effects compiler.units ;
   4 IN: words
   5
   6 ARTICLE: "interned-words" "Looking up and creating words"
   7 "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" } "."
   8 $nl
   9 "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."
  10 $nl
  11 "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" } ")."
  12 { $subsection create }
  13 { $subsection create-in }
  14 { $subsection lookup } ;
  15
  16 ARTICLE: "uninterned-words" "Uninterned words"
  17 "A word that is not a member of any vocabulary is said to be " { $emphasis "uninterned" } "."
  18 $nl
  19 "There are several ways of creating an uninterned word:"
  20 { $subsection <word> }
  21 { $subsection gensym }
  22 { $subsection define-temp } ;
  23
  24 ARTICLE: "colon-definition" "Colon definitions"
  25 "Every word has an associated quotation definition that is called when the word is executed. A " { $emphasis "colon definition" } " is a word where this quotation is supplied directly by the user. This is the simplest and most common type of word definition."
  26 $nl
  27 "Defining words at parse time:"
  28 { $subsection POSTPONE: : }
  29 { $subsection POSTPONE: ; }
  30 "Defining words at run time:"
  31 { $subsection define }
  32 { $subsection define-declared }
  33 { $subsection define-inline }
  34 "Word definitions must declare their stack effect. See " { $link "effects" } "."
  35 $nl
  36 "All other types of word definitions, such as " { $link "words.symbol" } " and " { $link "generic" } ", are just special cases of the above." ;
  37
  38 ARTICLE: "primitives" "Primitives"
  39 "Primitives are words defined in the Factor VM. They provide the essential low-level services to the rest of the system."
  40 { $subsection primitive }
  41 { $subsection primitive? } ;
  42
  43 ARTICLE: "deferred" "Deferred words and mutual recursion"
  44 "Words cannot be referenced before they are defined; that is, source files must order definitions in a strictly bottom-up fashion. This is done to simplify the implementation, facilitate better parse time checking and remove some odd corner cases; it also encourages better coding style."
  45 $nl
  46 "Sometimes this restriction gets in the way, for example when defining mutually-recursive words; one way to get around this limitation is to make a forward definition."
  47 { $subsection POSTPONE: DEFER: }
  48 "The class of deferred word definitions:"
  49 { $subsection deferred }
  50 { $subsection deferred? }
  51 "Deferred words throw an error when called:"
  52 { $subsection undefined }
  53 "Deferred words are just compound definitions in disguise. The following two lines are equivalent:"
  54 { $code
  55     "DEFER: foo"
  56     ": foo undefined ;"
  57 } ;
  58
  59 ARTICLE: "declarations" "Compiler declarations"
  60 "Compiler declarations are parsing words that set a word property in the most recently defined word. They appear after the final " { $link POSTPONE: ; } " of a word definition:"
  61 { $code ": cubed ( x -- y ) dup dup * * ; foldable" }
  62 "Compiler declarations assert that the word follows a certain contract, enabling certain optimizations that are not valid in general."
  63 { $subsection POSTPONE: inline }
  64 { $subsection POSTPONE: foldable }
  65 { $subsection POSTPONE: flushable }
  66 { $subsection POSTPONE: recursive }
  67 "It is entirely up to the programmer to ensure that the word satisfies the contract of a declaration. Furthermore, if a generic word is declared " { $link POSTPONE: foldable } " or " { $link POSTPONE: flushable } ", all methods must satisfy the contract. Unspecified behavior may result if a word does not follow the contract of one of its declarations."
  68 { $see-also "effects" } ;
  69
  70 ARTICLE: "word-props" "Word properties"
  71 "Each word has a hashtable of properties."
  72 { $subsection word-prop }
  73 { $subsection set-word-prop }
  74 "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."
  75 $nl
  76 "The following are some of the properties used by the library:"
  77 { $table
  78     { "Property" "Documentation" }
  79     { { $snippet "\"parsing\"" } { $link "parsing-words" } }
  80
  81     { { { $snippet "\"inline\"" } ", " { $snippet "\"foldable\"" } ", " { $snippet "flushable" } } { $link "declarations" } }
  82
  83     { { $snippet "\"loc\"" } { "Location information - " { $link where } } }
  84
  85     { { { $snippet "\"methods\"" } ", " { $snippet "\"combination\"" } } { "Set on generic words - " { $link "generic" } } }
  86
  87     { { { $snippet "\"reading\"" } ", " { $snippet "\"writing\"" } } { "Set on slot accessor words - " { $link "slots" } } }
  88
  89     { { $snippet "\"declared-effect\"" } { $link "effects" } }
  90
  91     { { { $snippet "\"help\"" } ", " { $snippet "\"help-loc\"" } ", " { $snippet "\"help-parent\"" } } { "Where word help is stored - " { $link "writing-help" } } }
  92
  93     { { $snippet "\"specializer\"" } { $link "hints" } }
  94
  95     { { $snippet "\"predicating\"" } " Set on class predicates, stores the corresponding class word" }
  96 }
  97 "Properties which are defined for classes only:"
  98 { $table
  99     { "Property" "Documentation" }
 100     { { $snippet "\"class\"" } { "A boolean indicating whether this word is a class - " { $link "classes" } } }
 101
 102     { { $snippet "\"coercer\"" } { "A quotation for converting the top of the stack to an instance of this class" } }
 103
 104     { { $snippet "\"constructor\"" } { $link "tuple-constructors" } }
 105
 106     { { $snippet "\"type\"" } { $link "builtin-classes" } }
 107
 108     { { { $snippet "\"superclass\"" } ", " { $snippet "\"predicate-definition\"" } } { $link "predicates" } }
 109
 110     { { $snippet "\"members\"" } { $link "unions" } }
 111
 112     { { $snippet "\"slots\"" } { $link "slots" } }
 113
 114     { { $snippet "\"predicate\"" } { "A quotation that tests if the top of the stack is an instance of this class - " { $link "class-predicates" } } }
 115 } ;
 116
 117 ARTICLE: "word.private" "Word implementation details"
 118 "The " { $snippet "def" } " slot of a word holds a " { $link quotation } " instance that is called when the word is executed."
 119 $nl
 120 "An " { $emphasis "XT" } " (execution token) is the machine code address of a word:"
 121 { $subsection word-xt } ;
 122
 123 ARTICLE: "words.introspection" "Word introspection"
 124 "Word introspection facilities and implementation details are found in the " { $vocab-link "words" } " vocabulary."
 125 $nl
 126 "Word objects contain several slots:"
 127 { $table
 128     { { $snippet "name" } "a word name" }
 129     { { $snippet "vocabulary" } "a word vocabulary name" }
 130     { { $snippet "def" } "a definition quotation" }
 131     { { $snippet "props" } "an assoc of word properties, including documentation and other meta-data" }
 132 }
 133 "Words are instances of a class."
 134 { $subsection word }
 135 { $subsection word? }
 136 "Words implement the definition protocol; see " { $link "definitions" } "."
 137 { $subsection "interned-words" }
 138 { $subsection "uninterned-words" }
 139 { $subsection "word-props" }
 140 { $subsection "word.private" } ;
 141
 142 ARTICLE: "words" "Words"
 143 "Words are the Factor equivalent of functions or procedures; a word is essentially a named quotation."
 144 $nl
 145 "There are two ways of creating word definitions:"
 146 { $list
 147     "using parsing words at parse time,"
 148     "using defining words at run time."
 149 }
 150 "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."
 151 $nl
 152 "Types of words:"
 153 { $subsection "colon-definition" }
 154 { $subsection "words.symbol" }
 155 { $subsection "words.alias" }
 156 { $subsection "words.constant" }
 157 { $subsection "primitives" }
 158 "Advanced topics:"
 159 { $subsection "deferred" }
 160 { $subsection "declarations" }
 161 { $subsection "words.introspection" }
 162 { $see-also "vocabularies" "vocabs.loader" "definitions" "see" } ;
 163
 164 ABOUT: "words"
 165
 166 HELP: deferred
 167 { $class-description "The class of deferred words created by " { $link POSTPONE: DEFER: } "." } ;
 168
 169 { deferred POSTPONE: DEFER: } related-words
 170
 171 HELP: primitive
 172 { $description "The class of primitive words." } ;
 173
 174 HELP: word-prop
 175 { $values { "word" word } { "name" "a property name" } { "value" "a property value" } }
 176 { $description "Retrieves a word property. Word property names are conventionally strings." } ;
 177
 178 HELP: set-word-prop
 179 { $values { "word" word } { "value" "a property value" } { "name" "a property name" } }
 180 { $description "Stores a word property. Word property names are conventionally strings." }
 181 { $side-effects "word" } ;
 182
 183 HELP: remove-word-prop
 184 { $values { "word" word } { "name" "a property name" } }
 185 { $description "Removes a word property, so future lookups will output " { $link f } " until it is set again. Word property names are conventionally strings." }
 186 { $side-effects "word" } ;
 187
 188 HELP: word-xt ( word -- start end )
 189 { $values { "word" word } { "start" "the word's start address" } { "end" "the word's end address" } }
 190 { $description "Outputs the machine code address of the word's definition." } ;
 191
 192 HELP: define
 193 { $values { "word" word } { "def" quotation } }
 194 { $description "Defines the word to call a quotation when executed. This is the run time equivalent of " { $link POSTPONE: : } "." }
 195 { $notes "This word must be called from inside " { $link with-compilation-unit } "." }
 196 { $side-effects "word" } ;
 197
 198 HELP: reset-props
 199 { $values { "word" word } { "seq" "a sequence of word property names" } }
 200 { $description "Removes all listed word properties from the word." }
 201 { $side-effects "word" } ;
 202
 203 HELP: reset-word
 204 { $values { "word" word } }
 205 { $description "Reset word declarations." }
 206 $low-level-note
 207 { $side-effects "word" } ;
 208
 209 HELP: reset-generic
 210 { $values { "word" word } }
 211 { $description "Reset word declarations and generic word properties." }
 212 $low-level-note
 213 { $side-effects "word" } ;
 214
 215 HELP: <word> ( name vocab -- word )
 216 { $values { "name" string } { "vocab" string } { "word" word } }
 217 { $description "Allocates an uninterned word with the specified name and vocabulary, and a blank word property hashtable. User code should call " { $link gensym } " to create uninterned words and " { $link create } " to create interned words." } ;
 218
 219 HELP: gensym
 220 { $values { "word" word } }
 221 { $description "Creates an uninterned word that is not equal to any other word in the system." }
 222 { $examples { $unchecked-example "gensym ." "G:260561" } }
 223 { $notes "Gensyms are often used as placeholder values that have no meaning of their own but must be unique. For example, the compiler uses gensyms to label sections of code." } ;
 224
 225 HELP: bootstrapping?
 226 { $var-description "Set by the library while bootstrap is in progress. Some parsing words need to behave differently during bootstrap." } ;
 227
 228 HELP: word
 229 { $values { "word" word } }
 230 { $description "Outputs the most recently defined word." }
 231 { $class-description "The class of words. One notable subclass is " { $link class } ", the class of class words." } ;
 232
 233 { word set-word save-location } related-words
 234
 235 HELP: set-word
 236 { $values { "word" word } }
 237 { $description "Sets the recently defined word." } ;
 238
 239 HELP: lookup
 240 { $values { "name" string } { "vocab" string } { "word" { $maybe word } } }
 241 { $description "Looks up a word in the dictionary. If the vocabulary or the word is not defined, outputs " { $link f } "." } ;
 242
 243 HELP: reveal
 244 { $values { "word" word } }
 245 { $description "Adds a newly-created word to the dictionary. Usually this word does not need to be called directly, and is only called as part of " { $link create } "." } ;
 246
 247 HELP: check-create
 248 { $values { "name" string } { "vocab" string } }
 249 { $description "Throws a " { $link check-create } " error if " { $snippet "name" } " or " { $snippet "vocab" } " is not a string." }
 250 { $error-description "Thrown if " { $link create } " is called with invalid parameters." } ;
 251
 252 HELP: create
 253 { $values { "name" string } { "vocab" string } { "word" word } }
 254 { $description "Creates a new word. If the vocabulary already contains a word with the requested name, outputs the existing word. The vocabulary must exist already; if it does not, you must call " { $link create-vocab } " first." } ;
 255
 256 HELP: constructor-word
 257 { $values { "name" string } { "vocab" string } { "word" word } }
 258 { $description "Creates a new word, surrounding " { $snippet "name" } " in angle brackets." }
 259 { $examples { $example "USING: prettyprint words ;" "\"salmon\" \"scratchpad\" constructor-word ." "<salmon>" } } ;
 260
 261 { POSTPONE: FORGET: forget forget* forget-vocab } related-words
 262
 263 HELP: target-word
 264 { $values { "word" word } { "target" word } }
 265 { $description "Looks up a word with the same name and vocabulary as the given word. Used during bootstrap to transfer host words to the target dictionary." } ;
 266
 267 HELP: bootstrap-word
 268 { $values { "word" word } { "target" word } }
 269 { $description "Looks up a word with the same name and vocabulary as the given word, performing a transformation to handle parsing words in the target dictionary. Used during bootstrap to transfer host words to the target dictionary." } ;
 270
 271 HELP: parsing-word?
 272 { $values { "object" object } { "?" "a boolean" } }
 273 { $description "Tests if an object is a parsing word declared by " { $link POSTPONE: SYNTAX: } "." }
 274 { $notes "Outputs " { $link f } " if the object is not a word." } ;
 275
 276 HELP: define-declared
 277 { $values { "word" word } { "def" quotation } { "effect" effect } }
 278 { $description "Defines a word and declares its stack effect." }
 279 { $side-effects "word" } ;
 280
 281 HELP: define-temp
 282 { $values { "quot" quotation } { "effect" effect } { "word" word } }
 283 { $description "Creates an uninterned word that will call " { $snippet "quot" } " when executed." }
 284 { $notes
 285     "The following phrases are equivalent:"
 286     { $code "[ 2 2 + . ] call" }
 287     { $code "[ 2 2 + . ] (( -- )) define-temp execute" }
 288     "This word must be called from inside " { $link with-compilation-unit } "."
 289 } ;
 290
 291 HELP: delimiter?
 292 { $values { "obj" object } { "?" "a boolean" } }
 293 { $description "Tests if an object is a delimiter word declared by " { $link POSTPONE: delimiter } "." }
 294 { $notes "Outputs " { $link f } " if the object is not a word." } ;
 295
 296 HELP: make-flushable
 297 { $values { "word" word } }
 298 { $description "Declares a word as " { $link POSTPONE: flushable } "." }
 299 { $side-effects "word" } ;
 300
 301 HELP: make-foldable
 302 { $values { "word" word } }
 303 { $description "Declares a word as " { $link POSTPONE: foldable } "." }
 304 { $side-effects "word" } ;
 305
 306 HELP: make-inline
 307 { $values { "word" word } }
 308 { $description "Declares a word as " { $link POSTPONE: inline } "." }
 309 { $side-effects "word" } ;
 310
 311 HELP: define-inline
 312 { $values { "word" word } { "def" quotation } { "effect" effect } }
 313 { $description "Defines a word and makes it " { $link POSTPONE: inline } "." }
 314 { $side-effects "word" } ;