diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor index ed0f4b16b0..8832cde3e4 100644 --- a/core/sequences/sequences-docs.factor +++ b/core/sequences/sequences-docs.factor @@ -15,7 +15,7 @@ HELP: length HELP: set-length { $values { "n" "a non-negative integer" } { "seq" "a resizable sequence" } } { $contract "Resizes a sequence. The initial contents of the new area is undefined." } -{ $errors "Throws a " { $link no-method } " error if the sequence is not resizable, and a " { $link bounds-error } " if the new length is negative." } +{ $errors "Throws a " { $link no-method } " error if the sequence is not resizable, and a " { $link bounds-error } " if the new length is negative." } { $side-effects "seq" } ; HELP: lengthen @@ -45,7 +45,7 @@ HELP: nths { "indices" sequence } { "seq" sequence } { "seq'" sequence } } { $description "Outputs a sequence of elements from the input sequence indexed by the indices." } -{ $examples +{ $examples { $example "USING: prettyprint sequences ;" "{ 0 2 } { \"a\" \"b\" \"c\" } nths ." "{ \"a\" \"c\" }" @@ -248,7 +248,7 @@ HELP: array-nth { $warning "This word is in the " { $vocab-link "sequences.private" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory. User code must use " { $link nth } " instead." } ; HELP: set-array-nth -{ $values { "elt" object } { "n" "a non-negative fixnum" } { "array" "an array" } } +{ $values { "elt" object } { "n" "a non-negative fixnum" } { "array" "an array" } } { $description "Low-level array element mutator." } { $warning "This word is in the " { $vocab-link "sequences.private" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory. User code must use " { $link set-nth } " instead." } ; @@ -430,7 +430,7 @@ HELP: all? HELP: push-if { $values { "elt" object } { "quot" { $quotation "( ..a elt -- ..b ? )" } } { "accum" "a resizable mutable sequence" } } -{ $description "Adds the element at the end of the sequence if the quotation yields a true value." } +{ $description "Adds the element at the end of the sequence if the quotation yields a true value." } { $notes "This word is a factor of " { $link filter } "." } ; HELP: filter @@ -557,7 +557,7 @@ HELP: append! HELP: prefix { $values { "seq" sequence } { "elt" object } { "newseq" sequence } } { $description "Outputs a new sequence obtained by adding " { $snippet "elt" } " at the beginning of " { $snippet "seq" } "." } -{ $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." } +{ $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." } { $examples { $example "USING: prettyprint sequences ;" "{ 1 2 3 } 0 prefix ." "{ 0 1 2 3 }" } } ; @@ -713,7 +713,7 @@ HELP: append { $values { "seq1" sequence } { "seq2" sequence } { "newseq" sequence } } { $description "Outputs a new sequence of the same type as " { $snippet "seq1" } " consisting of the elements of " { $snippet "seq1" } " followed by " { $snippet "seq2" } "." } { $errors "Throws an error if " { $snippet "seq2" } " contains elements not permitted in sequences of the same class as " { $snippet "seq1" } "." } -{ $examples +{ $examples { $example "USING: prettyprint sequences ;" "{ 1 2 } B{ 3 4 } append ." "{ 1 2 3 4 }" @@ -728,7 +728,7 @@ HELP: append-as { $values { "seq1" sequence } { "seq2" sequence } { "exemplar" sequence } { "newseq" sequence } } { $description "Outputs a new sequence of the same type as " { $snippet "exemplar" } " consisting of the elements of " { $snippet "seq1" } " followed by " { $snippet "seq2" } "." } { $errors "Throws an error if " { $snippet "seq1" } " or " { $snippet "seq2" } " contain elements not permitted in sequences of the same class as " { $snippet "exemplar" } "." } -{ $examples +{ $examples { $example "USING: prettyprint sequences ;" "{ 1 2 } B{ 3 4 } B{ } append-as ." "B{ 1 2 3 4 }" @@ -992,7 +992,7 @@ HELP: selector { $values { "quot" { $quotation "( ... elt -- ... ? )" } } { "selector" { $quotation "( ... elt -- ... )" } } { "accum" vector } } -{ $description "Creates a new vector to accumulate the values which return true for a predicate. Returns a new quotation which accepts an object to be tested and stored in the collector if the test yields true. The collector is left on the stack for convenience." } +{ $description "Creates a new vector to accumulate the values which return true for a predicate. Returns a new quotation which accepts an object to be tested and stored in the collector if the test yields true. The collector is left on the stack for convenience." } { $example "! Find all the even numbers:" "USING: prettyprint sequences math kernel ;" "10 iota [ even? ] selector [ each ] dip ." "V{ 0 2 4 6 8 }" @@ -1004,7 +1004,7 @@ HELP: trim-head { "seq" sequence } { "quot" quotation } { "newseq" sequence } } { $description "Removes elements starting from the left side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a new sequence." } -{ $example "" "USING: prettyprint math sequences ;" +{ $example "USING: prettyprint math sequences ;" "{ 0 0 1 2 3 0 0 } [ zero? ] trim-head ." "{ 1 2 3 0 0 }" } ; @@ -1014,7 +1014,7 @@ HELP: trim-head-slice { "seq" sequence } { "quot" quotation } { "slice" slice } } { $description "Removes elements starting from the left side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a slice" } -{ $example "" "USING: prettyprint math sequences ;" +{ $example "USING: prettyprint math sequences ;" "{ 0 0 1 2 3 0 0 } [ zero? ] trim-head-slice ." "T{ slice { from 2 } { to 7 } { seq { 0 0 1 2 3 0 0 } } }" } ; @@ -1024,7 +1024,7 @@ HELP: trim-tail { "seq" sequence } { "quot" quotation } { "newseq" sequence } } { $description "Removes elements starting from the right side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a new sequence." } -{ $example "" "USING: prettyprint math sequences ;" +{ $example "USING: prettyprint math sequences ;" "{ 0 0 1 2 3 0 0 } [ zero? ] trim-tail ." "{ 0 0 1 2 3 }" } ; @@ -1034,7 +1034,7 @@ HELP: trim-tail-slice { "seq" sequence } { "quot" quotation } { "slice" slice } } { $description "Removes elements starting from the right side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a slice." } -{ $example "" "USING: prettyprint math sequences ;" +{ $example "USING: prettyprint math sequences ;" "{ 0 0 1 2 3 0 0 } [ zero? ] trim-tail-slice ." "T{ slice { from 0 } { to 5 } { seq { 0 0 1 2 3 0 0 } } }" } ; @@ -1044,7 +1044,7 @@ HELP: trim { "seq" sequence } { "quot" quotation } { "newseq" sequence } } { $description "Removes elements starting from the left and right sides of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a new sequence." } -{ $example "" "USING: prettyprint math sequences ;" +{ $example "USING: prettyprint math sequences ;" "{ 0 0 1 2 3 0 0 } [ zero? ] trim ." "{ 1 2 3 }" } ; @@ -1054,7 +1054,7 @@ HELP: trim-slice { "seq" sequence } { "quot" quotation } { "slice" slice } } { $description "Removes elements starting from the left and right sides of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a slice." } -{ $example "" "USING: prettyprint math sequences ;" +{ $example "USING: prettyprint math sequences ;" "{ 0 0 1 2 3 0 0 } [ zero? ] trim-slice ." "T{ slice { from 2 } { to 5 } { seq { 0 0 1 2 3 0 0 } } }" } ; @@ -1065,8 +1065,8 @@ HELP: sift { $values { "seq" sequence } { "newseq" sequence } } - { $description "Outputs a new sequence with all instance of " { $link f } " removed." } - { $examples + { $description "Outputs a new sequence with all instance of " { $link f } " removed." } + { $examples { $example "USING: prettyprint sequences ;" "{ \"a\" 3 { } f } sift ." "{ \"a\" 3 { } }" @@ -1078,7 +1078,7 @@ HELP: harvest { "seq" sequence } { "newseq" sequence } } { $description "Outputs a new sequence with all empty sequences removed." } -{ $examples +{ $examples { $example "USING: prettyprint sequences ;" "{ { } { 2 3 } { 5 } { } } harvest ." "{ { 2 3 } { 5 } }" @@ -1091,9 +1091,9 @@ HELP: set-first { $values { "first" object } { "seq" sequence } } { $description "Sets the first element of a sequence." } -{ $examples +{ $examples { $example "USING: prettyprint kernel sequences ;" - "{ 1 2 3 4 } 5 over set-first ." + "{ 1 2 3 4 } 5 over set-first ." "{ 5 2 3 4 }" } } ; @@ -1102,9 +1102,9 @@ HELP: set-second { $values { "second" object } { "seq" sequence } } { $description "Sets the second element of a sequence." } -{ $examples +{ $examples { $example "USING: prettyprint kernel sequences ;" - "{ 1 2 3 4 } 5 over set-second ." + "{ 1 2 3 4 } 5 over set-second ." "{ 1 5 3 4 }" } } ; @@ -1113,9 +1113,9 @@ HELP: set-third { $values { "third" object } { "seq" sequence } } { $description "Sets the third element of a sequence." } -{ $examples +{ $examples { $example "USING: prettyprint kernel sequences ;" - "{ 1 2 3 4 } 5 over set-third ." + "{ 1 2 3 4 } 5 over set-third ." "{ 1 2 5 4 }" } } ; @@ -1124,9 +1124,9 @@ HELP: set-fourth { $values { "fourth" object } { "seq" sequence } } { $description "Sets the fourth element of a sequence." } -{ $examples +{ $examples { $example "USING: prettyprint kernel sequences ;" - "{ 1 2 3 4 } 5 over set-fourth ." + "{ 1 2 3 4 } 5 over set-fourth ." "{ 1 2 3 5 }" } } ; @@ -1138,7 +1138,7 @@ HELP: replicate { "len" integer } { "quot" { $quotation "( ... -- ... newelt )" } } { "newseq" sequence } } { $description "Calls the quotation " { $snippet "len" } " times, collecting results into a new array." } -{ $examples +{ $examples { $unchecked-example "USING: kernel prettyprint random sequences ;" "5 [ 100 random ] replicate ." "{ 52 10 45 81 30 }" @@ -1150,7 +1150,7 @@ HELP: replicate-as { "len" integer } { "quot" { $quotation "( ... -- ... newelt )" } } { "exemplar" sequence } { "newseq" sequence } } { $description "Calls the quotation " { $snippet "len" } " times, collecting results into a new sequence of the same type as the exemplar sequence." } -{ $examples +{ $examples { $unchecked-example "USING: prettyprint kernel sequences ;" "5 [ 100 random ] B{ } replicate-as ." "B{ 44 8 2 33 18 }" @@ -1163,8 +1163,8 @@ HELP: partition { $values { "seq" sequence } { "quot" quotation } { "trueseq" sequence } { "falseseq" sequence } } - { $description "Calls a predicate quotation on each element of the input sequence. If the test yields true, the element is added to " { $snippet "trueseq" } "; if false, it's added to " { $snippet "falseseq" } "." } -{ $examples + { $description "Calls a predicate quotation on each element of the input sequence. If the test yields true, the element is added to " { $snippet "trueseq" } "; if false, it's added to " { $snippet "falseseq" } "." } +{ $examples { $example "USING: prettyprint kernel math sequences ;" "{ 1 2 3 4 5 } [ even? ] partition [ . ] bi@" "{ 2 4 }\n{ 1 3 5 }" diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor index 059fa487bc..18434166b9 100644 --- a/core/syntax/syntax-docs.factor +++ b/core/syntax/syntax-docs.factor @@ -195,7 +195,7 @@ ARTICLE: "syntax-hash-sets" "Hash set syntax" 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 @@ -340,37 +340,37 @@ $nl 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: } } "." } +{ $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 } ... }" } @@ -453,7 +453,7 @@ HELP: SINGLETON: { $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" } } @@ -560,7 +560,7 @@ HELP: FROM: 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>" } } ; @@ -728,7 +728,7 @@ HELP: HOOK: "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" diff --git a/core/vocabs/parser/parser-docs.factor b/core/vocabs/parser/parser-docs.factor index 66900978a8..9f60f79047 100644 --- a/core/vocabs/parser/parser-docs.factor +++ b/core/vocabs/parser/parser-docs.factor @@ -1,7 +1,7 @@ USING: help.markup help.syntax parser strings words assocs vocabs ; IN: vocabs.parser -ARTICLE: "word-search-errors" "Word lookup errors" +ARTICLE: "word-search-errors" "Word lookup errors" "If the parser cannot not find a word in the current vocabulary search path, it attempts to look for the word in all loaded vocabularies." $nl "If " { $link auto-use? } " mode is off, a restartable error is thrown with a restart for each vocabulary in question, together with a restart which defers the word in the current vocabulary, as if " { $link POSTPONE: DEFER: } " was used." @@ -142,7 +142,7 @@ HELP: add-words-from HELP: add-words-excluding { $values { "vocab" "a vocabulary specifier" } { "words" "a sequence of word names" } } -{ $description "Adds all words except for " { $snippet "words" } " from " { $snippet "vocab" } " to the manifest." } +{ $description "Adds all words except for " { $snippet "words" } " from " { $snippet "vocab" } " to the manifest." } { $notes "This word is used to implement " { $link POSTPONE: EXCLUDE: } "." } ; HELP: add-renamed-word