USING: generic help.syntax help.markup kernel math parser words
effects classes classes.tuple generic.math generic.single arrays
io.pathnames vocabs.loader io sequences assocs words.symbol
-words.alias words.constant combinators vocabs.parser ;
+words.alias words.constant combinators vocabs.parser command-line ;
IN: syntax
ARTICLE: "parser-algorithm" "Parser algorithm"
"More information on integers can be found in " { $link "integers" } "." ;
ARTICLE: "syntax-ratios" "Ratio syntax"
-"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:"
+"The printed representation of a ratio is a pair of integers separated by a slash (" { $snippet "/" } "). A ratio can also be written as a proper fraction by following an integer part with " { $snippet "+" } " or " { $snippet "-" } " (matching the sign of the integer) and a ratio. No intermediate whitespace is permitted within a ratio literal. Here are some examples:"
{ $code
"75/33"
"1/10"
"-5/-6"
"1+1/3"
- "-10+1/7"
+ "-10-1/7"
}
-"More information on ratios can be found in " { $link "rationals" } ;
+"More information on ratios can be found in " { $link "rationals" } "." ;
ARTICLE: "syntax-floats" "Float syntax"
-"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" } ":"
+"Floating point literals are specified when a literal number contains a decimal point or exponent. Exponents are marked by an " { $snippet "e" } " or " { $snippet "E" } ":"
{ $code
"10.5"
"-3.1456"
- "7.e13"
+ "7e13"
"1.0e-5"
+ "1.0E+5"
}
-"Base 16 literals use " { $snippet "p" } " instead of " { $snippet "e" } " for the exponent, which is still decimal:"
+"Literal numbers without a decimal point or an exponent always parse as integers:"
{ $example
- "10.125 HEX: 1.44p3 = ."
+ "1 float? ."
+ "f"
+}
+{ $example
+ "1. float? ."
+ "t"
+}
+{ $example
+ "1e0 float? ."
"t"
}
-"Syntax for special float values:"
+"Literal floating point approximations of ratios can also be input by placing a decimal point in the denominator:"
+{ $example
+ "1/2. ."
+ "0.5"
+}
+{ $example
+ "1/3. ."
+ "0.3333333333333333"
+}
+"The special float values have their own syntax:"
{ $table
{ "Positive infinity" { $snippet "1/0." } }
{ "Negative infinity" { $snippet "-1/0." } }
{ "Not-a-number" { $snippet "0/0." } }
}
-"A Not-a-number with an arbitrary payload can also be parsed in:"
+"A Not-a-number literal with an arbitrary payload can also be input:"
{ $subsections POSTPONE: NAN: }
+"Hexadecimal float literals are also supported. These consist of a hexadecimal literal with a decimal point and an optional base-two exponent expressed as a decimal number after " { $snippet "p" } " or " { $snippet "P" } ":"
+{ $example
+ "8.0 0x1.0p3 = ."
+ "t"
+}
+{ $example
+ "1024.0 0x1.0P10 = ."
+ "t"
+}
+{ $example
+ "10.125 0x1.44p3 = ."
+ "t"
+}
+"The normalized hex form " { $snippet "HEX: ±1.MMMMMMMMMMMMMp±EEEE" } " allows any floating-point number to be specified precisely. The values of MMMMMMMMMMMMM and EEEE map directly to the mantissa and exponent fields of IEEE 754 representation."
+$nl
"More information on floats can be found in " { $link "floats" } "." ;
ARTICLE: "syntax-complex-numbers" "Complex number syntax"
{ $subsections POSTPONE: H{ }
"Hashtables are documented in " { $link "hashtables" } "." ;
+ARTICLE: "syntax-hash-sets" "Hash set syntax"
+{ $subsections POSTPONE: HS{ }
+"Hashtables are documented in " { $link "hash-sets" } "." ;
+
ARTICLE: "syntax-tuples" "Tuple syntax"
{ $subsections POSTPONE: T{ }
-"Tuples are documented in " { $link "tuples" } "." ;
+"Tuples are documented in " { $link "tuples" } "." ;
ARTICLE: "syntax-quots" "Quotation syntax"
{ $subsections
ARTICLE: "syntax-effects" "Stack effect syntax"
"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 } "."
-{ $subsections POSTPONE: (( }
+{ $subsections POSTPONE: ( }
{ $see-also "effects" "inference" "tools.inference" } ;
ARTICLE: "syntax-literals" "Literals"
"syntax-vectors"
"syntax-sbufs"
"syntax-hashtables"
+ "syntax-hash-sets"
"syntax-tuples"
"syntax-pathnames"
"syntax-effects"
$nl
"Parsing words can use this word as a generic end delimiter." } ;
-{ POSTPONE: { POSTPONE: V{ POSTPONE: H{ POSTPONE: C{ POSTPONE: T{ POSTPONE: W{ POSTPONE: } } related-words
+{ POSTPONE: { POSTPONE: V{ POSTPONE: H{ POSTPONE: HS{ POSTPONE: C{ POSTPONE: T{ POSTPONE: W{ POSTPONE: } } related-words
HELP: {
{ $syntax "{ elements... }" }
{ $values { "elements" "a list of objects" } }
-{ $description "Marks the beginning of a literal array. Literal arrays are terminated by " { $link POSTPONE: } } "." }
+{ $description "Marks the beginning of a literal array. Literal arrays are terminated by " { $link POSTPONE: } } "." }
{ $examples { $code "{ 1 2 3 }" } } ;
HELP: V{
{ $syntax "V{ elements... }" }
{ $values { "elements" "a list of objects" } }
-{ $description "Marks the beginning of a literal vector. Literal vectors are terminated by " { $link POSTPONE: } } "." }
+{ $description "Marks the beginning of a literal vector. Literal vectors are terminated by " { $link POSTPONE: } } "." }
{ $examples { $code "V{ 1 2 3 }" } } ;
HELP: B{
{ $syntax "B{ elements... }" }
{ $values { "elements" "a list of integers" } }
-{ $description "Marks the beginning of a literal byte array. Literal byte arrays are terminated by " { $link POSTPONE: } } "." }
+{ $description "Marks the beginning of a literal byte array. Literal byte arrays are terminated by " { $link POSTPONE: } } "." }
{ $examples { $code "B{ 1 2 3 }" } } ;
HELP: H{
{ $syntax "H{ { key value }... }" }
{ $values { "key" "an object" } { "value" "an object" } }
-{ $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: } } "." }
+{ $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: } } "." }
{ $examples { $code "H{ { \"tuna\" \"fish\" } { \"jalapeno\" \"vegetable\" } }" } } ;
+HELP: HS{
+{ $syntax "HS{ members ... }" }
+{ $values { "members" "a list of objects" } }
+{ $description "Marks the beginning of a literal hash set, given as a list of its members. Literal hashtables are terminated by " { $link POSTPONE: } } "." }
+{ $examples { $code "HS{ 3 \"foo\" }" } } ;
+
HELP: C{
{ $syntax "C{ real-part imaginary-part }" }
{ $values { "real-part" "a real number" } { "imaginary-part" "a real number" } }
-{ $description "Parses a complex number given in rectangular form as a pair of real numbers. Literal complex numbers are terminated by " { $link POSTPONE: } } "." } ;
+{ $description "Parses a complex number given in rectangular form as a pair of real numbers. Literal complex numbers are terminated by " { $link POSTPONE: } } "." } ;
HELP: T{
{ $syntax "T{ class }" "T{ class f slot-values... }" "T{ class { slot-name slot-value } ... }" }
{ $examples
{ $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!" }
} ;
-
+
HELP: SINGLETONS:
{ $syntax "SINGLETONS: words... ;" }
{ $values { "words" "a sequence of new words to define" } }
{ $syntax "CONSTANT: word value" }
{ $values { "word" word } { "value" object } }
{ $description "Creates a word which pushes a value on the stack." }
-{ $examples { $code "CONSTANT: magic 1" "CONSTANT: science HEX: ff0f" } } ;
+{ $examples { $code "CONSTANT: magic 1" "CONSTANT: science 0xff0f" } } ;
{ define-constant POSTPONE: CONSTANT: } related-words
{ $examples { $example
"USING: prettyprint ;"
"QUALIFIED: math"
- "1 2 math:+ ." "3"
+ "1 2 math:+ ."
+ "3"
} } ;
HELP: QUALIFIED-WITH:
{ $syntax "QUALIFIED-WITH: vocab word-prefix" }
{ $description "Like " { $link POSTPONE: QUALIFIED: } " but uses " { $snippet "word-prefix" } " as prefix." }
-{ $examples { $code
+{ $examples { $example
"USING: prettyprint ;"
"QUALIFIED-WITH: math m"
"1 2 m:+ ."
HELP: EXCLUDE:
{ $syntax "EXCLUDE: vocab => words ... ;" }
-{ $description "Adds all words except for " { $snippet "words" } " from " { $snippet "vocab" } " to the search path." }
+{ $description "Adds all words except for " { $snippet "words" } " from " { $snippet "vocab" } " to the search path." }
{ $examples { $code
"EXCLUDE: math.parser => bin> hex> ;" "! imports everything but bin> and hex>" } } ;
HELP: (
{ $syntax "( inputs -- outputs )" }
{ $values { "inputs" "a list of tokens" } { "outputs" "a list of tokens" } }
-{ $description "A stack effect declaration. This is treated as a comment unless it appears inside a word definition." }
-{ $see-also "effects" } ;
-
-HELP: ((
-{ $syntax "(( inputs -- outputs ))" }
-{ $values { "inputs" "a list of tokens" } { "outputs" "a list of tokens" } }
-{ $description "Literal stack effect syntax." }
+{ $description "Literal stack effect syntax. Also used by syntax words (such as " { $link POSTPONE: : } "), typically declaring the stack effect of the word definition which follows." }
{ $notes "Useful for meta-programming with " { $link define-declared } "." }
{ $examples
{ $example
""
"["
" my-dynamic-word 2 { [ + ] [ * ] } random curry"
- " (( x -- y )) define-declared"
+ " ( x -- y ) define-declared"
"] with-compilation-unit"
""
"2 my-dynamic-word ."
"4"
}
-} ;
+}
+{ $see-also "effects" }
+;
HELP: !
{ $syntax "! comment..." }
{ $values { "N" "hexadecimal digit (0-9, a-f, A-F)" } { "pEEE" "decimal exponent value" } }
{ $description "Adds an integer or floating-point value read from a hexadecimal literal to the parse tree." }
{ $examples
- { $example "USE: prettyprint" "HEX: ff ." "255" }
- { $example "USE: prettyprint" "HEX: 1.8p5 ." "48.0" }
+ { $example "USE: prettyprint" "0xff ." "255" }
+ { $example "USE: prettyprint" "0x1.8p5 ." "48.0" }
} ;
HELP: OCT:
{ $syntax "OCT: integer" }
{ $values { "integer" "octal digits (0-7)" } }
{ $description "Adds an integer read from an octal literal to the parse tree." }
-{ $examples { $example "USE: prettyprint" "OCT: 31337 ." "13023" } } ;
+{ $examples { $example "USE: prettyprint" "0o31337 ." "13023" } } ;
HELP: BIN:
{ $syntax "BIN: integer" }
{ $values { "integer" "binary digits (0 and 1)" } }
{ $description "Adds an integer read from an binary literal to the parse tree." }
-{ $examples { $example "USE: prettyprint" "BIN: 100 ." "4" } } ;
+{ $examples { $example "USE: prettyprint" "0b100 ." "4" } } ;
HELP: NAN:
{ $syntax "NAN: payload" }
{ $description "Defines a new generic word which uses the " { $link math-combination } " method combination." } ;
HELP: HOOK:
-{ $syntax "HOOK: word variable ( stack -- effect ) " }
+{ $syntax "HOOK: word variable ( stack -- effect )" }
{ $values { "word" "a new word to define" } { "variable" word } }
{ $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." }
{ $examples
"TUPLE: air-transport ;"
"HOOK: deliver transport ( destination -- )"
"M: land-transport deliver \"Land delivery to \" write print ;"
- "M: air-transport deliver \"Air delivery to \" write print ;"
+ "M: air-transport deliver \"Air delivery to \" write print ;"
"T{ air-transport } transport set"
"\"New York City\" deliver"
"Air delivery to New York City"
{ $code "TUPLE: person" "{ age integer initial: 0 }" "{ department string initial: \"Marketing\" }" "manager ;" }
} ;
+HELP: final
+{ $syntax "TUPLE: ... ; final" }
+{ $description "Declares the most recently defined word as a final tuple class which cannot be subclassed. Attempting to subclass a final class raises a " { $link bad-superclass } " error." } ;
+
HELP: initial:
{ $syntax "TUPLE: ... { slot initial: value } ... ;" }
{ $values { "slot" "a slot name" } { "value" "any literal" } }
"The following two lines are equivalent:"
{ $code
"C: <color> color"
- ": <color> color boa ;"
+ ": <color> ( red green blue -- color ) color boa ;"
}
"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."
} ;
HELP: MAIN:
{ $syntax "MAIN: word" }
{ $values { "word" word } }
-{ $description "Defines the main entry point for the current vocabulary. This word will be executed when this vocabulary is passed to " { $link run } "." } ;
+{ $description "Defines the main entry point for the current vocabulary and source file. This word will be executed when this vocabulary is passed to " { $link run } " or the source file is passed to " { $link run-script } "." } ;
HELP: <PRIVATE
{ $syntax "<PRIVATE ... PRIVATE>" }
projects / factor.git / blobdiff