core/syntax/syntax-docs.factor

   1 USING: generic help.syntax help.markup kernel math parser words
   2 effects classes classes.tuple generic.math generic.single arrays
   3 io.pathnames vocabs.loader io sequences assocs words.symbol
   4 words.alias words.constant combinators vocabs.parser ;
   5 IN: syntax
   6
   7 ARTICLE: "parser-algorithm" "Parser algorithm"
   8 "At the most abstract level, Factor syntax consists of whitespace-separated tokens. The parser tokenizes the input on whitespace boundaries. The parser is case-sensitive and whitespace between tokens is significant, so the following three expressions tokenize differently:"
   9 { $code "2X+\n2 X +\n2 x +" }
  10 "As the parser reads tokens it makes a distinction between numbers, ordinary words, and parsing words. Tokens are appended to the parse tree, the top level of which is a quotation returned by the original parser invocation. Nested levels of the parse tree are created by parsing words."
  11 $nl
  12 "The parser iterates through the input text, checking each character in turn. Here is the parser algorithm in more detail -- some of the concepts therein will be defined shortly:"
  13 { $list
  14     { "If the current character is a double-quote (\"), the " { $link POSTPONE: " } " parsing word is executed, causing a string to be read." }
  15     {
  16         "Otherwise, the next token is taken from the input. The parser searches for a word named by the token in the currently used set of vocabularies. If the word is found, one of the following two actions is taken:"
  17         { $list
  18             "If the word is an ordinary word, it is appended to the parse tree."
  19             "If the word is a parsing word, it is executed."
  20         }
  21     }
  22     "Otherwise if the token does not represent a known word, the parser attempts to parse it as a number. If the token is a number, the number object is added to the parse tree. Otherwise, an error is raised and parsing halts."
  23 }
  24 "Parsing words play a key role in parsing; while ordinary words and numbers are simply added to the parse tree, parsing words execute in the context of the parser, and can do their own parsing and create nested data structures in the parse tree. Parsing words are also able to define new words."
  25 $nl
  26 "While parsing words supporting arbitrary syntax can be defined, the default set is found in the " { $vocab-link "syntax" } " vocabulary and provides the basis for all further syntactic interaction with Factor." ;
  27
  28 ARTICLE: "syntax-comments" "Comments"
  29 { $subsections
  30     POSTPONE: !
  31     POSTPONE: #!
  32 } ;
  33
  34 ARTICLE: "syntax-immediate" "Parse time evaluation"
  35 "Code can be evaluated at parse time. This is a rarely-used feature; one use-case is " { $link "loading-libs" } ", where you want to execute some code before the words in a source file are compiled."
  36 { $subsections
  37     POSTPONE: <<
  38     POSTPONE: >>
  39 } ;
  40
  41 ARTICLE: "syntax-integers" "Integer syntax"
  42 "The printed representation of an integer consists of a sequence of digits, optionally prefixed by a sign."
  43 { $code
  44     "123456"
  45     "-10"
  46     "2432902008176640000"
  47 }
  48 "Integers are entered in base 10 unless prefixed with a base change parsing word."
  49 { $subsections
  50     POSTPONE: BIN:
  51     POSTPONE: OCT:
  52     POSTPONE: HEX:
  53 }
  54 "More information on integers can be found in " { $link "integers" } "." ;
  55
  56 ARTICLE: "syntax-ratios" "Ratio syntax"
  57 "The printed representation of a ratio is a pair of integers separated by a slash (/), prefixed by an optional whole number part followed by a plus (+). No intermediate whitespace is permitted. Here are some examples:"
  58 { $code
  59     "75/33"
  60     "1/10"
  61     "-5/-6"
  62     "1+1/3"
  63     "-10+1/7"
  64 }
  65 "More information on ratios can be found in " { $link "rationals" } ;
  66
  67 ARTICLE: "syntax-floats" "Float syntax"
  68 "Floating point literals can be input in base 10 or 16. Base 10 literals must contain a decimal point, and may contain an exponent after " { $snippet "e" } ":"
  69 { $code
  70     "10.5"
  71     "-3.1456"
  72     "7.e13"
  73     "1.0e-5"
  74 }
  75 "Base 16 literals use " { $snippet "p" } " instead of " { $snippet "e" } " for the exponent, which is still decimal:"
  76 { $example
  77     "10.125 HEX: 1.44p3 = ."
  78     "t"
  79 }
  80 "Syntax for special float values:"
  81 { $table
  82 { "Positive infinity" { $snippet "1/0." } }
  83 { "Negative infinity" { $snippet "-1/0." } }
  84 { "Not-a-number" { $snippet "0/0." } }
  85 }
  86 "A Not-a-number with an arbitrary payload can also be parsed in:"
  87 { $subsections POSTPONE: NAN: }
  88 "More information on floats can be found in " { $link "floats" } "." ;
  89
  90 ARTICLE: "syntax-complex-numbers" "Complex number syntax"
  91 "A complex number is given by two components, a “real” part and “imaginary” part. The components must either be integers, ratios or floats."
  92 { $code
  93     "C{ 1/2 1/3 }   ! the complex number 1/2+1/3i"
  94     "C{ 0 1 }       ! the imaginary unit"
  95 }
  96 { $subsections POSTPONE: C{ }
  97 "More information on complex numbers can be found in " { $link "complex-numbers" } "." ;
  98
  99 ARTICLE: "syntax-numbers" "Number syntax"
 100 "If a vocabulary lookup of a token fails, the parser attempts to parse it as a number."
 101 { $subsections
 102     "syntax-integers"
 103     "syntax-ratios"
 104     "syntax-floats"
 105     "syntax-complex-numbers"
 106 } ;
 107
 108 ARTICLE: "syntax-words" "Word syntax"
 109 "A word occurring inside a quotation is executed when the quotation is called. Sometimes a word needs to be pushed on the data stack instead. The canonical use case for this is passing the word to the " { $link execute } " combinator, or alternatively, reflectively accessing word properties (" { $link "word-props" } ")."
 110 { $subsections
 111     POSTPONE: \
 112     POSTPONE: POSTPONE:
 113 }
 114 "The implementation of the " { $link POSTPONE: \ } " word is discussed in detail in " { $link "reading-ahead" } ". Words are documented in " { $link "words" } "." ;
 115
 116 ARTICLE: "escape" "Character escape codes"
 117 { $table
 118     { "Escape code" "Meaning" }
 119     { { $snippet "\\\\" } { $snippet "\\" } }
 120     { { $snippet "\\s" } "a space" }
 121     { { $snippet "\\t" } "a tab" }
 122     { { $snippet "\\n" } "a newline" }
 123     { { $snippet "\\r" } "a carriage return" }
 124     { { $snippet "\\0" } "a null byte (ASCII 0)" }
 125     { { $snippet "\\e" } "escape (ASCII 27)" }
 126     { { $snippet "\\\"" } { $snippet "\"" } }
 127     { { $snippet "\\u" { $emphasis "xxxxxx" } } { "The Unicode code point with hexadecimal number " { $snippet { $emphasis "xxxxxx" } } } }
 128     { { $snippet "\\u{" { $emphasis "name" } "}" } { "The Unicode code point named " { $snippet { $emphasis "name" } } } }
 129 } ;
 130
 131 ARTICLE: "syntax-strings" "Character and string syntax"
 132 "Factor has no distinct character type, however Unicode character value integers can be read by specifying a literal character, or an escaped representation thereof."
 133 { $subsections
 134     POSTPONE: CHAR:
 135     POSTPONE: "
 136     "escape"
 137 }
 138 "Strings are documented in " { $link "strings" } "." ;
 139
 140 ARTICLE: "syntax-sbufs" "String buffer syntax"
 141 { $subsections POSTPONE: SBUF" }
 142 "String buffers are documented in " { $link "sbufs" } "." ;
 143
 144 ARTICLE: "syntax-arrays" "Array syntax"
 145 { $subsections
 146     POSTPONE: {
 147     POSTPONE: }
 148 }
 149 "Arrays are documented in " { $link "arrays" } "." ;
 150
 151 ARTICLE: "syntax-vectors" "Vector syntax"
 152 { $subsections POSTPONE: V{ }
 153 "Vectors are documented in " { $link "vectors" } "." ;
 154
 155 ARTICLE: "syntax-hashtables" "Hashtable syntax"
 156 { $subsections POSTPONE: H{ }
 157 "Hashtables are documented in " { $link "hashtables" } "." ;
 158
 159 ARTICLE: "syntax-tuples" "Tuple syntax"
 160 { $subsections POSTPONE: T{ }
 161 "Tuples are documented in " { $link "tuples" } "."  ;
 162
 163 ARTICLE: "syntax-quots" "Quotation syntax"
 164 { $subsections
 165     POSTPONE: [
 166     POSTPONE: ]
 167 }
 168 "Quotations are documented in " { $link "quotations" } "." ;
 169
 170 ARTICLE: "syntax-byte-arrays" "Byte array syntax"
 171 { $subsections POSTPONE: B{ }
 172 "Byte arrays are documented in " { $link "byte-arrays" } "." ;
 173
 174 ARTICLE: "syntax-pathnames" "Pathname syntax"
 175 { $subsections POSTPONE: P" }
 176 "Pathnames are documented in " { $link "io.pathnames" } "." ;
 177
 178 ARTICLE: "syntax-effects" "Stack effect syntax"
 179 "Note that this is " { $emphasis "not" } " syntax to declare stack effects of words. This pushes an " { $link effect } " instance on the stack for reflection, for use with words such as " { $link define-declared } ", " { $link call-effect } " and " { $link execute-effect } "."
 180 { $subsections POSTPONE: (( }
 181 { $see-also "effects" "inference" "tools.inference" } ;
 182
 183 ARTICLE: "syntax-literals" "Literals"
 184 "Many different types of objects can be constructed at parse time via literal syntax. Numbers are a special case since support for reading them is built-in to the parser. All other literals are constructed via parsing words."
 185 $nl
 186 "If a quotation contains a literal object, the same literal object instance is used each time the quotation executes; that is, literals are “live”."
 187 $nl
 188 "Using mutable object literals in word definitions requires care, since if those objects are mutated, the actual word definition will be changed, which is in most cases not what you would expect. Literals should be " { $link clone } "d before being passed to a word which may potentially mutate them."
 189 { $subsections
 190     "syntax-numbers"
 191     "syntax-words"
 192     "syntax-quots"
 193     "syntax-arrays"
 194     "syntax-strings"
 195     "syntax-byte-arrays"
 196     "syntax-vectors"
 197     "syntax-sbufs"
 198     "syntax-hashtables"
 199     "syntax-tuples"
 200     "syntax-pathnames"
 201     "syntax-effects"
 202 } ;
 203
 204 ARTICLE: "syntax" "Syntax"
 205 "Factor has two main forms of syntax: " { $emphasis "definition" } " syntax and " { $emphasis "literal" } " syntax. Code is data, so the syntax for code is a special case of object literal syntax. This section documents literal syntax. Definition syntax is covered in " { $link "words" } ". Extending the parser is the main topic of " { $link "parser" } "."
 206 { $subsections
 207     "parser-algorithm"
 208     "word-search"
 209     "top-level-forms"
 210     "syntax-comments"
 211     "syntax-literals"
 212     "syntax-immediate"
 213 } ;
 214
 215 ABOUT: "syntax"
 216
 217 HELP: delimiter
 218 { $syntax ": foo ... ; delimiter" }
 219 { $description "Declares the most recently defined word as a delimiter. Delimiters are words which are only ever valid as the end of a nested block to be read by " { $link parse-until } ". An unpaired occurrence of a delimiter is a parse error." } ;
 220
 221 HELP: deprecated
 222 { $syntax ": foo ... ; deprecated" }
 223 { $description "Declares the most recently defined word as deprecated. If the " { $vocab-link "tools.deprecation" } " vocabulary is loaded, usages of deprecated words will be noted by the " { $link "tools.errors" } " system." }
 224 { $notes "Code that uses deprecated words continues to function normally; the errors are purely informational. However, code that uses deprecated words should be updated, for the deprecated words are intended to be removed soon." } ;
 225
 226 HELP: SYNTAX:
 227 { $syntax "SYNTAX: foo ... ;" }
 228 { $description "Defines a parsing word." }
 229 { $examples "In the below example, the " { $snippet "world" } " word is never called, however its body references a parsing word which executes immediately:" { $example "USE: io" "IN: scratchpad" "<< SYNTAX: HELLO \"Hello parser!\" print ; >>\n: world ( -- ) HELLO ;" "Hello parser!" } } ;
 230
 231 HELP: inline
 232 { $syntax ": foo ... ; inline" }
 233 { $description
 234     "Declares the most recently defined word as an inline word. The optimizing compiler copies definitions of inline words when compiling calls to them."
 235     $nl
 236     "Combinators must be inlined in order to compile with the optimizing compiler - see " { $link "inference-combinators" } ". For any other word, inlining is merely an optimization."
 237     $nl
 238     "The non-optimizing quotation compiler ignores inlining declarations."
 239 } ;
 240
 241 HELP: recursive
 242 { $syntax ": foo ... ; recursive" }
 243 { $description "Declares the most recently defined word as a recursive word." }
 244 { $notes "This declaration is only required for " { $link POSTPONE: inline } " words which call themselves. See " { $link "inference-recursive-combinators" } "." } ;
 245
 246 HELP: foldable
 247 { $syntax ": foo ... ; foldable" }
 248 { $description
 249     "Declares that the most recently defined word may be evaluated at compile-time if all inputs are literal. Foldable words must satisfy a very strong contract:"
 250     { $list
 251         "foldable words must not have any observable side effects,"
 252         "foldable words must halt - for example, a word computing a series until it coverges should not be foldable, since compilation will not halt in the event the series does not converge."
 253         "both inputs and outputs of foldable words must be immutable."
 254     }
 255     "The last restriction ensures that words such as " { $link clone } " do not satisfy the foldable word contract. Indeed, " { $link clone } " will output a mutable object if its input is mutable, and so it is undesirable to evaluate it at compile-time, since doing so would give incorrect semantics for code that clones mutable objects and proceeds to mutate them."
 256 }
 257 { $notes
 258     "Folding optimizations are not applied if the call site of a word is in the same source file as the word. This is a side-effect of the compilation unit system; see " { $link "compilation-units" } "."
 259 }
 260 { $examples "Most operations on numbers are foldable. For example, " { $snippet "2 2 +" } " compiles to a literal 4, since " { $link + } " is declared foldable." } ;
 261
 262 HELP: flushable
 263 { $syntax ": foo ... ; flushable" }
 264 { $description
 265     "Declares that the most recently defined word has no side effects, and thus calls to this word may be pruned by the compiler if the outputs are not used."
 266     $nl
 267     "Note that many words are flushable but not foldable, for example " { $link clone } " and " { $link <array> } "."
 268 } ;
 269
 270 HELP: t
 271 { $syntax "t" }
 272 { $values { "t" "the canonical truth value" } }
 273 { $class-description "The canonical truth value, which is an instance of itself." } ;
 274
 275 HELP: f
 276 { $syntax "f" }
 277 { $values { "f" "the singleton false value" } }
 278 { $description "The " { $link f } " parsing word adds the " { $link f } " object to the parse tree, and is also the class whose sole instance is the " { $link f } " object. The " { $link f } " object is the singleton false value, the only object that is not true. The " { $link f } " object is not equal to the " { $link f } " class word, which can be pushed on the stack using word wrapper syntax:"
 279 { $code "f    ! the singleton f object denoting falsity\n\\ f  ! the f class word" } } ;
 280
 281 HELP: [
 282 { $syntax "[ elements... ]" }
 283 { $description "Marks the beginning of a literal quotation." }
 284 { $examples { $code "[ 1 2 3 ]" } } ;
 285
 286 { POSTPONE: [ POSTPONE: ] } related-words
 287
 288 HELP: ]
 289 { $syntax "]" }
 290 { $description "Marks the end of a literal quotation."
 291 $nl
 292 "Parsing words can use this word as a generic end delimiter." } ;
 293
 294 HELP: }
 295 { $syntax "}" }
 296 { $description "Marks the end of an array, vector, hashtable, complex number, tuple, or wrapper."
 297 $nl
 298 "Parsing words can use this word as a generic end delimiter." } ;
 299
 300 { POSTPONE: { POSTPONE: V{ POSTPONE: H{ POSTPONE: C{ POSTPONE: T{ POSTPONE: W{ POSTPONE: } } related-words
 301
 302 HELP: {
 303 { $syntax "{ elements... }" }
 304 { $values { "elements" "a list of objects" } }
 305 { $description "Marks the beginning of a literal array. Literal arrays are terminated by " { $link POSTPONE: } } "." }
 306 { $examples { $code "{ 1 2 3 }" } } ;
 307
 308 HELP: V{
 309 { $syntax "V{ elements... }" }
 310 { $values { "elements" "a list of objects" } }
 311 { $description "Marks the beginning of a literal vector. Literal vectors are terminated by " { $link POSTPONE: } } "." }
 312 { $examples { $code "V{ 1 2 3 }" } } ;
 313
 314 HELP: B{
 315 { $syntax "B{ elements... }" }
 316 { $values { "elements" "a list of integers" } }
 317 { $description "Marks the beginning of a literal byte array. Literal byte arrays are terminated by " { $link POSTPONE: } } "." }
 318 { $examples { $code "B{ 1 2 3 }" } } ;
 319
 320 HELP: H{
 321 { $syntax "H{ { key value }... }" }
 322 { $values { "key" "an object" } { "value" "an object" } }
 323 { $description "Marks the beginning of a literal hashtable, given as a list of two-element arrays holding key/value pairs. Literal hashtables are terminated by " { $link POSTPONE: } } "." }
 324 { $examples { $code "H{ { \"tuna\" \"fish\" } { \"jalapeno\" \"vegetable\" } }" } } ;
 325
 326 HELP: C{
 327 { $syntax "C{ real-part imaginary-part }" }
 328 { $values { "real-part" "a real number" } { "imaginary-part" "a real number" } }
 329 { $description "Parses a complex number given in rectangular form as a pair of real numbers. Literal complex numbers are terminated by " { $link POSTPONE: } } "." }  ;
 330
 331 HELP: T{
 332 { $syntax "T{ class }" "T{ class f slot-values... }" "T{ class { slot-name slot-value } ... }" }
 333 { $values { "class" "a tuple class word" } { "slots" "slot values" } }
 334 { $description "Marks the beginning of a literal tuple."
 335 $nl
 336 "Three literal syntax forms are recognized:"
 337 { $list
 338     { "empty tuple form: if no slot values are specified, then the literal tuple will have all slots set to their initial values (see " { $link "slot-initial-values" } ")." }
 339     { "BOA-form: if the first element of " { $snippet "slots" } " is " { $snippet "f" } ", then the remaining elements are slot values corresponding to slots in the order in which they are defined in the " { $link POSTPONE: TUPLE: } " form." }
 340     { "assoc-form: otherwise, " { $snippet "slots" } " is interpreted as a sequence of " { $snippet "{ slot-name value }" } " pairs. The " { $snippet "slot-name" } " should not be quoted." }
 341 }
 342 "BOA form is more concise, whereas assoc form is more readable for larger tuples with many slots, or if only a few slots are to be specified."
 343 $nl
 344 "With BOA form, specifying an insufficient number of values is given after the class word, the remaining slots of the tuple are set to their initial values (see " { $link "slot-initial-values" } "). If too many values are given, an error will be raised." }
 345 { $examples
 346 "An empty tuple; since vectors have their own literal syntax, the above is equivalent to " { $snippet "V{ }" } ""
 347 { $code "T{ vector }" }
 348 "A BOA-form tuple:"
 349 { $code
 350     "USE: colors"
 351     "T{ rgba f 1.0 0.0 0.5 }"
 352 }
 353 "An assoc-form tuple equal to the above:"
 354 { $code
 355     "USE: colors"
 356     "T{ rgba { red 1.0 } { green 0.0 } { blue 0.5 } }"
 357 } } ;
 358
 359 HELP: W{
 360 { $syntax "W{ object }" }
 361 { $values { "object" "an object" } }
 362 { $description "Marks the beginning of a literal wrapper. Literal wrappers are terminated by " { $link POSTPONE: } } "." }  ;
 363
 364 HELP: POSTPONE:
 365 { $syntax "POSTPONE: word" }
 366 { $values { "word" "a word" } }
 367 { $description "Reads the next word from the input string and appends the word to the parse tree, even if it is a parsing word." }
 368 { $examples "For an ordinary word " { $snippet "foo" } ", " { $snippet "foo" } " and " { $snippet "POSTPONE: foo" } " are equivalent; however, if " { $snippet "foo" } " is a parsing word, the former will execute it at parse time, while the latter will execute it at runtime." }
 369 { $notes "This word is used inside parsing words to delegate further action to another parsing word, and to refer to parsing words literally from literal arrays and such." } ;
 370
 371 HELP: :
 372 { $syntax ": word ( stack -- effect ) definition... ;" }
 373 { $values { "word" "a new word to define" } { "definition" "a word definition" } }
 374 { $description "Defines a word with the given stack effect in the current vocabulary." }
 375 { $examples { $code ": ask-name ( -- name )\n    \"What is your name? \" write readln ;\n: greet ( name -- )\n    \"Greetings, \" write print ;\n: friend ( -- )\n    ask-name greet ;" } } ;
 376
 377 { POSTPONE: : POSTPONE: ; define } related-words
 378
 379 HELP: ;
 380 { $syntax ";" }
 381 { $description
 382     "Marks the end of a definition."
 383     $nl
 384     "Parsing words can use this word as a generic end delimiter."
 385 } ;
 386
 387 HELP: SYMBOL:
 388 { $syntax "SYMBOL: word" }
 389 { $values { "word" "a new word to define" } }
 390 { $description "Defines a new symbol word in the current vocabulary. Symbols push themselves on the stack when executed, and are used to identify variables (see " { $link "namespaces" } ") as well as for storing crufties in word properties (see " { $link "word-props" } ")." }
 391 { $examples { $example "USE: prettyprint" "IN: scratchpad" "SYMBOL: foo\nfoo ." "foo" } } ;
 392
 393 { define-symbol POSTPONE: SYMBOL: POSTPONE: SYMBOLS: } related-words
 394
 395 HELP: SYMBOLS:
 396 { $syntax "SYMBOLS: words... ;" }
 397 { $values { "words" "a sequence of new words to define" } }
 398 { $description "Creates a new symbol for every token until the " { $snippet ";" } "." }
 399 { $examples { $example "USING: prettyprint ;" "IN: scratchpad" "SYMBOLS: foo bar baz ;\nfoo . bar . baz ." "foo\nbar\nbaz" } } ;
 400
 401 HELP: SINGLETON:
 402 { $syntax "SINGLETON: class" }
 403 { $values
 404     { "class" "a new singleton to define" }
 405 }
 406 { $description
 407     "Defines a new singleton class. The class word itself is the sole instance of the singleton class."
 408 }
 409 { $examples
 410     { $example "USING: classes.singleton kernel io ;" "IN: singleton-demo" "USE: prettyprint SINGLETON: foo\nGENERIC: bar ( obj -- )\nM: foo bar drop \"a foo!\" print ;\nfoo bar" "a foo!" }
 411 } ;
 412
 413 HELP: SINGLETONS:
 414 { $syntax "SINGLETONS: words... ;" }
 415 { $values { "words" "a sequence of new words to define" } }
 416 { $description "Creates a new singleton for every token until the " { $snippet ";" } "." } ;
 417
 418 HELP: ALIAS:
 419 { $syntax "ALIAS: new-word existing-word" }
 420 { $values { "new-word" word } { "existing-word" word } }
 421 { $description "Creates a new inlined word that calls the existing word." }
 422 { $examples
 423     { $example "USING: prettyprint sequences ;"
 424                "IN: alias.test"
 425                "ALIAS: sequence-nth nth"
 426                "0 { 10 20 30 } sequence-nth ."
 427                "10"
 428     }
 429 } ;
 430
 431 { define-alias POSTPONE: ALIAS: } related-words
 432
 433 HELP: CONSTANT:
 434 { $syntax "CONSTANT: word value" }
 435 { $values { "word" word } { "value" object } }
 436 { $description "Creates a word which pushes a value on the stack." }
 437 { $examples { $code "CONSTANT: magic 1" "CONSTANT: science HEX: ff0f" } } ;
 438
 439 { define-constant POSTPONE: CONSTANT: } related-words
 440
 441 HELP: \
 442 { $syntax "\\ word" }
 443 { $values { "word" "a word" } }
 444 { $description "Reads the next word from the input and appends a wrapper holding the word to the parse tree. When the evaluator encounters a wrapper, it pushes the wrapped word literally on the data stack." }
 445 { $examples "The following two lines are equivalent:" { $code "0 \\ <vector> execute\n0 <vector>" } "If " { $snippet "foo" } " is a symbol, the following two lines are equivalent:" { $code "foo" "\\ foo" } } ;
 446
 447 HELP: DEFER:
 448 { $syntax "DEFER: word" }
 449 { $values { "word" "a new word to define" } }
 450 { $description "Create a word in the current vocabulary that simply raises an error when executed. Usually, the word will be replaced with a real definition later." }
 451 { $notes "Due to the way the parser works, words cannot be referenced before they are defined; that is, source files must order definitions in a strictly bottom-up fashion. Mutually-recursive pairs of words can be implemented by " { $emphasis "deferring" } " one of the words in the pair allowing the second word in the pair to parse, then by defining the first word." }
 452 { $examples { $code "DEFER: foe\n: fie ... foe ... ;\n: foe ... fie ... ;" } } ;
 453
 454 HELP: FORGET:
 455 { $syntax "FORGET: word" }
 456 { $values { "word" "a word" } }
 457 { $description "Removes the word from its vocabulary, or does nothing if no such word exists. Existing definitions that reference forgotten words will continue to work, but new occurrences of the word will not parse." } ;
 458
 459 HELP: USE:
 460 { $syntax "USE: vocabulary" }
 461 { $values { "vocabulary" "a vocabulary name" } }
 462 { $description "Adds a new vocabulary to the search path, loading it first if necessary." }
 463 { $notes "If adding the vocabulary introduces ambiguity, referencing the ambiguous names will throw a " { $link ambiguous-use-error } "." }
 464 { $errors "Throws an error if the vocabulary does not exist or could not be loaded." } ;
 465
 466 HELP: UNUSE:
 467 { $syntax "UNUSE: vocabulary" }
 468 { $values { "vocabulary" "a vocabulary name" } }
 469 { $description "Removes a vocabulary from the search path." }
 470 { $errors "Throws an error if the vocabulary does not exist." } ;
 471
 472 HELP: USING:
 473 { $syntax "USING: vocabularies... ;" }
 474 { $values { "vocabularies" "a list of vocabulary names" } }
 475 { $description "Adds a list of vocabularies to the search path." }
 476 { $notes "If adding the vocabularies introduces ambiguity, referencing the ambiguous names will throw a " { $link ambiguous-use-error } "." }
 477 { $errors "Throws an error if one of the vocabularies does not exist." } ;
 478
 479 HELP: QUALIFIED:
 480 { $syntax "QUALIFIED: vocab" }
 481 { $description "Adds the vocabulary's words, prefixed with the vocabulary name, to the search path." }
 482 { $notes "If adding the vocabulary introduces ambiguity, the vocabulary will take precedence when resolving any ambiguous names. This is a rare case; for example, suppose a vocabulary " { $snippet "fish" } " defines a word named " { $snippet "go:fishing" } ", and a vocabulary named " { $snippet "go" } " defines a word named " { $snippet "fishing" } ". Then, the following will call the latter word:"
 483   { $code
 484   "USE: fish"
 485   "QUALIFIED: go"
 486   "go:fishing"
 487   }
 488 }
 489 { $examples { $example
 490     "USING: prettyprint ;"
 491     "QUALIFIED: math"
 492     "1 2 math:+ ." "3"
 493 } } ;
 494
 495 HELP: QUALIFIED-WITH:
 496 { $syntax "QUALIFIED-WITH: vocab word-prefix" }
 497 { $description "Like " { $link POSTPONE: QUALIFIED: } " but uses " { $snippet "word-prefix" } " as prefix." }
 498 { $examples { $code
 499     "USING: prettyprint ;"
 500     "QUALIFIED-WITH: math m"
 501     "1 2 m:+ ."
 502     "3"
 503 } } ;
 504
 505 HELP: FROM:
 506 { $syntax "FROM: vocab => words ... ;" }
 507 { $description "Adds " { $snippet "words" } " from " { $snippet "vocab" } " to the search path." }
 508 { $notes "If adding the words introduces ambiguity, the words will take precedence when resolving any ambiguous names." }
 509 { $examples
 510   "Both the " { $vocab-link "vocabs.parser" } " and " { $vocab-link "binary-search" } " vocabularies define a word named " { $snippet "search" } ". The following will throw an " { $link ambiguous-use-error } ":"
 511   { $code "USING: vocabs.parser binary-search ;" "... search ..." }
 512   "Because " { $link POSTPONE: FROM: } " takes precedence over a " { $link POSTPONE: USING: } ", the ambiguity can be resolved explicitly. Suppose you wanted the " { $vocab-link "binary-search" } " vocabulary's " { $snippet "search" } " word:"
 513   { $code "USING: vocabs.parser binary-search ;" "FROM: binary-search => search ;" "... search ..." }
 514  } ;
 515
 516 HELP: EXCLUDE:
 517 { $syntax "EXCLUDE: vocab => words ... ;" }
 518 { $description "Adds all words except for " { $snippet "words" } " from " { $snippet "vocab" } "  to the search path." }
 519 { $examples { $code
 520     "EXCLUDE: math.parser => bin> hex> ;" "! imports everything but bin> and hex>" } } ;
 521
 522 HELP: RENAME:
 523 { $syntax "RENAME: word vocab => new-name" }
 524 { $description "Imports " { $snippet "word" } " from " { $snippet "vocab" } ", but renamed to " { $snippet "new-name" } "." }
 525 { $notes "If adding the words introduces ambiguity, the words will take precedence when resolving any ambiguous names." }
 526 { $examples { $example
 527     "USING: prettyprint ;"
 528     "RENAME: + math => -"
 529     "2 3 - ."
 530     "5"
 531 } } ;
 532
 533 HELP: IN:
 534 { $syntax "IN: vocabulary" }
 535 { $values { "vocabulary" "a new vocabulary name" } }
 536 { $description "Sets the current vocabulary where new words will be defined, creating the vocabulary first if it does not exist. After the vocabulary has been created, it can be listed in " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " declarations." } ;
 537
 538 HELP: CHAR:
 539 { $syntax "CHAR: token" }
 540 { $values { "token" "a literal character, escape code, or Unicode character name" } }
 541 { $description "Adds a Unicode code point to the parse tree." }
 542 { $examples
 543     { $code
 544         "CHAR: x"
 545         "CHAR: \\u000032"
 546         "CHAR: \\u{exclamation-mark}"
 547         "CHAR: exclamation-mark"
 548         "CHAR: ugaritic-letter-samka"
 549     }
 550 } ;
 551
 552 HELP: "
 553 { $syntax "\"string...\"" "\"\"\"string...\"\"\"" }
 554 { $values { "string" "literal and escaped characters" } }
 555 { $description "Reads from the input string until the next occurrence of " { $snippet "\"" } " or " { $snippet "\"\"\"" } ", and appends the resulting string to the parse tree. String literals can span multiple lines. Various special characters can be read by inserting " { $link "escape" } ". For triple quoted strings, the double-quote character does not require escaping." }
 556 { $examples
 557     "A string with an escaped newline in it:"
 558     { $example "USE: io" "\"Hello\\nworld\" print" "Hello\nworld" }
 559     "A string with an actual newline in it:"
 560     { $example "USE: io" "\"Hello\nworld\" print" "Hello\nworld" }
 561     "A string with a named Unicode code point:"
 562     { $example "USE: io" "\"\\u{greek-capital-letter-sigma}\" print" "\u{greek-capital-letter-sigma}" }
 563     "A triple-quoted string:"
 564     { $example "USE: io \"\"\"Teach a man to \"fish\"...\nand fish will go extinct\"\"\" print" """Teach a man to \"fish\"...
 565 and fish will go extinct""" }
 566 } ;
 567
 568 HELP: SBUF"
 569 { $syntax "SBUF\" string... \"" }
 570 { $values { "string" "literal and escaped characters" } }
 571 { $description "Reads from the input string until the next occurrence of " { $link POSTPONE: " } ", converts the string to a string buffer, and appends it to the parse tree." }
 572 { $examples { $example "USING: io strings ;" "SBUF\" Hello world\" >string print" "Hello world" } } ;
 573
 574 HELP: P"
 575 { $syntax "P\" pathname\"" }
 576 { $values { "pathname" "a pathname string" } }
 577 { $description "Reads from the input string until the next occurrence of " { $link POSTPONE: " } ", creates a new " { $link pathname } ", and appends it to the parse tree. Pathnames presented in the UI are clickable, which opens them in a text editor configured with " { $link "editor" } "." }
 578 { $examples { $example "USING: accessors io io.files ;" "P\" foo.txt\" string>> print" "foo.txt" } } ;
 579
 580 HELP: (
 581 { $syntax "( inputs -- outputs )" }
 582 { $values { "inputs" "a list of tokens" } { "outputs" "a list of tokens" } }
 583 { $description "A stack effect declaration. This is treated as a comment unless it appears inside a word definition." }
 584 { $see-also "effects" } ;
 585
 586 HELP: ((
 587 { $syntax "(( inputs -- outputs ))" }
 588 { $values { "inputs" "a list of tokens" } { "outputs" "a list of tokens" } }
 589 { $description "Literal stack effect syntax." }
 590 { $notes "Useful for meta-programming with " { $link define-declared } "." }
 591 { $examples
 592     { $example
 593         "USING: compiler.units kernel math prettyprint random words ;"
 594         "IN: scratchpad"
 595         ""
 596         "SYMBOL: my-dynamic-word"
 597         ""
 598         "["
 599         "    my-dynamic-word 2 { [ + ] [ * ] } random curry"
 600         "    (( x -- y )) define-declared"
 601         "] with-compilation-unit"
 602         ""
 603         "2 my-dynamic-word ."
 604         "4"
 605     }
 606 } ;
 607
 608 HELP: !
 609 { $syntax "! comment..." }
 610 { $values { "comment" "characters" } }
 611 { $description "Discards all input until the end of the line." } ;
 612
 613 { POSTPONE: ! POSTPONE: #! } related-words
 614
 615 HELP: #!
 616 { $syntax "#! comment..." }
 617 { $values { "comment" "characters" } }
 618 { $description "Discards all input until the end of the line." } ;
 619
 620 HELP: HEX:
 621 { $syntax "HEX: NNN" "HEX: NNN.NNNpEEE" }
 622 { $values { "N" "hexadecimal digit (0-9, a-f, A-F)" } { "pEEE" "decimal exponent value" } }
 623 { $description "Adds an integer or floating-point value read from a hexadecimal literal to the parse tree." }
 624 { $examples
 625     { $example "USE: prettyprint" "HEX: ff ." "255" }
 626     { $example "USE: prettyprint" "HEX: 1.8p5 ." "48.0" }
 627 } ;
 628
 629 HELP: OCT:
 630 { $syntax "OCT: integer" }
 631 { $values { "integer" "octal digits (0-7)" } }
 632 { $description "Adds an integer read from an octal literal to the parse tree." }
 633 { $examples { $example "USE: prettyprint" "OCT: 31337 ." "13023" } } ;
 634
 635 HELP: BIN:
 636 { $syntax "BIN: integer" }
 637 { $values { "integer" "binary digits (0 and 1)" } }
 638 { $description "Adds an integer read from an binary literal to the parse tree." }
 639 { $examples { $example "USE: prettyprint" "BIN: 100 ." "4" } } ;
 640
 641 HELP: NAN:
 642 { $syntax "NAN: payload" }
 643 { $values { "payload" "64-bit hexadecimal integer" } }
 644 { $description "Adds a floating point Not-a-Number literal to the parse tree." }
 645 { $examples
 646     { $example
 647         "USE: prettyprint"
 648         "NAN: 80000deadbeef ."
 649         "NAN: 80000deadbeef"
 650     }
 651 } ;
 652
 653 HELP: GENERIC:
 654 { $syntax "GENERIC: word ( stack -- effect )" }
 655 { $values { "word" "a new word to define" } }
 656 { $description "Defines a new generic word in the current vocabulary. Initially, it contains no methods, and thus will throw a " { $link no-method } " error when called." } ;
 657
 658 HELP: GENERIC#
 659 { $syntax "GENERIC# word n ( stack -- effect )" }
 660 { $values { "word" "a new word to define" } { "n" "the stack position to dispatch on" } }
 661 { $description "Defines a new generic word which dispatches on the " { $snippet "n" } "th most element from the top of the stack in the current vocabulary. Initially, it contains no methods, and thus will throw a " { $link no-method } " error when called." }
 662 { $notes
 663     "The following two definitions are equivalent:"
 664     { $code "GENERIC: foo ( obj -- )" }
 665     { $code "GENERIC# foo 0 ( obj -- )" }
 666 } ;
 667
 668 HELP: MATH:
 669 { $syntax "MATH: word" }
 670 { $values { "word" "a new word to define" } }
 671 { $description "Defines a new generic word which uses the " { $link math-combination } " method combination." } ;
 672
 673 HELP: HOOK:
 674 { $syntax "HOOK: word variable ( stack -- effect ) " }
 675 { $values { "word" "a new word to define" } { "variable" word } }
 676 { $description "Defines a new hook word in the current vocabulary. Hook words are generic words which dispatch on the value of a variable, so methods are defined with " { $link POSTPONE: M: } ". Hook words differ from other generic words in that the dispatch value is removed from the stack before the chosen method is called." }
 677 { $examples
 678     { $example
 679         "USING: io namespaces ;"
 680         "IN: scratchpad"
 681         "SYMBOL: transport"
 682         "TUPLE: land-transport ;"
 683         "TUPLE: air-transport ;"
 684         "HOOK: deliver transport ( destination -- )"
 685         "M: land-transport deliver \"Land delivery to \" write print ;"
 686         "M: air-transport deliver \"Air delivery to \"  write print ;"
 687         "T{ air-transport } transport set"
 688         "\"New York City\" deliver"
 689         "Air delivery to New York City"
 690     }
 691 }
 692 { $notes
 693     "Hook words are really just generic words with a custom method combination (see " { $link "method-combination" } ")."
 694 } ;
 695
 696 HELP: M:
 697 { $syntax "M: class generic definition... ;" }
 698 { $values { "class" "a class word" } { "generic" "a generic word" } { "definition" "a method definition" } }
 699 { $description "Defines a method, that is, a behavior for the generic word specialized on instances of the class." } ;
 700
 701 HELP: UNION:
 702 { $syntax "UNION: class members... ;" }
 703 { $values { "class" "a new class word to define" } { "members" "a list of class words separated by whitespace" } }
 704 { $description "Defines a union class. An object is an instance of a union class if it is an instance of one of its members." } ;
 705
 706 HELP: INTERSECTION:
 707 { $syntax "INTERSECTION: class participants... ;" }
 708 { $values { "class" "a new class word to define" } { "participants" "a list of class words separated by whitespace" } }
 709 { $description "Defines an intersection class. An object is an instance of an intersection class if it is an instance of all of its participants." } ;
 710
 711 HELP: MIXIN:
 712 { $syntax "MIXIN: class" }
 713 { $values { "class" "a new class word to define" } }
 714 { $description "Defines a mixin class. A mixin is similar to a union class, except it has no members initially, and new members can be added with the " { $link POSTPONE: INSTANCE: } " word." }
 715 { $examples "The " { $link sequence } " and " { $link assoc } " mixin classes." } ;
 716
 717 HELP: INSTANCE:
 718 { $syntax "INSTANCE: instance mixin" }
 719 { $values { "instance" "a class word" } { "mixin" "a mixin class word" } }
 720 { $description "Makes " { $snippet "instance" } " an instance of " { $snippet "mixin" } "." } ;
 721
 722 HELP: PREDICATE:
 723 { $syntax "PREDICATE: class < superclass predicate... ;" }
 724 { $values { "class" "a new class word to define" } { "superclass" "an existing class word" } { "predicate" "membership test with stack effect " { $snippet "( superclass -- ? )" } } }
 725 { $description
 726     "Defines a predicate class deriving from " { $snippet "superclass" } "."
 727     $nl
 728     "An object is an instance of a predicate class if two conditions hold:"
 729     { $list
 730         "it is an instance of the predicate's superclass,"
 731         "it satisfies the predicate"
 732     }
 733     "Each predicate must be defined as a subclass of some other class. This ensures that predicates inheriting from disjoint classes do not need to be exhaustively tested during method dispatch."
 734 }
 735 { $examples
 736     { $code "USING: math ;" "PREDICATE: positive < integer 0 > ;" }
 737 } ;
 738
 739 HELP: TUPLE:
 740 { $syntax "TUPLE: class slots... ;" "TUPLE: class < superclass slots ... ;" }
 741 { $values { "class" "a new tuple class to define" } { "slots" "a list of slot specifiers" } }
 742 { $description "Defines a new tuple class."
 743 $nl
 744 "The superclass is optional; if left unspecified, it defaults to " { $link tuple } "."
 745 $nl
 746 "Slot specifiers take one of the following three forms:"
 747 { $list
 748     { { $snippet "name" } " - a slot which can hold any object, with no attributes" }
 749     { { $snippet "{ name attributes... }" } " - a slot which can hold any object, with optional attributes" }
 750     { { $snippet "{ name class attributes... }" } " - a slot specialized to a specific class, with optional attributes" }
 751 }
 752 "Slot attributes are lists of slot attribute specifiers followed by values; a slot attribute specifier is one of " { $link initial: } " or " { $link read-only } ". See " { $link "tuple-declarations" } " for details." }
 753 { $examples
 754     "A simple tuple class:"
 755     { $code "TUPLE: color red green blue ;" }
 756     "Declaring slots to be integer-valued:"
 757     { $code "TUPLE: color" "{ red integer }" "{ green integer }" "{ blue integer } ;" }
 758     "An example mixing short and long slot specifiers:"
 759     { $code "TUPLE: person" "{ age integer initial: 0 }" "{ department string initial: \"Marketing\" }" "manager ;" }
 760 } ;
 761
 762 HELP: initial:
 763 { $syntax "TUPLE: ... { slot initial: value } ... ;" }
 764 { $values { "slot" "a slot name" } { "value" "any literal" } }
 765 { $description "Specifies an initial value for a tuple slot." } ;
 766
 767 HELP: read-only
 768 { $syntax "TUPLE: ... { slot read-only } ... ;" }
 769 { $values { "slot" "a slot name" } }
 770 { $description "Defines a tuple slot to be read-only. If a tuple has read-only slots, instances of the tuple should only be created by calling " { $link boa } ", instead of " { $link new } ". Using " { $link boa } " is the only way to set the value of a read-only slot." } ;
 771
 772 { initial: read-only } related-words
 773
 774 HELP: SLOT:
 775 { $syntax "SLOT: name" }
 776 { $values { "name" "a slot name" } }
 777 { $description "Defines a protocol slot; that is, defines the accessor words for a slot named " { $snippet "slot" } " without associating it with any specific tuple." } ;
 778
 779 HELP: ERROR:
 780 { $syntax "ERROR: class slots... ;" }
 781 { $values { "class" "a new tuple class to define" } { "slots" "a list of slot names" } }
 782 { $description "Defines a new tuple class whose class word throws a new instance of the error." }
 783 { $notes
 784     "The following two snippets are equivalent:"
 785     { $code
 786         "ERROR: invalid-values x y ;"
 787         ""
 788         "TUPLE: invalid-values x y ;"
 789         ": invalid-values ( x y -- * )"
 790         "    \\ invalid-values boa throw ;"
 791     }
 792 } ;
 793
 794 HELP: C:
 795 { $syntax "C: constructor class" }
 796 { $values { "constructor" "a new word to define" } { "class" tuple-class } }
 797 { $description "Define a constructor word for a tuple class which simply performs BOA (by order of arguments) construction using " { $link boa } "." }
 798 { $examples
 799     "Suppose the following tuple has been defined:"
 800     { $code "TUPLE: color red green blue ;" }
 801     "The following two lines are equivalent:"
 802     { $code
 803         "C: <color> color"
 804         ": <color> color boa ;"
 805     }
 806     "In both cases, a word " { $snippet "<color>" } " is defined, which reads three values from the stack and creates a " { $snippet "color" } " instance having these values in the " { $snippet "red" } ", " { $snippet "green" } " and " { $snippet "blue" } " slots, respectively."
 807 } ;
 808
 809 HELP: MAIN:
 810 { $syntax "MAIN: word" }
 811 { $values { "word" word } }
 812 { $description "Defines the main entry point for the current vocabulary. This word will be executed when this vocabulary is passed to " { $link run } "." } ;
 813
 814 HELP: <PRIVATE
 815 { $syntax "<PRIVATE ... PRIVATE>" }
 816 { $description "Begins a block of private word definitions. Private word definitions are placed in the current vocabulary name, suffixed with " { $snippet ".private" } "." }
 817 { $notes
 818     "The following is an example of usage:"
 819     { $code
 820         "IN: factorial"
 821         ""
 822         "<PRIVATE"
 823         ""
 824         ": (fac) ( accum n -- n! )"
 825         "    dup 1 <= [ drop ] [ [ * ] keep 1 - (fac) ] if ;"
 826         ""
 827         "PRIVATE>"
 828         ""
 829         ": fac ( n -- n! ) 1 swap (fac) ;"
 830     }
 831     "The above is equivalent to:"
 832     { $code
 833         "IN: factorial.private"
 834         ""
 835         ": (fac) ( accum n -- n! )"
 836         "    dup 1 <= [ drop ] [ [ * ] keep 1 - (fac) ] if ;"
 837         ""
 838         "IN: factorial"
 839         ""
 840         ": fac ( n -- n! ) 1 swap (fac) ;"
 841     }
 842 } ;
 843
 844 HELP: PRIVATE>
 845 { $syntax "<PRIVATE ... PRIVATE>" }
 846 { $description "Ends a block of private word definitions." } ;
 847
 848 { POSTPONE: <PRIVATE POSTPONE: PRIVATE> } related-words
 849
 850 HELP: <<
 851 { $syntax "<< ... >>" }
 852 { $description "Evaluates some code at parse time." }
 853 { $notes "Calling words defined in the same source file at parse time is prohibited; see compilation unit as where it was defined; see " { $link "compilation-units" } "." } ;
 854
 855 HELP: >>
 856 { $syntax ">>" }
 857 { $description "Marks the end of a parse time code block." } ;
 858
 859 HELP: call-next-method
 860 { $syntax "call-next-method" }
 861 { $description "Calls the next applicable method. Only valid inside a method definition. The values at the top of the stack are passed on to the next method, and they must be compatible with that method's class specializer." }
 862 { $notes "This word looks like an ordinary word but it is a parsing word. It cannot be factored out of a method definition, since the code expansion references the current method object directly." }
 863 { $errors
 864     "Throws a " { $link no-next-method } " error if this is the least specific method, and throws an " { $link inconsistent-next-method } " error if the values at the top of the stack are not compatible with the current method's specializer."
 865 } ;
 866
 867 { POSTPONE: call-next-method (call-next-method) next-method } related-words
 868
 869 { POSTPONE: << POSTPONE: >> } related-words
 870
 871 HELP: call(
 872 { $syntax "call( stack -- effect )" }
 873 { $description "Calls the quotation on the top of the stack, asserting that it has the given stack effect. The quotation does not need to be known at compile time." }
 874 { $examples
 875   { $code
 876     "TUPLE: action name quot ;"
 877     ": perform-action ( action -- )"
 878     "    [ name>> print ] [ quot>> call( -- ) ] bi ;"
 879   }
 880 } ;
 881
 882 HELP: execute(
 883 { $syntax "execute( stack -- effect )" }
 884 { $description "Calls the word on the top of the stack, asserting that it has the given stack effect. The word does not need to be known at compile time." }
 885 { $examples
 886   { $code
 887     "IN: scratchpad"
 888     ""
 889     ": eat ( -- ) ; : sleep ( -- ) ; : hack ( -- ) ;"
 890     "{ eat sleep hack } [ execute( -- ) ] each"
 891   }
 892 } ;
 893
 894 { POSTPONE: call( POSTPONE: execute( } related-words