diff --git a/basis/concurrency/messaging/messaging-docs.factor b/basis/concurrency/messaging/messaging-docs.factor index 3bd2d330c3..41beedb6dc 100644 --- a/basis/concurrency/messaging/messaging-docs.factor +++ b/basis/concurrency/messaging/messaging-docs.factor @@ -53,7 +53,8 @@ ARTICLE: { "concurrency" "synchronous-sends" } "Synchronous sends" { $subsection reply-synchronous } "An example:" { $example - "USING: concurrency.messaging kernel threads ;" + "USING: concurrency.messaging kernel prettyprint threads ;" + "IN: scratchpad" ": pong-server ( -- )" " receive [ \"pong\" ] dip reply-synchronous ;" "[ pong-server t ] \"pong-server\" spawn-server" diff --git a/basis/help/tutorial/tutorial.factor b/basis/help/tutorial/tutorial.factor index 9ed36ac77c..32cccee257 100644 --- a/basis/help/tutorial/tutorial.factor +++ b/basis/help/tutorial/tutorial.factor @@ -94,7 +94,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:" -{ $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:" @@ -106,12 +106,12 @@ $nl "Start by pushing a character on the stack; notice that characters are really just integers:" { $code "CHAR: a" } "Now, use the " { $link Letter? } " word to test if it is an alphabetical character, upper or lower case:" -{ $example "Letter? ." "t" } +{ $unchecked-example "Letter? ." "t" } "This gives the expected result." $nl "Now try with a non-alphabetical character:" { $code "CHAR: #" } -{ $example "Letter? ." "f" } +{ $unchecked-example "Letter? ." "f" } "What we want to do is given a string, remove all characters which do not match the " { $link Letter? } " predicate. Let's push a string on the stack:" { $code "\"A man, a plan, a canal: Panama.\"" } "Now, place a quotation containing " { $link Letter? } " on the stack; quoting code places it on the stack instead of executing it immediately:" diff --git a/basis/locals/locals-docs.factor b/basis/locals/locals-docs.factor index 8092d11e4a..efaad748cf 100644 --- a/basis/locals/locals-docs.factor +++ b/basis/locals/locals-docs.factor @@ -134,6 +134,7 @@ $nl } "In a word with locals, literals expand into code which constructs the literal, and so every invocation pushes a new object:" { $example + "USE: locals" "IN: scratchpad" "TUPLE: person first-name last-name ;" ":: ordinary-word-test ( -- tuple )" diff --git a/basis/math/complex/complex-docs.factor b/basis/math/complex/complex-docs.factor index bed3a655b1..1fcc1ead13 100644 --- a/basis/math/complex/complex-docs.factor +++ b/basis/math/complex/complex-docs.factor @@ -6,7 +6,7 @@ ARTICLE: "complex-numbers-zero" "Embedding of real numbers in complex numbers" "Constructing a complex number with an imaginary component equal to an integer zero simply returns the real number corresponding to the real component:" { $example "USING: math prettyprint ;" "C{ 1 2 } C{ 3 -2 } + ." "4" } "Constructing a complex number with an imaginary component equal to floating point zero will still output a new complex number, however:" -{ $example "USING: math prettyprint ;" "C{ 0.0 2.0 } C{ 0.0 1.0 } * ." "C{ 2.0 0.0 }" } +{ $example "USING: math prettyprint ;" "C{ 0.0 2.0 } C{ 0.0 1.0 } * ." "C{ -2.0 0.0 }" } "Unlike math, where all real numbers are also complex numbers, Factor only considers a number to be a complex number if its imaginary part is non-zero. However, complex number operations are fully supported for real numbers; they are treated as having an imaginary part of zero." ; ARTICLE: "complex-numbers" "Complex numbers" diff --git a/basis/math/libm/libm-docs.factor b/basis/math/libm/libm-docs.factor index 1fe565ee00..72c114487b 100644 --- a/basis/math/libm/libm-docs.factor +++ b/basis/math/libm/libm-docs.factor @@ -5,8 +5,8 @@ ARTICLE: "math.libm" "C standard library math functions" "The words in the " { $vocab-link "math.libm" } " vocabulary call C standard library math functions. They are used to implement words in the " { $vocab-link "math.functions" } " vocabulary." $nl "They can be called directly, however there is little reason to do so, since they only implement real-valued functions, and in some cases place restrictions on the domain:" -{ $example "2 acos ." "C{ 0.0 1.316957896924817 }" } -{ $example "2 facos ." "0.0/0.0" } +{ $example "USE: math.functions" "2 acos ." "C{ 0.0 1.316957896924817 }" } +{ $example "USE: math.libm" "2 facos ." "0.0/0.0" } "Trigonometric functions:" { $subsection fcos } { $subsection fsin } diff --git a/basis/stack-checker/stack-checker-docs.factor b/basis/stack-checker/stack-checker-docs.factor index f208178b10..5b67cd9adc 100644 --- a/basis/stack-checker/stack-checker-docs.factor +++ b/basis/stack-checker/stack-checker-docs.factor @@ -21,7 +21,7 @@ $nl ARTICLE: "inference-combinators" "Combinator stack effects" "Without further information, one cannot say what the stack effect of " { $link call } " is; it depends on the given quotation. If the inferencer encounters a " { $link call } " without further information, a " { $link literal-expected } " error is raised." -{ $example "[ dup call ] infer." "... an error ..." } +{ $example "[ dup call ] infer." "Literal value expected\n\nType :help for debugging help." } "On the other hand, the stack effect of applying " { $link call } " to a literal quotation or a " { $link curry } " of a literal quotation is easy to compute; it behaves as if the quotation was substituted at that point:" { $example "[ [ 2 + ] call ] infer." "( object -- object )" } "Consider a combinator such as " { $link keep } ". The combinator itself does not have a stack effect, because it applies " { $link call } " to a potentially arbitrary quotation. However, since the combinator is declared " { $link POSTPONE: inline } ", a given usage of it can have a stack effect:" @@ -35,7 +35,15 @@ $nl "Here is an example where the stack effect cannot be inferred:" { $code ": foo 0 [ + ] ;" "[ foo reduce ] infer." } "However if " { $snippet "foo" } " was declared " { $link POSTPONE: inline } ", everything would work, since the " { $link reduce } " combinator is also " { $link POSTPONE: inline } ", and the inferencer can see the literal quotation value at the point it is passed to " { $link call } ":" -{ $example ": foo 0 [ + ] ; inline" "[ foo reduce ] infer." "( object -- object )" } ; +{ $example ": foo 0 [ + ] ; inline" "[ foo reduce ] infer." "( object -- object )" } +"Passing a literal quotation on the data stack through an inlined recursive combinator nullifies its literal status. For example, the following will not infer:" +{ $example + "[ [ reverse ] swap [ reverse ] map swap call ] infer." "Literal value expected\n\nType :help for debugging help." +} +"To make this work, pass the quotation on the retain stack instead:" +{ $example + "[ [ reverse ] [ [ reverse ] map ] dip call ] infer." "( object -- object )" +} ; ARTICLE: "inference-branches" "Branch stack effects" "Conditionals such as " { $link if } " and combinators built on " { $link if } " present a problem, in that if the two branches leave the stack at a different height, it is not clear what the stack effect should be. In this case, inference throws a " { $link unbalanced-branches-error } "." @@ -58,12 +66,14 @@ $nl $nl "If a recursive word takes quotation parameters from the stack and calls them, it must be declared " { $link POSTPONE: inline } " (as documented in " { $link "inference-combinators" } ") as well as " { $link POSTPONE: recursive } "." $nl -"Furthermore, the input parameters which are quotations must be annotated in the stack effect. For example," -{ $see loop } -"An inline recursive word cannot pass a quotation through the recursive call. For example, the following will not infer:" -{ $code ": foo ( a b c -- d e f ) [ f foo drop ] when 2dup call ; inline" "[ 1 [ 1+ ] foo ] infer." } +"Furthermore, the input parameters which are quotations must be annotated in the stack effect. For example, the following will not infer:" +{ $example ": bad ( quot -- ) [ call ] keep foo ; inline recursive" "[ [ ] bad ] infer." "Literal value expected\n\nType :help for debugging help." } +"The following is correct:" +{ $example ": good ( quot: ( -- ) -- ) [ call ] keep good ; inline recursive" "[ [ ] good ] infer." "( -- )" } +"An inline recursive word cannot pass a quotation on the data stack through the recursive call. For example, the following will not infer:" +{ $example ": bad ( ? quot: ( ? -- ) -- ) 2dup [ not ] dip bad call ; inline recursive" "[ [ drop ] bad ] infer." "Literal value expected\n\nType :help for debugging help." } "However a small change can be made:" -{ $example ": foo ( a b c -- d ) [ 2dup f foo drop ] when call ; inline" "[ 1 [ 1+ ] t foo ] infer." "( -- object )" } +{ $example ": good ( ? quot: ( ? -- ) -- ) [ good ] 2keep [ not ] dip call ; inline recursive" "[ [ drop ] good ] infer." "( object -- )" } "An inline recursive word must have a fixed stack effect in its base case. The following will not infer:" { $code ": foo ( quot ? -- ) [ f foo ] [ call ] if ; inline" diff --git a/core/assocs/assocs-docs.factor b/core/assocs/assocs-docs.factor index 3d8e516cdf..e088953db8 100644 --- a/core/assocs/assocs-docs.factor +++ b/core/assocs/assocs-docs.factor @@ -21,7 +21,7 @@ ARTICLE: "enums" "Enumerations" { $subsection enum } { $subsection } "Inverting a permutation using enumerations:" -{ $example "USING: assocs sorting prettyprint ;" ": invert >alist sort-values keys ;" "{ 2 0 4 1 3 } invert ." "{ 1 3 0 4 2 }" } ; +{ $example "USING: assocs sorting prettyprint ;" "IN: scratchpad" ": invert ( perm -- perm' )" " >alist sort-values keys ;" "{ 2 0 4 1 3 } invert ." "{ 1 3 0 4 2 }" } ; HELP: enum { $class-description "An associative structure which wraps a sequence and maps integers to the corresponding elements of the sequence." diff --git a/core/classes/singleton/singleton-docs.factor b/core/classes/singleton/singleton-docs.factor index d6911576dd..bd2a2ae6a6 100644 --- a/core/classes/singleton/singleton-docs.factor +++ b/core/classes/singleton/singleton-docs.factor @@ -10,18 +10,6 @@ ARTICLE: "singletons" "Singleton classes" { $subsection singleton-class? } { $subsection singleton-class } ; -HELP: SINGLETON: -{ $syntax "SINGLETON: class" } -{ $values - { "class" "a new singleton to define" } -} -{ $description - "Defines a new singleton class. The class word itself is the sole instance of the singleton class." -} -{ $examples - { $example "USING: classes.singleton kernel io ;" "IN: scratchpad" "SINGLETON: foo\nGENERIC: bar ( obj -- )\nM: foo bar drop \"a foo!\" print ;\nfoo bar" "a foo!" } -} ; - HELP: define-singleton-class { $values { "word" "a new word" } } { $description diff --git a/core/kernel/kernel-docs.factor b/core/kernel/kernel-docs.factor index 2e99969264..d85a51edff 100644 --- a/core/kernel/kernel-docs.factor +++ b/core/kernel/kernel-docs.factor @@ -888,9 +888,9 @@ $nl "Here is an array containing the " { $link f } " class:" { $example "{ POSTPONE: f } ." "{ POSTPONE: f }" } "The " { $link f } " object is an instance of the " { $link f } " class:" -{ $example "f class ." "POSTPONE: f" } +{ $example "USE: classes" "f class ." "POSTPONE: f" } "The " { $link f } " class is an instance of " { $link word } ":" -{ $example "\\ f class ." "word" } +{ $example "USE: classes" "\\ f class ." "word" } "On the other hand, " { $link t } " is just a word, and there is no class which it is a unique instance of." { $example "t \\ t eq? ." "t" } "Many words which search collections confuse the case of no element being present with an element being found equal to " { $link f } ". If this distinction is imporant, there is usually an alternative word which can be used; for example, compare " { $link at } " with " { $link at* } "." ; diff --git a/core/math/integers/integers-docs.factor b/core/math/integers/integers-docs.factor index c75040b6bb..26c7e03fba 100644 --- a/core/math/integers/integers-docs.factor +++ b/core/math/integers/integers-docs.factor @@ -4,10 +4,10 @@ IN: math.integers ARTICLE: "integers" "Integers" { $subsection integer } "Integers come in two varieties -- fixnums and bignums. Fixnums fit in a machine word and are faster to manipulate; if the result of a fixnum operation is too large to fit in a fixnum, the result is upgraded to a bignum. Here is an example where two fixnums are multiplied yielding a bignum:" -{ $example "134217728 class ." "fixnum" } -{ $example "128 class ." "fixnum" } +{ $example "USE: classes" "134217728 class ." "fixnum" } +{ $example "USE: classes" "128 class ." "fixnum" } { $example "134217728 128 * ." "17179869184" } -{ $example "134217728 128 * class ." "bignum" } +{ $example "USE: classes" "1 128 shift class ." "bignum" } "Integers can be entered using a different base; see " { $link "syntax-numbers" } "." $nl "Integers can be tested for, and real numbers can be converted to integers:" diff --git a/core/math/math-docs.factor b/core/math/math-docs.factor index caae9dde5b..7d0666328f 100644 --- a/core/math/math-docs.factor +++ b/core/math/math-docs.factor @@ -321,8 +321,8 @@ ARTICLE: "number-protocol" "Number protocol" "Math operations obey certain numerical upgrade rules. If one of the inputs is a bignum and the other is a fixnum, the latter is first coerced to a bignum; if one of the inputs is a float, the other is coerced to a float." $nl "Two examples where you should note the types of the inputs and outputs:" -{ $example "3 >fixnum 6 >bignum * class ." "bignum" } -{ $example "1/2 2.0 + ." "4.5" } +{ $example "USE: classes" "3 >fixnum 6 >bignum * class ." "bignum" } +{ $example "1/2 2.0 + ." "2.5" } "The following usual operations are supported by all numbers." { $subsection + } { $subsection - } diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor index 9962bcdb87..d8cd56ff3d 100644 --- a/core/syntax/syntax-docs.factor +++ b/core/syntax/syntax-docs.factor @@ -352,6 +352,18 @@ HELP: SYMBOLS: { $description "Creates a new symbol for every token until the " { $snippet ";" } "." } { $examples { $example "USING: prettyprint ;" "IN: scratchpad" "SYMBOLS: foo bar baz ;\nfoo . bar . baz ." "foo\nbar\nbaz" } } ; +HELP: SINGLETON: +{ $syntax "SINGLETON: class" } +{ $values + { "class" "a new singleton to define" } +} +{ $description + "Defines a new singleton class. The class word itself is the sole instance of the singleton class." +} +{ $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" } }