Merge branch 'doc-fixes' of git://github.com/keitahaga/factor

db4
Slava Pestov 2011-01-28 21:36:34 -05:00
commit c29aa3aab9
12 changed files with 39 additions and 35 deletions

View File

@ -23,7 +23,7 @@ HELP: equate
HELP: assoc>disjoint-set
{ $values { "assoc" assoc } { "disjoint-set" disjoint-set } }
{ $description "Given an assoc representation of a graph where the keys are vertices and key/value pairs are edges, creates a disjoint set whose elements are the keys of assoc, and two keys are equvalent if they belong to the same connected component of the graph." }
{ $description "Given an assoc representation of a graph where the keys are vertices and key/value pairs are edges, creates a disjoint set whose elements are the keys of assoc, and two keys are equivalent if they belong to the same connected component of the graph." }
{ $examples
{ $example
"USING: disjoint-sets kernel prettyprint ;"

View File

@ -102,7 +102,7 @@ $nl
"For example, we'd like it to identify the following as a palindrome:"
{ $code "\"A man, a plan, a canal: Panama.\"" }
"However, right now, the simplistic algorithm we use says this is not a palindrome:"
{ $unchecked-example "\"A man, a plan, a canal: Panama.\" palindrome?" "f" }
{ $unchecked-example "\"A man, a plan, a canal: Panama.\" palindrome? ." "f" }
"We would like it to output " { $link t } " there. We can encode this requirement with a unit test that we add to " { $snippet "palindrome-tests.factor" } ":"
{ $code "[ t ] [ \"A man, a plan, a canal: Panama.\" palindrome? ] unit-test" }
"If you now run unit tests, you will see a unit test failure:"

View File

@ -184,23 +184,23 @@ HELP: interval-max
HELP: interval-mod
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
{ $description "Outputs an interval containing all possible values obtained by aplying " { $link mod } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
{ $description "Outputs an interval containing all possible values obtained by applying " { $link mod } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
HELP: interval-rem
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
{ $description "Outputs an interval containing all possible values obtained by aplying " { $link rem } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
{ $description "Outputs an interval containing all possible values obtained by applying " { $link rem } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
HELP: interval-bitand
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
{ $description "Outputs an interval containing all possible values obtained by aplying " { $link bitand } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
{ $description "Outputs an interval containing all possible values obtained by applying " { $link bitand } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
HELP: interval-bitor
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
{ $description "Outputs an interval containing all possible values obtained by aplying " { $link bitor } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
{ $description "Outputs an interval containing all possible values obtained by applying " { $link bitor } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
HELP: interval-bitxor
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
{ $description "Outputs an interval containing all possible values obtained by aplying " { $link bitxor } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
{ $description "Outputs an interval containing all possible values obtained by applying " { $link bitxor } " to elements of " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
HELP: interval-min
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }

View File

@ -62,7 +62,7 @@ HELP: n*p
HELP: pextend-conv
{ $values { "p" "a polynomial" } { "q" "a polynomial" } { "p'" "a polynomial" } { "q'" "a polynomial" } }
{ $description "Convulution, extending to " { $snippet "p_m + q_n - 1" } "." }
{ $description "Convolution, extending to " { $snippet "p_m + q_n - 1" } "." }
{ $examples { $example "USING: kernel math.polynomials prettyprint ;" "{ 1 0 1 } { 0 1 } pextend-conv [ . ] bi@" "{ 1 0 1 0 }\n{ 0 1 0 0 }" } } ;
HELP: p*

View File

@ -34,7 +34,7 @@ HELP: range
{ $description "Computes the difference of the maximum and minimum values in " { $snippet "seq" } "." }
{ $examples
{ $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } range ." "2" }
{ $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } range ." "3" } } ;
{ $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } range ." "3" } } ;
HELP: minmax
{ $values { "seq" sequence } { "min" real } { "max" real } }
@ -75,34 +75,34 @@ HELP: histogram
{ "seq" sequence }
{ "hashtable" hashtable }
}
{ $examples
{ $description "Returns a hashtable where the keys are the elements of the sequence and the values are the number of times they appeared in that sequence." }
{ $examples
{ $example "! Count the number of times an element appears in a sequence."
"USING: prettyprint math.statistics ;"
"\"aaabc\" histogram ."
"H{ { 97 3 } { 98 1 } { 99 1 } }"
}
}
{ $description "Returns a hashtable where the keys are the elements of the sequence and the values are the number of times they appeared in that sequence." } ;
} ;
HELP: histogram!
{ $values
{ "hashtable" hashtable } { "seq" sequence }
}
{ $examples
{ $description "Takes an existing hashtable and uses " { $link histogram } " to continue counting the number of occurrences of each element." }
{ $examples
{ $example "! Count the number of times the elements of two sequences appear."
"USING: prettyprint math.statistics ;"
"\"aaabc\" histogram \"aaaaaabc\" histogram! ."
"H{ { 97 9 } { 98 2 } { 99 2 } }"
}
}
{ $description "Takes an existing hashtable and uses " { $link histogram } " to continue counting the number of occurences of each element." } ;
} ;
HELP: sorted-histogram
{ $values
{ "seq" sequence }
{ "alist" "an array of key/value pairs" }
}
{ $description "Outputs a " { $link histogram } " of a sequence sorted by number of occurences from lowest to highest." }
{ $description "Outputs a " { $link histogram } " of a sequence sorted by number of occurrences from lowest to highest." }
{ $examples
{ $example "USING: prettyprint math.statistics ;"
""""abababbbbbbc" sorted-histogram ."""
@ -115,41 +115,41 @@ HELP: sequence>assoc
{ "seq" sequence } { "quot" quotation } { "exemplar" "an exemplar assoc" }
{ "assoc" assoc }
}
{ $examples
{ $description "Iterates over a sequence, allowing elements of the sequence to be added to a newly created " { $snippet "assoc" } " according to the passed quotation." }
{ $examples
{ $example "! Iterate over a sequence and increment the count at each element"
"USING: assocs prettyprint math.statistics ;"
"\"aaabc\" [ inc-at ] H{ } sequence>assoc ."
"H{ { 97 3 } { 98 1 } { 99 1 } }"
}
}
{ $description "Iterates over a sequence, allowing elements of the sequence to be added to a newly created " { $snippet "assoc" } " according to the passed quotation." } ;
} ;
HELP: sequence>assoc!
{ $values
{ "assoc" assoc } { "seq" sequence } { "quot" quotation }
}
{ $examples
{ $description "Iterates over a sequence, allowing elements of the sequence to be added to an existing " { $snippet "assoc" } " according to the passed quotation." }
{ $examples
{ $example "! Iterate over a sequence and add the counts to an existing assoc"
"USING: assocs prettyprint math.statistics kernel ;"
"H{ { 97 2 } { 98 1 } } clone \"aaabc\" [ inc-at ] sequence>assoc! ."
"H{ { 97 5 } { 98 2 } { 99 1 } }"
}
}
{ $description "Iterates over a sequence, allowing elements of the sequence to be added to an existing " { $snippet "assoc" } " according to the passed quotation." } ;
} ;
HELP: sequence>hashtable
{ $values
{ "seq" sequence } { "quot" quotation }
{ "hashtable" hashtable }
}
{ $examples
{ $description "Iterates over a sequence, allowing elements of the sequence to be added to a hashtable according to the passed quotation." }
{ $examples
{ $example "! Count the number of times an element occurs in a sequence"
"USING: assocs prettyprint math.statistics ;"
"\"aaabc\" [ inc-at ] sequence>hashtable ."
"H{ { 97 3 } { 98 1 } { 99 1 } }"
}
}
{ $description "Iterates over a sequence, allowing elements of the sequence to be added to a hashtable according to the passed quotation." } ;
} ;
ARTICLE: "histogram" "Computing histograms"
"Counting elements in a sequence:"

View File

@ -22,7 +22,8 @@ HELP: define-memoized
{ $description "Defines the given word at run time as one which memoizes its outputs given a particular input." } ;
HELP: MEMO:
{ $syntax "MEMO: word ( stack -- effect ) definition ;" }
{ $syntax "MEMO: word ( stack -- effect ) definition... ;" }
{ $values { "word" "a new word to define" } { "definition" "a word definition" } }
{ $description "Defines the given word at parse time as one which memoizes its output given a particular input. The stack effect is mandatory." } ;
{ define-memoized POSTPONE: MEMO: } related-words

View File

@ -274,7 +274,7 @@ ARTICLE: "peg.ebnf.variable" "Variable"
;
ARTICLE: "peg.ebnf.foreign-rules" "Foreign Rules"
"Rules can call outto other peg.ebnf defined parsers. The result of "
"Rules can call out to other peg.ebnf defined parsers. The result of "
"the foreign call then becomes the AST of the successful parse. Foreign rules "
"are invoked using '<foreign word-name>' or '<foreign word-name rule>'. The "
"latter allows calling a specific rule in a previously designed peg.ebnf parser. "

View File

@ -91,9 +91,10 @@ $nl
"However a small change can be made:"
{ $example ": good ( ? quot: ( ? -- ) -- ) [ good ] 2keep [ not ] dip call ; inline recursive" "[ [ drop ] good ] infer." "( x -- )" }
"An inline recursive word must have a fixed stack effect in its base case. The following will not infer:"
{ $code
{ $example
": foo ( quot ? -- ) [ f foo ] [ call ] if ; inline"
"[ [ 5 ] t foo ] infer."
"The inline recursive word “foo” must be declared recursive\nword foo"
} ;
ARTICLE: "tools.inference" "Stack effect tools"

View File

@ -139,7 +139,7 @@ HELP: closer
{ $class-description "Describes a closing tag, like " { $snippet "</a>" } ". Contains one slot, " { $snippet "name" } ", containing the closer's name." } ;
HELP: contained
{ $class-description "Represents a self-closing tag, like " { $snippet "<a/>" } ". Contains two slots," { $snippet "name" } " and " { $snippet "attrs" } " containing, respectively, the name of the tag and its attributes." } ;
{ $class-description "Represents a self-closing tag, like " { $snippet "<a/>" } ". Contains two slots, " { $snippet "name" } " and " { $snippet "attrs" } " containing, respectively, the name of the tag and its attributes." } ;
{ opener closer contained } related-words

View File

@ -444,7 +444,7 @@ HELP: boa
{ $values { "slots..." "slot values" } { "class" tuple-class } { "tuple" tuple } }
{ $description "Creates a new instance of " { $snippet "class" } " and fill in the slots from the stack, with the top-most stack element being stored in the right-most slot." }
{ $notes "The name " { $snippet "boa" } " is shorthand for “by order of arguments”, and “BOA constructor” is a pun on “boa constrictor”." }
{ $errors "Throws an error if the slot values do not match class declarations on slots (see" { $link "tuple-declarations" } ")." } ;
{ $errors "Throws an error if the slot values do not match class declarations on slots (see " { $link "tuple-declarations" } ")." } ;
HELP: bad-superclass
{ $error-description "Thrown if an attempt is made to subclass a class that is not a tuple class, or a tuple class declared " { $link POSTPONE: final } "." } ;

View File

@ -143,4 +143,4 @@ HELP: effect>string
HELP: stack-effect
{ $values { "word" word } { "effect/f" { $maybe effect } } }
{ $description "Outputs the stack effect of a word; either a stack effect declared with " { $link POSTPONE: ( } ", or an inferred stack effect (see " { $link "inference" } "." } ;
{ $description "Outputs the stack effect of a word; either a stack effect declared with " { $link POSTPONE: ( } ", or an inferred stack effect (see " { $link "inference" } ")." } ;

View File

@ -83,10 +83,12 @@ HELP: empty?
HELP: if-empty
{ $values { "seq" sequence } { "quot1" quotation } { "quot2" quotation } }
{ $description "Makes an implicit check if the sequence is empty. An empty sequence is dropped and " { $snippet "quot1" } " is called. Otherwise, if the sequence has any elements, " { $snippet "quot2" } " is called on it." }
{ $example
"USING: kernel prettyprint sequences ;"
"{ 1 2 3 } [ \"empty sequence\" ] [ sum ] if-empty ."
"6"
{ $examples
{ $example
"USING: kernel prettyprint sequences ;"
"{ 1 2 3 } [ \"empty sequence\" ] [ sum ] if-empty ."
"6"
}
} ;
HELP: when-empty