core/words/words-docs.factor

   1 USING: definitions help.markup help.syntax kernel parser
   2 kernel.private words.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 "Words can output their name and vocabulary:"
  16 { $subsection word-name }
  17 { $subsection word-vocabulary } ;
  18
  19 ARTICLE: "uninterned-words" "Uninterned words"
  20 "A word that is not a member of any vocabulary is said to be " { $emphasis "uninterned" } "."
  21 $nl
  22 "There are several ways of creating an uninterned word:"
  23 { $subsection <word> }
  24 { $subsection gensym }
  25 { $subsection define-temp } ;
  26
  27 ARTICLE: "colon-definition" "Word definitions"
  28 "Every word has an associated quotation definition that is called when the word is executed."
  29 $nl
  30 "Defining words at parse time:"
  31 { $subsection POSTPONE: : }
  32 { $subsection POSTPONE: ; }
  33 "Defining words at run time:"
  34 { $subsection define }
  35 { $subsection define-declared }
  36 { $subsection define-inline }
  37 "Word definitions should declare their stack effect, unless the definition is completely trivial. See " { $link "effect-declaration" } "."
  38 $nl
  39 "All other types of word definitions, such as " { $link "symbols" } " and " { $link "generic" } ", are just special cases of the above." ;
  40
  41 ARTICLE: "symbols" "Symbols"
  42 "A symbol pushes itself on the stack when executed. By convention, symbols are used as variable names (" { $link "namespaces" } ")."
  43 { $subsection symbol }
  44 { $subsection symbol? }
  45 "Defining symbols at parse time:"
  46 { $subsection POSTPONE: SYMBOL: }
  47 "Defining symbols at run time:"
  48 { $subsection define-symbol }
  49 "Symbols are just compound definitions in disguise. The following two lines are equivalent:"
  50 { $code
  51     "SYMBOL: foo"
  52     ": foo \\ foo ;"
  53 } ;
  54
  55 ARTICLE: "primitives" "Primitives"
  56 "Primitives are words defined in the Factor VM. They provide the essential low-level services to the rest of the system."
  57 { $subsection primitive }
  58 { $subsection primitive? } ;
  59
  60 ARTICLE: "deferred" "Deferred words and mutual recursion"
  61 "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."
  62 $nl
  63 "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."
  64 { $subsection POSTPONE: DEFER: }
  65 "The class of deferred word definitions:"
  66 { $subsection deferred }
  67 { $subsection deferred? }
  68 "Deferred words throw an error when called:"
  69 { $subsection undefined }
  70 "Deferred words are just compound definitions in disguise. The following two lines are equivalent:"
  71 { $code
  72     "DEFER: foo"
  73     ": foo undefined ;"
  74 } ;
  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 $nl
  79 "The first declaration specifies the time when a word runs. It affects both the non-optimizing and optimizing compilers:"
  80 { $subsection POSTPONE: parsing }
  81 "The remaining declarations only affect definitions compiled with the optimizing compiler. 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 } " or " { $link POSTPONE: flushable } ", all methods must satisfy the contract, otherwise unpredicable behavior will occur." }
  83 { $subsection POSTPONE: inline }
  84 { $subsection POSTPONE: foldable }
  85 { $subsection POSTPONE: flushable }
  86 "Stack effect declarations are documented in " { $link "effect-declaration" } "." ;
  87
  88 ARTICLE: "word-definition" "Defining words"
  89 "There are two approaches to creating word definitions:"
  90 { $list
  91     "using parsing words at parse time,"
  92     "using defining words at run time."
  93 }
  94 "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."
  95 { $subsection "colon-definition" }
  96 { $subsection "symbols" }
  97 { $subsection "primitives" }
  98 { $subsection "deferred" }
  99 { $subsection "declarations" }
 100 "Words implement the definition protocol; see " { $link "definitions" } "." ;
 101
 102 ARTICLE: "word-props" "Word properties"
 103 "Each word has a hashtable of properties."
 104 { $subsection word-prop }
 105 { $subsection set-word-prop }
 106 { $subsection word-props }
 107 { $subsection set-word-props }
 108 "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."
 109 $nl
 110 "The following are some of the properties used by the library:"
 111 { $table
 112     { "Property" "Documentation" }
 113     { { $snippet "\"parsing\"" } { $link "parsing-words" } }
 114
 115     { { { $snippet "\"inline\"" } ", " { $snippet "\"foldable\"" } ", " { $snippet "flushable" } } { $link "declarations" } }
 116
 117     { { $snippet "\"loc\"" } { "Location information - " { $link where } } }
 118
 119     { { { $snippet "\"methods\"" } ", " { $snippet "\"combination\"" } } { "Set on generic words - " { $link "generic" } } }
 120
 121     { { { $snippet "\"reading\"" } ", " { $snippet "\"writing\"" } } { "Set on slot accessor words - " { $link "slots" } } }
 122
 123     { { $snippet "\"declared-effect\"" } { $link "effect-declaration" } }
 124
 125     { { { $snippet "\"help\"" } ", " { $snippet "\"help-loc\"" } ", " { $snippet "\"help-parent\"" } } { "Where word help is stored - " { $link "writing-help" } } }
 126
 127     { { $snippet "\"infer\"" } { $link "compiler-transforms" } }
 128
 129     { { { $snippet "\"inferred-effect\"" } } { $link "inference" } }
 130
 131     { { $snippet "\"specializer\"" } { $link "specializers" } }
 132
 133     { { { $snippet "\"intrinsics\"" } ", " { $snippet "\"if-intrinsics\"" } } { $link "generator" } }
 134
 135     { { $snippet "\"predicating\"" } " Set on class predicates, stores the corresponding class word" }
 136
 137     { { { $snippet "\"constructing\"" } ", " { $snippet "\"constructor-quot\"" } } { $link "tuple-constructors" } }
 138 }
 139 "Properties which are defined for classes only:"
 140 { $table
 141     { "Property" "Documentation" }
 142     { { $snippet "\"class\"" } { "A boolean indicating whether this word is a class - " { $link "classes" } } }
 143
 144     { { $snippet "\"coercer\"" } { "A quotation for converting the top of the stack to an instance of this class" } }
 145
 146     { { $snippet "\"constructor\"" } { $link "tuple-constructors" } }
 147
 148     { { $snippet "\"slot-names\"" } { $link "tuples" } }
 149
 150     { { $snippet "\"type\"" } { $link "builtin-classes" } }
 151
 152     { { { $snippet "\"superclass\"" } ", " { $snippet "\"predicate-definition\"" } } { $link "predicates" } }
 153
 154     { { $snippet "\"members\"" } { $link "unions" } }
 155
 156     { { $snippet "\"slots\"" } { $link "slots" } }
 157
 158     { { $snippet "\"predicate\"" } { "A quotation that tests if the top of the stack is an instance of this class - " { $link "class-predicates" } } }
 159 } ;
 160
 161 ARTICLE: "word.private" "Word implementation details"
 162 "Primitive definition accessors:"
 163 { $subsection word-def }
 164 { $subsection set-word-def }
 165 "An " { $emphasis "XT" } " (execution token) is the machine code address of a word:"
 166 { $subsection word-xt } ;
 167
 168 ARTICLE: "words" "Words"
 169 "Words are the Factor equivalent of functions or procedures; a word is essentially a named quotation."
 170 $nl
 171 "Word introspection facilities and implementation details are found in the " { $vocab-link "words" } " vocabulary."
 172 $nl
 173 "A word consists of several parts:"
 174 { $list
 175     "a word name,"
 176     "a vocabulary name,"
 177     "a definition quotation, called when the word when executed,"
 178     "a set of word properties, including documentation and other meta-data."
 179 }
 180 "Words are instances of a class."
 181 { $subsection word }
 182 { $subsection word? }
 183 { $subsection "interned-words" }
 184 { $subsection "uninterned-words" }
 185 { $subsection "word-definition" }
 186 { $subsection "word-props" }
 187 { $subsection "word.private" }
 188 { $see-also "vocabularies" "vocabs.loader" "definitions" } ;
 189
 190 ABOUT: "words"
 191
 192 HELP: compiled? ( word -- ? )
 193 { $values { "word" word } { "?" "a boolean" } }
 194 { $description "Tests if a word has been compiled." } ;
 195
 196 HELP: execute ( word -- )
 197 { $values { "word" word } }
 198 { $description "Executes a word." }
 199 { $examples
 200     { $example "USING: kernel io words ;" "IN: scratchpad" ": twice dup execute execute ;\n: hello \"Hello\" print ;\n\\ hello twice" "Hello\nHello" }
 201 } ;
 202
 203 HELP: word-props ( word -- props )
 204 { $values { "word" word } { "props" "an assoc" } }
 205 { $description "Outputs a word's property table." } ;
 206
 207 HELP: set-word-props ( props word -- )
 208 { $values { "props" "an assoc" } { "word" word } }
 209 { $description "Sets a word's property table." }
 210 { $notes "The given assoc must not be a literal, since it will be mutated by future calls to " { $link set-word-prop } "." }
 211 { $side-effects "word" } ;
 212
 213 HELP: word-def ( word -- obj )
 214 { $values { "word" word } { "obj" object } }
 215 { $description "Outputs a word's primitive definition." } ;
 216
 217 HELP: set-word-def ( obj word -- )
 218 { $values { "obj" object } { "word" word } }
 219 { $description "Sets a word's primitive definition." }
 220 $low-level-note
 221 { $side-effects "word" } ;
 222
 223 HELP: deferred
 224 { $class-description "The class of deferred words created by " { $link POSTPONE: DEFER: } "." } ;
 225
 226 { deferred POSTPONE: DEFER: } related-words
 227
 228 HELP: primitive
 229 { $description "The class of primitive words." } ;
 230
 231 HELP: symbol
 232 { $description "The class of symbols created by " { $link POSTPONE: SYMBOL: } "." } ;
 233
 234 HELP: word-prop
 235 { $values { "word" word } { "name" "a property name" } { "value" "a property value" } }
 236 { $description "Retrieves a word property. Word property names are conventionally strings." } ;
 237
 238 HELP: set-word-prop
 239 { $values { "word" word } { "value" "a property value" } { "name" "a property name" } }
 240 { $description "Stores a word property. Word property names are conventionally strings." }
 241 { $side-effects "word" } ;
 242
 243 HELP: remove-word-prop
 244 { $values { "word" word } { "name" "a property name" } }
 245 { $description "Removes a word property, so future lookups will output " { $link f } " until it is set again. Word property names are conventionally strings." }
 246 { $side-effects "word" } ;
 247
 248 HELP: word-xt ( word -- start end )
 249 { $values { "word" word } { "start" "the word's start address" } { "end" "the word's end address" } }
 250 { $description "Outputs the machine code address of the word's definition." } ;
 251
 252 HELP: define-symbol
 253 { $values { "word" word } }
 254 { $description "Defines the word to push itself on the stack when executed. This is the run time equivalent of " { $link POSTPONE: SYMBOL: } "." }
 255 { $notes "This word must be called from inside " { $link with-compilation-unit } "." }
 256 { $side-effects "word" } ;
 257
 258 HELP: define
 259 { $values { "word" word } { "def" quotation } }
 260 { $description "Defines the word to call a quotation when executed. This is the run time equivalent of " { $link POSTPONE: : } "." }
 261 { $notes "This word must be called from inside " { $link with-compilation-unit } "." }
 262 { $side-effects "word" } ;
 263
 264 HELP: reset-props
 265 { $values { "word" word } { "seq" "a sequence of word property names" } }
 266 { $description "Removes all listed word properties from the word." }
 267 { $side-effects "word" } ;
 268
 269 HELP: reset-word
 270 { $values { "word" word } }
 271 { $description "Reset word declarations." }
 272 $low-level-note
 273 { $side-effects "word" } ;
 274
 275 HELP: reset-generic
 276 { $values { "word" word } }
 277 { $description "Reset word declarations and generic word properties." }
 278 $low-level-note
 279 { $side-effects "word" } ;
 280
 281 HELP: <word> ( name vocab -- word )
 282 { $values { "name" string } { "vocab" string } { "word" word } }
 283 { $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." } ;
 284
 285 HELP: gensym
 286 { $values { "word" word } }
 287 { $description "Creates an uninterned word that is not equal to any other word in the system." }
 288 { $examples { $unchecked-example "gensym ." "G:260561" } }
 289 { $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." } ;
 290
 291 HELP: bootstrapping?
 292 { $var-description "Set by the library while bootstrap is in progress. Some parsing words need to behave differently during bootstrap." } ;
 293
 294 HELP: word
 295 { $values { "word" word } }
 296 { $description "Outputs the most recently defined word." }
 297 { $class-description "The class of words. One notable subclass is " { $link class } ", the class of class words." } ;
 298
 299 { word set-word save-location } related-words
 300
 301 HELP: set-word
 302 { $values { "word" word } }
 303 { $description "Sets the recently defined word." } ;
 304
 305 HELP: lookup
 306 { $values { "name" string } { "vocab" string } { "word" "a word or " { $link f } } }
 307 { $description "Looks up a word in the dictionary. If the vocabulary or the word is not defined, outputs " { $link f } "." } ;
 308
 309 HELP: reveal
 310 { $values { "word" word } }
 311 { $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 } "." } ;
 312
 313 HELP: check-create
 314 { $values { "name" string } { "vocab" string } }
 315 { $description "Throws a " { $link check-create } " error if " { $snippet "name" } " or " { $snippet "vocab" } " is not a string." }
 316 { $error-description "Thrown if " { $link create } " is called with invalid parameters." } ;
 317
 318 HELP: create
 319 { $values { "name" string } { "vocab" string } { "word" word } }
 320 { $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." } ;
 321
 322 HELP: constructor-word
 323 { $values { "name" string } { "vocab" string } { "word" word } }
 324 { $description "Creates a new word, surrounding " { $snippet "name" } " in angle brackets." }
 325 { $examples { $example "USING: prettyprint words ;" "\"salmon\" \"scratchpad\" constructor-word ." "<salmon>" } } ;
 326
 327 { POSTPONE: FORGET: forget forget* forget-vocab } related-words
 328
 329 HELP: target-word
 330 { $values { "word" word } { "target" word } }
 331 { $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." } ;
 332
 333 HELP: bootstrap-word
 334 { $values { "word" word } { "target" word } }
 335 { $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." } ;
 336
 337 HELP: parsing-word?
 338 { $values { "obj" object } { "?" "a boolean" } }
 339 { $description "Tests if an object is a parsing word declared by " { $link POSTPONE: parsing } "." }
 340 { $notes "Outputs " { $link f } " if the object is not a word." } ;
 341
 342 HELP: define-declared
 343 { $values { "word" word } { "def" quotation } { "effect" effect } }
 344 { $description "Defines a word and declares its stack effect." }
 345 { $side-effects "word" } ;
 346
 347 HELP: define-temp
 348 { $values { "quot" quotation } { "word" word } }
 349 { $description "Creates an uninterned word that will call " { $snippet "quot" } " when executed." }
 350 { $notes
 351     "The following phrases are equivalent:"
 352     { $code "[ 2 2 + . ] call" }
 353     { $code "[ 2 2 + . ] define-temp execute" }
 354     "This word must be called from inside " { $link with-compilation-unit } "."
 355 } ;
 356
 357 HELP: quot-uses
 358 { $values { "quot" quotation } { "assoc" "an assoc with words as keys" } }
 359 { $description "Outputs a set of words referenced by the quotation and any quotations it contains." } ;
 360
 361 HELP: delimiter?
 362 { $values { "obj" object } { "?" "a boolean" } }
 363 { $description "Tests if an object is a delimiter word declared by " { $link POSTPONE: delimiter } "." }
 364 { $notes "Outputs " { $link f } " if the object is not a word." } ;
 365
 366 HELP: make-flushable
 367 { $values { "word" word } }
 368 { $description "Declares a word as " { $link POSTPONE: flushable } "." }
 369 { $side-effects "word" } ;
 370
 371 HELP: make-foldable
 372 { $values { "word" word } }
 373 { $description "Declares a word as " { $link POSTPONE: foldable } "." }
 374 { $side-effects "word" } ;
 375
 376 HELP: make-inline
 377 { $values { "word" word } }
 378 { $description "Declares a word as " { $link POSTPONE: inline } "." }
 379 { $side-effects "word" } ;
 380
 381 HELP: define-inline
 382 { $values { "word" word } { "quot" quotation } }
 383 { $description "Defines a word and makes it " { $link POSTPONE: inline } "." }
 384 { $side-effects "word" } ;