diff --git a/basis/classes/struct/struct-docs.factor b/basis/classes/struct/struct-docs.factor index e580c4c0aa..15f784a819 100644 --- a/basis/classes/struct/struct-docs.factor +++ b/basis/classes/struct/struct-docs.factor @@ -31,7 +31,7 @@ HELP: HELP: STRUCT: { $syntax "STRUCT: class { slot type } { slot type } ... ;" } { $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } } -{ $description "Defines a new " { $link struct } " type. The syntax is nearly identical to " { $link postpone: TUPLE: } "; however, there are some additional restrictions on struct types:" +{ $description "Defines a new " { $link struct } " type. The syntax is nearly identical to " { $link postpone: \TUPLE: } "; however, there are some additional restrictions on struct types:" { $list { "Struct classes cannot have a superclass defined." } { "The slots of a struct must all have a type declared. The type must be a C type." } @@ -42,42 +42,42 @@ HELP: STRUCT: HELP: S{ { $syntax "S{ class slots... }" } { $values { "class" "a " { $link struct } " class word" } { "slots" "slot values" } } -{ $description "Marks the beginning of a literal struct. The syntax is identical to tuple literal syntax with " { $link postpone: T{ } { $snippet " }" } "; either the assoc syntax (that is, " { $snippet "S{ class { slot value } { slot value } ... }" } ") or the simple syntax (" { $snippet "S{ class f value value ... }" } ") can be used." } ; +{ $description "Marks the beginning of a literal struct. The syntax is identical to tuple literal syntax with " { $link postpone: \T{ } { $snippet " }" } "; either the assoc syntax (that is, " { $snippet "S{ class { slot value } { slot value } ... }" } ") or the simple syntax (" { $snippet "S{ class f value value ... }" } ") can be used." } ; HELP: S@ { $syntax "S@ class alien" } { $values { "class" "a " { $link struct } " class word" } { "alien" "a literal alien" } } { $description "Marks the beginning of a literal struct at a specific C address. The prettyprinter uses this syntax when the memory backing a struct object is invalid. This syntax should not generally be used in source code." } ; -{ postpone: S{ postpone: S@ } related-words +{ postpone: \S{ postpone: S@ } related-words HELP: UNION-STRUCT: { $syntax "UNION-STRUCT: class { slot type } { slot type } ... ;" } { $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } } -{ $description "Defines a new " { $link struct } " type where all of the slots share the same storage. See " { $link postpone: STRUCT: } " for details on the syntax." } ; +{ $description "Defines a new " { $link struct } " type where all of the slots share the same storage. See " { $link postpone: \STRUCT: } " for details on the syntax." } ; HELP: PACKED-STRUCT: { $syntax "PACKED-STRUCT: class { slot type } { slot type } ... ;" } { $values { "class" "a new " { $link struct } " class to define" } { "slots" "a list of slot specifiers" } } -{ $description "Defines a new " { $link struct } " type with no alignment padding between slots or at the end. In all other respects, behaves like " { $link postpone: STRUCT: } "." } ; +{ $description "Defines a new " { $link struct } " type with no alignment padding between slots or at the end. In all other respects, behaves like " { $link postpone: \STRUCT: } "." } ; HELP: define-struct-class { $values { "class" class } { "slots" "a sequence of " { $link struct-slot-spec } "s" } } -{ $description "Defines a new " { $link struct } " class. This is the runtime equivalent of the " { $link postpone: STRUCT: } " syntax." } ; +{ $description "Defines a new " { $link struct } " class. This is the runtime equivalent of the " { $link postpone: \STRUCT: } " syntax." } ; HELP: define-packed-struct-class { $values { "class" class } { "slots" "a sequence of " { $link struct-slot-spec } "s" } } -{ $description "Defines a new " { $link struct } " class. This is the runtime equivalent of the " { $link postpone: PACKED-STRUCT: } " syntax." } ; +{ $description "Defines a new " { $link struct } " class. This is the runtime equivalent of the " { $link postpone: \PACKED-STRUCT: } " syntax." } ; HELP: define-union-struct-class { $values { "class" class } { "slots" "a sequence of " { $link struct-slot-spec } "s" } } -{ $description "Defines a new " { $link struct } " class where all of the slots share the same storage. This is the runtime equivalent of the " { $link postpone: UNION-STRUCT: } " syntax." } ; +{ $description "Defines a new " { $link struct } " class where all of the slots share the same storage. This is the runtime equivalent of the " { $link postpone: \UNION-STRUCT: } " syntax." } ; HELP: malloc-struct { $values @@ -111,7 +111,7 @@ HELP: read-struct HELP: struct { $class-description "The parent class of all struct types." } ; -{ struct postpone: STRUCT: postpone: UNION-STRUCT: } related-words +{ struct postpone: \STRUCT: postpone: \UNION-STRUCT: } related-words HELP: struct-class { $class-description "The metaclass of all " { $link struct } " classes." } ; @@ -145,10 +145,10 @@ ARTICLE: "classes.struct.examples" "Struct class examples" } ; ARTICLE: "classes.struct.define" "Defining struct classes" -"Struct classes are defined using a syntax similar to the " { $link postpone: TUPLE: } " syntax for defining tuple classes:" -{ $subsections postpone: STRUCT: postpone: PACKED-STRUCT: } +"Struct classes are defined using a syntax similar to the " { $link postpone: \TUPLE: } " syntax for defining tuple classes:" +{ $subsections postpone: \STRUCT: postpone: \PACKED-STRUCT: } "Union structs are also supported, which behave like structs but share the same memory for all the slots." -{ $subsections postpone: UNION-STRUCT: } ; +{ $subsections postpone: \UNION-STRUCT: } ; ARTICLE: "classes.struct.create" "Creating instances of structs" "Structs can be allocated with " { $link new } "- and " { $link boa } "-like constructor words. Additional words are provided for building structs from C memory and from existing buffers:" @@ -163,8 +163,8 @@ ARTICLE: "classes.struct.create" "Creating instances of structs" (struct) (malloc-struct) } -"Structs have literal syntax, similar to " { $link postpone: T{ } " for tuples:" -{ $subsections postpone: S{ } ; +"Structs have literal syntax, similar to " { $link postpone: \T{ } " for tuples:" +{ $subsections postpone: \S{ } ; ARTICLE: "classes.struct.c" "Passing structs to C functions" "Structs can be passed and returned by value, or by reference." diff --git a/basis/help/handbook/handbook.factor b/basis/help/handbook/handbook.factor index b626fe6002..85dc5827cd 100644 --- a/basis/help/handbook/handbook.factor +++ b/basis/help/handbook/handbook.factor @@ -45,7 +45,7 @@ $nl $nl "Some generic words have " { $strong "Description" } " headings, and others have " { $strong "Contract" } " headings. A distinction is made between words which are not intended to be extended with user-defined methods, and those that are." { $heading "Vocabulary naming conventions" } -"A vocabulary name ending in " { $snippet ".private" } " contains words which are either implementation details, unsafe, or both. For example, the " { $snippet "sequences.private" } " vocabulary contains words which access sequence elements without bounds checking (" { $link "sequences-unsafe" } "). You should avoid using private words from the Factor library unless absolutely necessary. Similarly, your own code can place words in private vocabularies using " { $link postpone: postpone: \ postpone: W{ } related-words +{ literalize curry postpone: \\ postpone: \W{ } related-words diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor index d68607f2da..f0e819e079 100644 --- a/core/syntax/syntax-docs.factor +++ b/core/syntax/syntax-docs.factor @@ -11,7 +11,7 @@ ARTICLE: "parser-algorithm" "Parser algorithm" $nl "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:" { $list - { "If the current character is a double-quote (\"), the " { $link postpone: " } " parsing word is executed, causing a string to be read." } + { "If the current character is a double-quote (\"), the " { $link postpone: \" } " parsing word is executed, causing a string to be read." } { "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:" { $list @@ -99,7 +99,7 @@ ARTICLE: "syntax-floats" "Float syntax" { "Not-a-number" { $snippet "0/0." } } } "A Not-a-number literal with an arbitrary payload can also be input:" -{ $subsections postpone: nan: } +{ $subsections postpone: \nan: } "Hexadecimal, octal and binary float literals are also supported. These consist of a hexadecimal, octal or binary literal with a decimal point and a mandatory base-two exponent expressed as a decimal number after " { $snippet "p" } " or " { $snippet "P" } ":" { $example "8.0 0x1.0p3 = ." @@ -131,7 +131,7 @@ ARTICLE: "syntax-complex-numbers" "Complex number syntax" "C{ 1/2 1/3 } ! the complex number 1/2+1/3i" "C{ 0 1 } ! the imaginary unit" } -{ $subsections postpone: C{ } +{ $subsections postpone: \C{ } "More information on complex numbers can be found in " { $link "complex-numbers" } "." ; ARTICLE: "syntax-numbers" "Number syntax" @@ -146,10 +146,10 @@ ARTICLE: "syntax-numbers" "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" } ")." { $subsections - postpone: \ - postpone: postpone: + postpone: \\ + postpone: \postpone: } -"The implementation of the " { $link postpone: \ } " word is discussed in detail in " { $link "reading-ahead" } ". Words are documented in " { $link "words" } "." ; +"The implementation of the " { $link postpone: \\ } " word is discussed in detail in " { $link "reading-ahead" } ". Words are documented in " { $link "words" } "." ; ARTICLE: "escape" "Character escape codes" { $table @@ -173,57 +173,57 @@ ARTICLE: "escape" "Character escape codes" ARTICLE: "syntax-strings" "Character and string syntax" "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: " + postpone: \char: + postpone: \" "escape" } "Strings are documented in " { $link "strings" } "." ; ARTICLE: "syntax-sbufs" "String buffer syntax" -{ $subsections postpone: SBUF" } +{ $subsections postpone: \SBUF" } "String buffers are documented in " { $link "sbufs" } "." ; ARTICLE: "syntax-arrays" "Array syntax" { $subsections - postpone: { - postpone: } + postpone: \{ + postpone: \} } "Arrays are documented in " { $link "arrays" } "." ; ARTICLE: "syntax-vectors" "Vector syntax" -{ $subsections postpone: V{ } +{ $subsections postpone: \V{ } "Vectors are documented in " { $link "vectors" } "." ; ARTICLE: "syntax-hashtables" "Hashtable syntax" -{ $subsections postpone: H{ } +{ $subsections postpone: \H{ } "Hashtables are documented in " { $link "hashtables" } "." ; ARTICLE: "syntax-hash-sets" "Hash set syntax" -{ $subsections postpone: HS{ } +{ $subsections postpone: \HS{ } "Hashtables are documented in " { $link "hash-sets" } "." ; ARTICLE: "syntax-tuples" "Tuple syntax" -{ $subsections postpone: T{ } +{ $subsections postpone: \T{ } "Tuples are documented in " { $link "tuples" } "." ; ARTICLE: "syntax-quots" "Quotation syntax" { $subsections - postpone: [ - postpone: ] + postpone: \[ + postpone: \] } "Quotations are documented in " { $link "quotations" } "." ; ARTICLE: "syntax-byte-arrays" "Byte array syntax" -{ $subsections postpone: B{ } +{ $subsections postpone: \B{ } "Byte arrays are documented in " { $link "byte-arrays" } "." ; ARTICLE: "syntax-pathnames" "Pathname syntax" -{ $subsections postpone: P" } +{ $subsections postpone: \P" } "Pathnames are documented in " { $link "io.pathnames" } "." ; 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" @@ -329,7 +329,7 @@ HELP: [ { $description "Marks the beginning of a literal quotation." } { $examples { $code "[ 1 2 3 ]" } } ; -{ postpone: [ postpone: ] } related-words +{ postpone: \[ postpone: \] } related-words HELP: ] { $syntax "]" } @@ -343,24 +343,24 @@ HELP: } $nl "Parsing words can use this word as a generic end delimiter." } ; -{ postpone: { postpone: V{ postpone: H{ postpone: HS{ 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: intersection{ @@ -371,19 +371,19 @@ HELP: intersection{ HELP: H{ { $syntax "H{ { key value }... }" } { $values { "key" object } { "value" 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: } } "." } +{ $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 } ... }" } @@ -393,7 +393,7 @@ $nl "Three literal syntax forms are recognized:" { $list { "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" } ")." } - { "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." } + { "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." } { "assoc-form: otherwise, " { $snippet "slots" } " is interpreted as a sequence of " { $snippet "{ slot-name value }" } " pairs. The " { $snippet "slot-name" } " should not be quoted." } } "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." @@ -416,7 +416,7 @@ $nl HELP: W{ { $syntax "W{ object }" } { $values { "object" object } } -{ $description "Marks the beginning of a literal wrapper. Literal wrappers are terminated by " { $link postpone: } } "." } ; +{ $description "Marks the beginning of a literal wrapper. Literal wrappers are terminated by " { $link postpone: \} } "." } ; HELP: postpone: { $syntax "postpone: word" } @@ -431,7 +431,7 @@ HELP: : { $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 +{ postpone: \: postpone: \; define } related-words HELP: ; { $syntax ";" } @@ -447,7 +447,7 @@ HELP: SYMBOL: { $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" } ")." } { $examples { $example "USE: prettyprint" "IN: scratchpad" "SYMBOL: foo\nfoo ." "foo" } } ; -{ define-symbol postpone: SYMBOL: postpone: SYMBOLS: } related-words +{ define-symbol postpone: \SYMBOL: postpone: \SYMBOLS: } related-words HELP: SYMBOLS: { $syntax "SYMBOLS: words... ;" } @@ -485,7 +485,7 @@ HELP: ALIAS: } } ; -{ define-alias postpone: ALIAS: } related-words +{ define-alias postpone: \ALIAS: } related-words HELP: CONSTANT: { $syntax "CONSTANT: word value" } @@ -493,7 +493,7 @@ HELP: CONSTANT: { $description "Creates a word which pushes a value on the stack." } { $examples { $code "CONSTANT: magic 1" "CONSTANT: science 0xff0f" } } ; -{ define-constant postpone: CONSTANT: } related-words +{ define-constant postpone: \CONSTANT: } related-words HELP: \ { $syntax "\\ word" } @@ -552,7 +552,7 @@ HELP: QUALIFIED: HELP: QUALIFIED-WITH: { $syntax "QUALIFIED-WITH: vocab word-prefix" } -{ $description "Like " { $link postpone: QUALIFIED: } " but uses " { $snippet "word-prefix" } " as prefix." } +{ $description "Like " { $link postpone: \QUALIFIED: } " but uses " { $snippet "word-prefix" } " as prefix." } { $examples { $example "USING: prettyprint ;" "QUALIFIED-WITH: math m" @@ -567,7 +567,7 @@ HELP: FROM: { $examples "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 } ":" { $code "USING: vocabs.parser binary-search ;" "... search ..." } - "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:" + "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:" { $code "USING: vocabs.parser binary-search ;" "FROM: binary-search => search ;" "... search ..." } } ; @@ -591,7 +591,7 @@ HELP: RENAME: HELP: IN: { $syntax "IN: vocabulary" } { $values { "vocabulary" "a new vocabulary name" } } -{ $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." } ; +{ $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." } ; HELP: char: { $syntax "char: token" } @@ -623,19 +623,19 @@ HELP: " HELP: SBUF" { $syntax "SBUF\" string... \"" } { $values { "string" "literal and escaped characters" } } -{ $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." } +{ $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." } { $examples { $example "USING: io strings ;" "SBUF\" Hello world\" >string print" "Hello world" } } ; 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. Pathnames presented in the UI are clickable, which opens them in a text editor configured with " { $link "editor" } "." } +{ $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 "Literal stack effect syntax. Also used by syntax words (such as " { $link postpone: : } "), typically declaring the stack effect of the word definition which follows." } +{ $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 @@ -691,7 +691,7 @@ HELP: MATH: HELP: HOOK: { $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." } +{ $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 { $example "USING: io namespaces ;" @@ -729,7 +729,7 @@ HELP: INTERSECTION: HELP: MIXIN: { $syntax "MIXIN: class" } { $values { "class" "a new class word to define" } } -{ $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." } +{ $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." } { $examples "The " { $link sequence } " and " { $link assoc } " mixin classes." } ; HELP: INSTANCE: @@ -867,7 +867,7 @@ HELP: PRIVATE> { $syntax "" } { $description "Ends a block of private word definitions." } ; -{ postpone: } related-words +{ postpone: \ } related-words HELP: << { $syntax "<< ... >>" } @@ -913,4 +913,4 @@ HELP: execute( } } ; -{ postpone: call( postpone: execute( } related-words +{ postpone: \call( postpone: \execute( } related-words