From 5d9c1ea0a0d13c80c53ebe21d5260a8f03ccd200 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Thu, 10 Jul 2008 01:00:27 -0500 Subject: [PATCH] Documentation updates, rename unfold to produce --- core/alien/alien-docs.factor | 12 +++++++---- core/alien/strings/strings-docs.factor | 8 +++++-- core/alien/syntax/syntax-docs.factor | 2 +- core/bootstrap/image/image.factor | 2 +- core/classes/algebra/algebra.factor | 2 +- core/classes/tuple/tuple-docs.factor | 10 +++++++-- core/heaps/heaps.factor | 2 +- core/inference/inference-tests.factor | 2 +- core/io/io.factor | 4 ++-- core/sequences/sequences-docs.factor | 21 ++++++++++--------- core/sequences/sequences.factor | 4 ++-- extra/concurrency/mailboxes/mailboxes.factor | 2 +- extra/http/http.factor | 2 +- extra/math/combinatorics/combinatorics.factor | 2 +- extra/multi-methods/multi-methods.factor | 2 +- extra/project-euler/002/002.factor | 2 +- extra/project-euler/019/019.factor | 2 +- extra/project-euler/148/148.factor | 2 +- extra/project-euler/common/common.factor | 2 +- extra/ui/windows/windows.factor | 2 +- 20 files changed, 51 insertions(+), 36 deletions(-) diff --git a/core/alien/alien-docs.factor b/core/alien/alien-docs.factor index 030e2f6164..70e1d2b399 100755 --- a/core/alien/alien-docs.factor +++ b/core/alien/alien-docs.factor @@ -12,9 +12,7 @@ HELP: dll HELP: expired? { $values { "c-ptr" "an alien, byte array, or " { $link f } } { "?" "a boolean" } } -{ $description "Tests if the alien is a relic from an earlier session. When an image is loaded, any alien objects which persisted in the image are marked as being expired." -$nl -"A byte array is never considered to be expired, whereas passing " { $link f } " always yields true." } ; +{ $description "Tests if the alien is a relic from an earlier session. A byte array is never considered to have expired, whereas passing " { $link f } " always yields true." } ; HELP: ( displacement c-ptr -- alien ) { $values { "displacement" "an integer" } { "c-ptr" "an alien, byte array, or " { $link f } } { "alien" "a new alien" } } @@ -146,16 +144,22 @@ HELP: alien-callback { alien-invoke alien-indirect alien-callback } related-words +ARTICLE: "alien-expiry" "Alien expiry" +"When an image is loaded, any alien objects which persisted from the previous session are marked as having expired. This is because the C pointers they contain are almost certainly no longer valid." +$nl +"For this reason, the " { $link POSTPONE: ALIEN: } " word should not be used in source files, since loading the source file then saving the image will result in the literal becoming expired. Use " { $link } " instead, and ensure the word calling " { $link } " is not declared " { $link POSTPONE: flushable } "." +{ $subsection expired? } ; + ARTICLE: "aliens" "Alien addresses" "Instances of the " { $link alien } " class represent pointers to C data outside the Factor heap:" { $subsection } { $subsection } { $subsection alien-address } -{ $subsection expired? } "Anywhere that a " { $link alien } " instance is accepted, the " { $link f } " singleton may be passed in to denote a null pointer." $nl "Usually alien objects do not have to created and dereferenced directly; instead declaring C function parameters and return values as having a pointer type such as " { $snippet "void*" } " takes care of the details." { $subsection "syntax-aliens" } +{ $subsection "alien-expiry" } "When higher-level abstractions won't do:" { $subsection "reading-writing-memory" } { $see-also "c-data" "c-types-specs" } ; diff --git a/core/alien/strings/strings-docs.factor b/core/alien/strings/strings-docs.factor index 27b0122ebe..3dc358336c 100644 --- a/core/alien/strings/strings-docs.factor +++ b/core/alien/strings/strings-docs.factor @@ -1,5 +1,5 @@ USING: help.markup help.syntax strings byte-arrays alien libc -debugger ; +debugger io.encodings.string sequences ; IN: alien.strings HELP: string>alien @@ -38,7 +38,11 @@ HELP: utf16n ARTICLE: "c-strings" "C strings" "C string types are arrays with shape " { $snippet "{ \"char*\" encoding }" } ", where " { $snippet "encoding" } " is an encoding descriptor. The type " { $snippet "\"char*\"" } " is an alias for " { $snippet "{ \"char*\" utf8 }" } ". See " { $link "encodings-descriptors" } " for information about encoding descriptors." $nl -"Passing a Factor string to a C function expecting a C string allocates a " { $link byte-array } " in the Factor heap; the string is then converted to the requested format and a raw pointer is passed to the function. If the conversion fails, for example if the string contains null bytes or characters with values higher than 255, a " { $link c-string-error. } " is thrown." +"Passing a Factor string to a C function expecting a C string allocates a " { $link byte-array } " in the Factor heap; the string is then converted to the requested format and a raw pointer is passed to the function." +$nl +"If the conversion fails, for example if the string contains null bytes or characters with values higher than 255, a " { $link c-string-error. } " is thrown." +$nl +"Care must be taken if the C function expects a " { $snippet "char*" } " with a length in bytes, rather than a null-terminated " { $snippet "char*" } "; passing the result of calling " { $link length } " on the string object will not suffice. This is because a Factor string of " { $emphasis "n" } " characters will not necessarily encode to " { $emphasis "n" } " bytes. The correct idiom for C functions which take a string with a length is to first encode the string using " { $link encode } ", and then pass the resulting byte array together with the length of this byte array." $nl "Sometimes a C function has a parameter type of " { $snippet "void*" } ", and various data types, among them strings, can be passed in. In this case, strings are not automatically converted to aliens, and instead you must call one of these words:" { $subsection string>alien } diff --git a/core/alien/syntax/syntax-docs.factor b/core/alien/syntax/syntax-docs.factor index 6565ea0e2c..37cbd12801 100755 --- a/core/alien/syntax/syntax-docs.factor +++ b/core/alien/syntax/syntax-docs.factor @@ -11,7 +11,7 @@ HELP: ALIEN: { $syntax "ALIEN: address" } { $values { "address" "a non-negative integer" } } { $description "Creates an alien object at parse time." } -{ $notes "Alien objects are invalidated between image saves and loads." } ; +{ $notes "Alien objects are invalidated between image saves and loads, and hence source files should not contain alien literals; this word is for interactive use only. See " { $link "alien-expiry" } " for details." } ; ARTICLE: "syntax-aliens" "Alien object literal syntax" { $subsection POSTPONE: ALIEN: } diff --git a/core/bootstrap/image/image.factor b/core/bootstrap/image/image.factor index 5812a0f8e7..62130cb179 100755 --- a/core/bootstrap/image/image.factor +++ b/core/bootstrap/image/image.factor @@ -250,7 +250,7 @@ GENERIC: ' ( obj -- ptr ) #! n is positive or zero. [ dup 0 > ] [ [ bignum-bits neg shift ] [ bignum-radix bitand ] bi ] - [ ] unfold nip ; + [ ] produce nip ; : emit-bignum ( n -- ) dup dup 0 < [ neg ] when bignum>seq diff --git a/core/classes/algebra/algebra.factor b/core/classes/algebra/algebra.factor index 2d2498a1c3..00657f48c4 100755 --- a/core/classes/algebra/algebra.factor +++ b/core/classes/algebra/algebra.factor @@ -194,7 +194,7 @@ M: anonymous-complement (classes-intersect?) [ [ name>> ] compare ] sort >vector [ dup empty? not ] [ dup largest-class >r over delete-nth r> ] - [ ] unfold nip ; + [ ] produce nip ; : min-class ( class seq -- class/f ) over [ classes-intersect? ] curry filter diff --git a/core/classes/tuple/tuple-docs.factor b/core/classes/tuple/tuple-docs.factor index 98e1fd3e50..114146e450 100755 --- a/core/classes/tuple/tuple-docs.factor +++ b/core/classes/tuple/tuple-docs.factor @@ -393,8 +393,14 @@ HELP: >tuple { $values { "seq" sequence } { "tuple" tuple } } { $description "Creates a tuple with slot values taken from a sequence. The first element of the sequence must be a tuple class word and the remainder the declared slots." $nl -"If the sequence has too many elements, they are ignored, and if it has too few, the remaining slots in the tuple are set to " { $link f } "." } -{ $errors "Throws an error if the first element of the sequence is not a tuple class word." } ; +"If the sequence has too few elements, the remaining slots in the tuple are set to their initial values." } +{ $errors "Throws an error if one of the following occurs:" + { $list + "the first element of the sequence is not a tuple class word" + "the values in the sequence do not satisfy the slot class predicates" + "the sequence is too long" + } +} ; HELP: tuple>array ( tuple -- array ) { $values { "tuple" tuple } { "array" array } } diff --git a/core/heaps/heaps.factor b/core/heaps/heaps.factor index 57f0e0ac72..fe1fc4e172 100755 --- a/core/heaps/heaps.factor +++ b/core/heaps/heaps.factor @@ -191,4 +191,4 @@ M: priority-queue heap-pop ( heap -- value key ) : heap-pop-all ( heap -- alist ) [ dup heap-empty? not ] [ dup heap-pop swap 2array ] - [ ] unfold nip ; + [ ] produce nip ; diff --git a/core/inference/inference-tests.factor b/core/inference/inference-tests.factor index 5ab95c6bc4..d66821e230 100755 --- a/core/inference/inference-tests.factor +++ b/core/inference/inference-tests.factor @@ -540,7 +540,7 @@ ERROR: custom-error ; { 1 0 } [ [ ] map-children ] must-infer-as ! Corner case -[ [ [ f dup ] [ dup ] [ ] unfold ] infer ] must-fail +[ [ [ f dup ] [ dup ] [ ] produce ] infer ] must-fail [ [ [ f dup ] [ ] [ ] while ] infer ] must-fail diff --git a/core/io/io.factor b/core/io/io.factor index e8521f923c..da7585e7ea 100755 --- a/core/io/io.factor +++ b/core/io/io.factor @@ -100,9 +100,9 @@ SYMBOL: error-stream presented associate format ; : lines ( stream -- seq ) - [ [ readln dup ] [ ] [ drop ] unfold ] with-input-stream ; + [ [ readln dup ] [ ] [ drop ] produce ] with-input-stream ; : contents ( stream -- str ) [ - [ 65536 read dup ] [ ] [ drop ] unfold concat f like + [ 65536 read dup ] [ ] [ drop ] produce concat f like ] with-input-stream ; diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor index 86fd9be3d7..f67b01e1bf 100755 --- a/core/sequences/sequences-docs.factor +++ b/core/sequences/sequences-docs.factor @@ -116,7 +116,7 @@ ARTICLE: "sequences-slices" "Subsequences and slices" "Taking a sequence apart into a head and a tail:" { $subsection unclip-slice } { $subsection cut-slice } -"A utility for words which use slices as mutable iterators:" +"A utility for words which use slices as iterators:" { $subsection } ; ARTICLE: "sequences-combinators" "Sequence combinators" @@ -130,7 +130,7 @@ ARTICLE: "sequences-combinators" "Sequence combinators" { $subsection map } { $subsection 2map } { $subsection accumulate } -{ $subsection unfold } +{ $subsection produce } "Filtering:" { $subsection push-if } { $subsection filter } ; @@ -748,8 +748,9 @@ HELP: slice-error } ; HELP: slice -{ $class-description "A virtual sequence which presents a subrange of the elements of an underlying sequence. New instances can be created by calling " { $link } ". Slices are mutable if the underlying sequence is mutable, and mutating a slice changes the underlying sequence." } -{ $notes "The slots of a slice should not be changed after the slice has been created, because this can break invariants." } ; +{ $class-description "A virtual sequence which presents a subrange of the elements of an underlying sequence. New instances can be created by calling " { $link } "." +$nl +"Slices are mutable if the underlying sequence is mutable, and mutating a slice changes the underlying sequence. However, slices cannot be resized after creation." } ; HELP: check-slice { $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" sequence } } @@ -764,10 +765,10 @@ HELP: collapse-slice HELP: { $values { "seq" sequence } { "slice" slice } } { $description "Outputs a slice with the same elements as " { $snippet "seq" } ", and " { $link slice-from } " equal to 0 and " { $link slice-to } " equal to the length of " { $snippet "seq" } "." } -{ $notes "Some words create slices then proceed to read and write the " { $link slice-from } " and " { $link slice-to } " slots of the slice. To behave predictably when they are themselves given a slice as input, they apply this word first to get a canonical slice." } ; +{ $notes "Some words create slices then proceed to read the " { $snippet "to" } " and " { $snippet "from" } " slots of the slice. To behave predictably when they are themselves given a slice as input, they apply this word first to get a canonical slice." } ; HELP: -{ $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" sequence } { "slice" "a slice" } } +{ $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" sequence } { "slice" slice } } { $description "Outputs a new virtual sequence sharing storage with the subrange of elements in " { $snippet "seq" } " with indices starting from and including " { $snippet "m" } ", and up to but not including " { $snippet "n" } "." } { $errors "Throws an error if " { $snippet "m" } " or " { $snippet "n" } " is out of bounds." } { $notes "Taking the slice of a slice outputs a slice of the underlying sequence of the original slice. Keep this in mind when writing code which depends on the values of " { $link slice-from } " and " { $link slice-to } " being equal to the inputs to this word. The " { $link } " word might be helpful in such situations." } ; @@ -950,14 +951,14 @@ HELP: supremum { $description "Outputs the greatest element of " { $snippet "seq" } "." } { $errors "Throws an error if the sequence is empty." } ; -HELP: unfold +HELP: produce { $values { "pred" "a quotation with stack effect " { $snippet "( -- ? )" } } { "quot" "a quotation with stack effect " { $snippet "( -- obj )" } } { "tail" "a quotation" } { "seq" "a sequence" } } { $description "Calls " { $snippet "pred" } " repeatedly. If the predicate yields " { $link f } ", stops, otherwise, calls " { $snippet "quot" } " to yield a value. Values are accumulated and returned in a sequence at the end." } { $examples "The following example divides a number by two until we reach zero, and accumulates intermediate results:" - { $example "USING: kernel math prettyprint sequences ;" "1337 [ dup 0 > ] [ 2/ dup ] [ ] unfold nip ." "{ 668 334 167 83 41 20 10 5 2 1 0 }" } - "The " { $snippet "tail" } " quotation is used when the predicate produces more than one output value. In this case, we have to drop this value even if the predicate fails in order for stack inference to calculate a stack effect for the " { $link unfold } " call:" - { $unchecked-example "USING: kernel prettyprint random sequences ;" "[ 10 random dup 1 > ] [ ] [ drop ] unfold ." "{ 8 2 2 9 }" } + { $example "USING: kernel math prettyprint sequences ;" "1337 [ dup 0 > ] [ 2/ dup ] [ ] produce nip ." "{ 668 334 167 83 41 20 10 5 2 1 0 }" } + "The " { $snippet "tail" } " quotation is used when the predicate produces more than one output value. In this case, we have to drop this value even if the predicate fails in order for stack inference to calculate a stack effect for the " { $link produce } " call:" + { $unchecked-example "USING: kernel prettyprint random sequences ;" "[ 10 random dup 1 > ] [ ] [ drop ] produce ." "{ 8 2 2 9 }" } } ; HELP: sigma diff --git a/core/sequences/sequences.factor b/core/sequences/sequences.factor index 1c6b96d0d5..bc92055338 100755 --- a/core/sequences/sequences.factor +++ b/core/sequences/sequences.factor @@ -420,11 +420,11 @@ PRIVATE> : accumulator ( quot -- quot' vec ) V{ } clone [ [ push ] curry compose ] keep ; inline -: unfold ( pred quot tail -- seq ) +: produce ( pred quot tail -- seq ) swap accumulator >r swap while r> { } like ; inline : follow ( obj quot -- seq ) - >r [ dup ] r> [ keep ] curry [ ] unfold nip ; inline + >r [ dup ] r> [ keep ] curry [ ] produce nip ; inline : prepare-index ( seq quot -- seq n quot ) >r dup length r> ; inline diff --git a/extra/concurrency/mailboxes/mailboxes.factor b/extra/concurrency/mailboxes/mailboxes.factor index 86d3297a28..d0d6afef3f 100755 --- a/extra/concurrency/mailboxes/mailboxes.factor +++ b/extra/concurrency/mailboxes/mailboxes.factor @@ -52,7 +52,7 @@ M: mailbox dispose* threads>> notify-all ; block-if-empty [ dup mailbox-empty? ] [ dup data>> pop-back ] - [ ] unfold nip ; + [ ] produce nip ; : mailbox-get-all ( mailbox -- array ) f mailbox-get-all-timeout ; diff --git a/extra/http/http.factor b/extra/http/http.factor index 90b8b86921..70848ed9f6 100755 --- a/extra/http/http.factor +++ b/extra/http/http.factor @@ -25,7 +25,7 @@ IN: http [ CHAR: \r assert= read1 CHAR: \n assert= ] when* ; : (read-header) ( -- alist ) - [ read-crlf dup f like ] [ parse-header-line ] [ drop ] unfold ; + [ read-crlf dup f like ] [ parse-header-line ] [ drop ] produce ; : process-header ( alist -- assoc ) f swap [ [ swap or dup ] dip swap ] assoc-map nip diff --git a/extra/math/combinatorics/combinatorics.factor b/extra/math/combinatorics/combinatorics.factor index 3376ea640b..f7d7b76fa4 100644 --- a/extra/math/combinatorics/combinatorics.factor +++ b/extra/math/combinatorics/combinatorics.factor @@ -16,7 +16,7 @@ IN: math.combinatorics ! http://msdn2.microsoft.com/en-us/library/aa302371.aspx : factoradic ( n -- factoradic ) - 0 [ over 0 > ] [ 1+ [ /mod ] keep swap ] [ ] unfold reverse 2nip ; + 0 [ over 0 > ] [ 1+ [ /mod ] keep swap ] [ ] produce reverse 2nip ; : (>permutation) ( seq n -- seq ) [ [ dupd >= [ 1+ ] when ] curry map ] keep prefix ; diff --git a/extra/multi-methods/multi-methods.factor b/extra/multi-methods/multi-methods.factor index 69dca2affc..8859f07340 100755 --- a/extra/multi-methods/multi-methods.factor +++ b/extra/multi-methods/multi-methods.factor @@ -80,7 +80,7 @@ SYMBOL: total : topological-sort ( seq quot -- newseq ) >r >vector [ dup empty? not ] r> [ dupd maximal-element >r over delete-nth r> ] curry - [ ] unfold nip ; inline + [ ] produce nip ; inline : classes< ( seq1 seq2 -- lt/eq/gt ) [ diff --git a/extra/project-euler/002/002.factor b/extra/project-euler/002/002.factor index 108f5c1e94..7bd77a2f68 100644 --- a/extra/project-euler/002/002.factor +++ b/extra/project-euler/002/002.factor @@ -40,7 +40,7 @@ PRIVATE> ! ------------------- : fib-upto* ( n -- seq ) - 0 1 [ pick over >= ] [ tuck + dup ] [ ] unfold 3nip + 0 1 [ pick over >= ] [ tuck + dup ] [ ] produce 3nip but-last-slice { 0 1 } prepend ; : euler002a ( -- answer ) diff --git a/extra/project-euler/019/019.factor b/extra/project-euler/019/019.factor index 5006301c2b..b29495f913 100644 --- a/extra/project-euler/019/019.factor +++ b/extra/project-euler/019/019.factor @@ -53,7 +53,7 @@ IN: project-euler.019 : first-days ( end-date start-date -- days ) [ 2dup after=? ] [ dup 1 months time+ swap day-of-week ] - [ ] unfold 2nip ; + [ ] produce 2nip ; PRIVATE> diff --git a/extra/project-euler/148/148.factor b/extra/project-euler/148/148.factor index daad89a40c..ead9a4e58d 100644 --- a/extra/project-euler/148/148.factor +++ b/extra/project-euler/148/148.factor @@ -10,7 +10,7 @@ IN: project-euler.148 dup 1+ * 2/ ; inline : >base7 ( x -- y ) - [ dup 0 > ] [ 7 /mod ] [ ] unfold nip ; + [ dup 0 > ] [ 7 /mod ] [ ] produce nip ; : (use-digit) ( prev x index -- next ) [ [ 1+ * ] [ sum-1toN 7 sum-1toN ] bi ] dip ^ * + ; diff --git a/extra/project-euler/common/common.factor b/extra/project-euler/common/common.factor index fefb986fe0..7963cde254 100644 --- a/extra/project-euler/common/common.factor +++ b/extra/project-euler/common/common.factor @@ -78,7 +78,7 @@ PRIVATE> ] if ; : number>digits ( n -- seq ) - [ dup zero? not ] [ 10 /mod ] [ ] unfold reverse nip ; + [ dup zero? not ] [ 10 /mod ] [ ] produce reverse nip ; : nth-triangle ( n -- n ) dup 1+ * 2 / ; diff --git a/extra/ui/windows/windows.factor b/extra/ui/windows/windows.factor index f8228b3177..cc697878ee 100755 --- a/extra/ui/windows/windows.factor +++ b/extra/ui/windows/windows.factor @@ -24,7 +24,7 @@ SINGLETON: windows-ui-backend [ EnumClipboardFormats win32-error dup dup 0 > ] [ ] [ drop ] - unfold nip ; + produce nip ; : with-clipboard ( quot -- ) f OpenClipboard win32-error=0/f