core/syntax/parse-syntax.facts

   1 USING: generic help kernel math modules parser words ;
   2
   3 HELP: parsing
   4 { $syntax "parsing" }
   5 { $description "Declares the most recently defined word as a parsing word." }
   6 { $examples "In the below example, the " { $snippet "world" } " word is never called, however its body references a parsing word which executes immediately:" { $example ": hello \"Hello parser!\" print ; parsing\n: world hello ;" "Hello parser!" } } ;
   7
   8 HELP: inline
   9 { $syntax "inline" }
  10 { $description
  11     "Declares the most recently defined word as an inline word."
  12     $terpri
  13     "Combinators must be inlined in order to compile - see " { $link "inference-combinators" } ". For any other word, inlining is merely an optimization. Inlining does not affect the execution of the word in the interpreter."
  14 } ;
  15
  16 HELP: foldable
  17 { $syntax "foldable " }
  18 { $description
  19     "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:"
  20     { $list
  21         "foldable words must not have any observable side effects,"
  22         "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."
  23         "both inputs and outputs of foldable words must be immutable."
  24     }
  25     "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."
  26 }
  27 { $examples "Most operations on numbers are foldable. For example, " { $snippet "2 2 +" } " compiles to a literal 4, since " { $link + } " is declared foldable." } ;
  28
  29 HELP: t
  30 { $syntax "t" }
  31 { $values { "t" "the canonical truth value" } }
  32 { $description "The canonical instance of " { $link general-t } ". It is just a symbol." } ;
  33
  34 HELP: f
  35 { $syntax "f" }
  36 { $values { "f" "the singleton false value" } }
  37 { $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:"
  38 { $code "f    ! the singleton f object denoting falsity\n\\ f  ! the f class word" } } ;
  39
  40 HELP: [
  41 { $syntax "[ elements... ]" }
  42 { $description "Marks the beginning of a literal quotation." }
  43 { $examples { $code "[ 1 2 3 ]" } }
  44 { $see-also POSTPONE: ] } ;
  45
  46 HELP: ]
  47 { $syntax "]" }
  48 { $description "Marks the end of a literal quotation." }
  49 { $see-also POSTPONE: [ } ;
  50
  51 HELP: }
  52 { $syntax "}" }
  53 { $description "Marks the end of an array, vector, hashtable, complex number, tuple, or wrapper." }
  54 { $see-also POSTPONE: { POSTPONE: V{ POSTPONE: H{ POSTPONE: C{ POSTPONE: T{ POSTPONE: W{ } ;
  55
  56 HELP: {
  57 { $syntax "{ elements... }" }
  58 { $values { "elements" "a list of objects" } }
  59 { $description "Marks the beginning of a literal array." }
  60 { $examples { $code "{ 1 2 3 }" } } ;
  61
  62 HELP: V{
  63 { $syntax "V{ elements... }" }
  64 { $values { "elements" "a list of objects" } }
  65 { $description "Marks the beginning of a literal vector." }
  66 { $examples { $code "V{ 1 2 3 }" } } ;
  67
  68 HELP: H{
  69 { $syntax "H{ { key value }... }" }
  70 { $values { "key" "an object" } { "value" "an object" } }
  71 { $description "Marks the beginning of a literal hashtable, given as a list of two-element arrays holding key/value pairs." }
  72 { $examples { $code "H{ { \"tuna\" \"fish\" } { \"jalapeno\" \"vegetable\" } }" } } ;
  73
  74 HELP: C{
  75 { $syntax "C{ real imaginary }" }
  76 { $values { "real" "a real number" } { "imaginary" "a real number" } }
  77 { $description "Parses a complex number given in rectangular form as a pair of real numbers." } ;
  78
  79 HELP: T{
  80 { $syntax "T{ class delegate slots... }" }
  81 { $values { "class" "a tuple class word" } { "delegate" "a delegate" } { "slots" "list of objects" } }
  82 { $description "Marks the beginning of a literal tuple. The class word must always be specified. If an insufficient number of values is given after the class word, the remaining slots of the tuple are set to " { $link f } ". If too many values are given, an error is thrown." } ;
  83
  84 HELP: W{
  85 { $syntax "W{ object }" }
  86 { $values { "object" "an object" } }
  87 { $description "Marks the beginning of a literal wrapper." }
  88 { $see-also POSTPONE: \ <wrapper> literalize } ;
  89
  90 HELP: POSTPONE:
  91 { $syntax "POSTPONE: word" }
  92 { $values { "word" "a word" } }
  93 { $description "Reads the next word from the input string and appends the word to the parse tree, even if it is a parsing word." }
  94 { $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." }
  95 { $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." } ;
  96
  97 HELP: :
  98 { $syntax ": word definition... ;" }
  99 { $values { "word" "a new word to define" } { "definition" "a word definition" } }
 100 { $description "Defines a compound word in the current vocabulary." }
 101 { $examples { $code ": ask-name ( -- name )\n    \"What is your name? \" write readln ;\n: greet ( name -- )    \"Greetings, \" write print ;\n: friend ( -- )    ask-name greet ;" } }
 102 { $see-also POSTPONE: ; define-compound } ;
 103
 104 HELP: ;
 105 { $syntax ";" }
 106 { $description
 107     "Marks the end of a definition."
 108     $terpri
 109     "Parsing words can use this word as a generic end delimiter. It has parse-time stack effect " { $snippet "( definer parsed -- )" } "; when parsed, it reverses the " { $snippet "parsed" } " quotation, and passes it as input to the " { $snippet "definer" } " quotation."
 110 }
 111 { $see-also POSTPONE: : POSTPONE: G: POSTPONE: M: POSTPONE: C: POSTPONE: UNION: POSTPONE: PREDICATE: POSTPONE: USING: } ;
 112
 113 HELP: SYMBOL:
 114 { $syntax "SYMBOL: word" }
 115 { $values { "word" "a new word to define" } }
 116 { $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" } ")." }
 117 { $examples { $example "SYMBOL: foo\nfoo ." "foo" } } ;
 118
 119 HELP: \
 120 { $syntax "\\ word" }
 121 { $values { "word" "a word" } }
 122 { $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." }
 123 { $examples "The following two lines are equivalent:" { $code "0 \\ <vector> execute\n0 <vector>" } } ;
 124
 125 HELP: DEFER:
 126 { $syntax "DEFER: word" }
 127 { $values { "word" "a new word to define" } }
 128 { $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." }
 129 { $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." }
 130 { $examples { $code "DEFER: foe\n: fie ... foe ... ;\n: foe ... fie ... ;" } } ;
 131
 132 HELP: FORGET:
 133 { $syntax "FORGET: word" }
 134 { $values { "word" "a word" } }
 135 { $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." } ;
 136
 137 HELP: USE:
 138 { $syntax "USE: vocabulary" }
 139 { $values { "vocabulary" "a vocabulary name" } }
 140 { $description "Adds a new vocabulary at the front of the search path. Subsequent word lookups by the parser will search this vocabulary first." }
 141 { $errors "Throws an error if the vocabulary does not exist." } ;
 142
 143 HELP: USING:
 144 { $syntax "USING: vocabularies... ;" }
 145 { $values { "vocabularies" "a list of vocabulary names" } }
 146 { $description "Adds a list of vocabularies to the front of the search path, with later vocabularies taking precedence." }
 147 { $errors "Throws an error if one of the vocabularies does not exist." } ;
 148
 149 HELP: IN:
 150 { $syntax "IN: vocabulary" }
 151 { $values { "vocabulary" "a new vocabulary name" } }
 152 { $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." } ;
 153
 154 HELP: CHAR:
 155 { $syntax "CHAR: token" }
 156 { $values { "token" "a literal character or escape code" } }
 157 { $description "Adds the Unicode code point of the character represented by the token to the parse tree." } ;
 158
 159 HELP: "
 160 { $syntax "\"string...\"" }
 161 { $values { "string" "literal and escaped characters" } }
 162 { $description "Reads from the input string until the next occurrence of " { $link POSTPONE: " } ", and appends the resulting string to the parse tree. String literals cannot span multiple lines. Strings containing the " { $link POSTPONE: " } " character and various other special characters can be read by inserting escape sequences." }
 163 { $examples { $example "\"Hello\\nworld\" print" "Hello\nworld" } } ;
 164
 165 HELP: SBUF"
 166 { $syntax "SBUF\" string... \"" }
 167 { $values { "string" "literal and escaped characters" } }
 168 { $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." }
 169 { $examples { $example "SBUF\" Hello world\" >string print" "Hello world" } } ;
 170
 171 HELP: (
 172 { $syntax "( inputs -- outputs )" }
 173 { $values { "inputs" "a list of tokens" } { "outputs" "a list of tokens" } }
 174 { $description "Declares the stack effect of the most recently defined word, storing a new " { $link effect } " instance in the " { $snippet "\"declared-effect\"" } " word property." }
 175 { $notes "Recursive words must have a declared stack effect to compile. See " { $link "effect-declaration" } " for details." } ;
 176
 177 HELP: !
 178 { $syntax "! comment..." }
 179 { $values { "comment" "characters" } }
 180 { $description "Discards all input until the end of the line." }
 181 { $see-also POSTPONE: #! } ;
 182
 183 HELP: #!
 184 { $syntax "#! comment..." }
 185 { $values { "comment" "characters" } }
 186 { $description "Discards all input until the end of the line." }
 187 { $see-also POSTPONE: ! } ;
 188
 189 HELP: HEX:
 190 { $syntax "HEX: integer" }
 191 { $values { "integer" "hexadecimal digits (0-9, a-f, A-F)" } }
 192 { $description "Adds an integer read from a hexadecimal literal to the parse tree." }
 193 { $examples { $example "HEX: ff ." "255" } } ;
 194
 195 HELP: OCT:
 196 { $syntax "OCT: integer" }
 197 { $values { "integer" "octal digits (0-7)" } }
 198 { $description "Adds an integer read from an octal literal to the parse tree." }
 199 { $examples { $example "OCT: 31337 ." "13023" } } ;
 200
 201 HELP: BIN:
 202 { $syntax "BIN: integer" }
 203 { $values { "integer" "binary digits (0 and 1)" } }
 204 { $description "Adds an integer read from an binary literal to the parse tree." }
 205 { $examples { $example "BIN: 100 ." "4" } } ;
 206
 207 HELP: GENERIC:
 208 { $syntax "GENERIC: word" }
 209 { $values { "word" "a new word to define" } }
 210 { $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." }
 211 { $notes
 212     "A " { $link "method-combination" } " facility exists for customizing method dispatch behavior."
 213     $terpri
 214     "This parsing word is equivalent to the following usage of the more general " { $link POSTPONE: G: } " word:"
 215     { $code "G: word 0 standard-combination ;" }
 216 }
 217 { $see-also define-generic } ;
 218
 219 HELP: G:
 220 { $syntax "G: word combination... ;" }
 221 { $values { "word" "a new word to define" } { "combination" "a method combination definition with stack effect " { $snippet "( word -- quot )" } } }
 222 { $description "Defines a generic word using the long-form. A method combination is a quotation that is given the generic word on the stack, and outputs a quotation " { $emphasis "that becomes the definition of the word" } "." }
 223 { $contract "The method combination quotation is called each time the generic word has to be updated (for example, when a method is added), and thus must be side-effect free." }
 224 { $see-also define-generic* } ;
 225
 226 HELP: M:
 227 { $syntax "M: class generic definition... ;" }
 228 { $values { "class" "a class word" } { "generic" "a generic word" } { "definition" "a method definition" } }
 229 { $description "Defines a method, that is, a behavior for the generic word specialized on instances of the class." }
 230 { $see-also define-method } ;
 231
 232 HELP: UNION:
 233 { $syntax "UNION: class members... ;" }
 234 { $values { "class" "a new class word to define" } { "members" "a list of class words separated by whitespace" } }
 235 { $description "Defines a union class. An object is an instance of a union class if it is an instance of one of its members." }
 236 { $notes "Union classes are used to associate the same method with several different classes, as well as to conveniently define predicates." }
 237 { $see-also define-union } ;
 238
 239 HELP: PREDICATE:
 240 { $syntax "PREDICATE: superclass class predicate... ;" }
 241 { $values { "superclass" "an existing class word" } { "class" "a new class word to define" } { "predicate" "membership test with stack effect " { $snippet "( superclass -- ? )" } } }
 242 { $description
 243     "Defines a predicate class deriving from " { $snippet "superclass" } "."
 244     $terpri
 245     "An object is an instance of a predicate class if two conditions hold:"
 246     { $list
 247         "it is an instance of the predicate's superclass,"
 248         "it satisfies the predicate"
 249     }
 250     "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."
 251 }
 252 { $see-also define-predicate-class } ;
 253
 254 HELP: TUPLE:
 255 { $syntax "TUPLE: class slots... ;" }
 256 { $values { "class" "a new class word to define" } { "slots" "a list of slot names" } }
 257 { $description "Defines a new tuple class with membership predicate " { $snippet "name?" } " and constructor " { $snippet "<name>" } "."
 258 $terpri
 259 "Tuples are user-defined classes with instances composed of named slots. All tuple classes are subtypes of the built-in " { $link tuple } " type." }
 260 { $see-also define-tuple } ;
 261
 262 HELP: C:
 263 { $syntax "C: class definition... ;" }
 264 { $values { "class" "a class word" } { "definition" "a constructor definition" } }
 265 { $description "Define a constructor word for a tuple class. The constructor definition receives a new instance of the class on the stack, with all slots initially set to " { $link f } "."
 266 $terpri
 267 "Constructors are named after the tuple class surrounded in angle brackets: " { $snippet "<" } " and " { $snippet ">" } ". Constructor words are defined in the same vocabulary as the tuple class, and the current value of the " { $link in } " variable has no effect."  }
 268 { $contract "The definition must only have one output, the new tuple itself." }
 269 { $notes "Each tuple class defines a default constructor that reads slot values from the stack. This parsing word redefines the default constructor." }
 270 { $see-also define-constructor } ;
 271
 272 HELP: REQUIRES:
 273 { $syntax "REQUIRES: modules... ;" }
 274 { $values { "modules" "module name strings" } }
 275 { $description "Loads a list of modules by calling " { $link require } " on each one." } ;
 276
 277 HELP: PROVIDE:
 278 { $syntax "PROVIDE: name pairs... ;" }
 279 { $values { "name" "a string" } { "pairs" "a sequence of pairs, with keys described below" } }
 280 { $description "Registers a module definition and loads its source files by calling " { $link provide } "."
 281 $terpri
 282 "The module name is followed by key/value pairs, where the keys are drawn from the following set:"
 283 { $list
 284     { { $link +files+ } " - the value is a sequence of source file names" }
 285     { { $link +tests+ } " - the value is a sequence of unit test file names" }
 286     { { $link +help+ } " - the value is a help topic" }
 287 }
 288 "All keys are optional, and path names are relative to the main module directory."
 289 $terpri
 290 "Elements of path name lists can optionally be pairs, where the first element is a source file which is conditionally loaded if the quotation in the second element yields a true value." }
 291 { $examples
 292 "An example where the conditional load feature is used to load platform-specific code:"
 293 { $code
 294 "PROVIDE: libs/calendar"
 295 "{ +files+ {"
 296 "    { \"os-unix.factor\" [ unix? ] }"
 297 "    { \"os-win32.factor\" [ windows? ] }"
 298 "    \"calendar.factor\""
 299 "} }"
 300 "{ +tests+ { \"test/calendar.factor\" } } ;"
 301 } } ;
 302
 303 HELP: MAIN:
 304 { $syntax "MAIN: name definition... ;" }
 305 { $values { "name" "a module name string" } { "definition" "an entry point definition" } }
 306 { $description "Registers a module entry point which can be run by passing the module name to " { $link run-module } ". The entry point quotation must not take any inputs from the stack, or leave any values on the stack when returning." } ;
 307
 308 HELP: +files+
 309 { $description "A key which may appear in a " { $link POSTPONE: PROVIDE: } " form." } ;
 310
 311 HELP: +tests+
 312 { $description "A key which may appear in a " { $link POSTPONE: PROVIDE: } " form." } ;
 313
 314 HELP: +help+
 315 { $description "A key which may appear in a " { $link POSTPONE: PROVIDE: } " form." } ;
 316
 317 HELP: +directory+
 318 { $description "A key which may appear in a " { $link POSTPONE: PROVIDE: } " form." } ;