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"
} ;
ARTICLE: "syntax-words" "Word syntax"
-"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" } ")."
+"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" } ")."
{ $subsections
POSTPONE: \
POSTPONE: POSTPONE:
} ;
ARTICLE: "syntax-strings" "Character and string syntax"
-"Factor has no distinct character type, however Unicode character value integers can be read by specifying a literal character, or an escaped representation thereof."
+"Factor has no distinct character type. Integers representing Unicode code points can be read by specifying a literal character, or an escaped representation thereof."
{ $subsections
POSTPONE: CHAR:
POSTPONE: "
{ $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"
$nl
"If a quotation contains a literal object, the same literal object instance is used each time the quotation executes; that is, literals are “live”."
$nl
-"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 word which may potentially mutate them."
+"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."
{ $subsections
"syntax-numbers"
"syntax-words"
"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 } ... }" }
HELP: :
{ $syntax ": word ( stack -- effect ) definition... ;" }
{ $values { "word" "a new word to define" } { "definition" "a word definition" } }
-{ $description "Defines a word with the given stack effect in the current vocabulary. The stack effect is optional for words which only push literals on the stack." }
+{ $description "Defines a word with the given stack effect in the current vocabulary." }
{ $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 ;" } } ;
{ POSTPONE: : POSTPONE: ; define } related-words
{ $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: CHAR:
{ $syntax "CHAR: token" }
-{ $values { "token" "a literal character, escape code, or Unicode character name" } }
+{ $values { "token" "a literal character, escape code, or Unicode code point name" } }
{ $description "Adds a Unicode code point to the parse tree." }
{ $examples
{ $code
HELP: P"
{ $syntax "P\" pathname\"" }
{ $values { "pathname" "a pathname string" } }
-{ $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." }
+{ $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" } "." }
{ $examples { $example "USING: accessors io io.files ;" "P\" foo.txt\" string>> print" "foo.txt" } } ;
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