diff --git a/basis/io/streams/limited/limited-docs.factor b/basis/io/streams/limited/limited-docs.factor index 5a06dedf0d..18b4545fde 100644 --- a/basis/io/streams/limited/limited-docs.factor +++ b/basis/io/streams/limited/limited-docs.factor @@ -38,7 +38,7 @@ HELP: limited-input { $description "Wraps the current " { $link input-stream } " in a " { $link limited-stream } "." } ; ARTICLE: "io.streams.limited" "Limited input streams" -"The " { $vocab-link "io.streams.limited" } " vocabulary wraps a stream to behave as if it had only a limited number of bytes, either throwing an error or returning " { $link f } " upon reaching the end. Limiting a non-seekable stream keeps a byte count and triggers the end-of-stream behavior when this byte count has been reached. However, limiting a seekable stream creates a window of bytes that supports seeking and re-reading of bytes in that window." $nl +"The " { $vocab-link "io.streams.limited" } " vocabulary wraps a stream to behave as if it had only a limited number of bytes. Limiting a seekable stream creates a window of bytes that supports seeking and re-reading of bytes in that window. If it is desirable for a stream to throw an exception upon exhaustion, use the " { $vocab-link "io.streams.throwing" } " vocabulary in conjunction with this one." $nl "Wrap a stream in a limited stream:" { $subsections limited-stream } "Wrap the current " { $link input-stream } " in a limited stream:" diff --git a/basis/io/streams/throwing/throwing-docs.factor b/basis/io/streams/throwing/throwing-docs.factor new file mode 100644 index 0000000000..14ceb6c790 --- /dev/null +++ b/basis/io/streams/throwing/throwing-docs.factor @@ -0,0 +1,44 @@ +! Copyright (C) 2010 Doug Coleman. +! See http://factorcode.org/license.txt for BSD license. +USING: help.markup help.syntax io kernel quotations words +math ; +IN: io.streams.throwing + +HELP: stream-exhausted +{ $values + { "n" integer } { "stream" "an input stream" } { "word" word } +} +{ $description "The exception that gets thrown when a stream is exhausted." } ; + +HELP: stream-throw-on-eof +{ $values + { "stream" "an input stream" } { "quot" quotation } +} +{ $description "Wraps a stream in a " { $link } " tuple and calls the quotation with this stream as the " { $link input-stream } " variable. Causes a " { $link stream-exhausted } " exception to be thrown upon stream exhaustion. The stream is left open after this combinator returns." } +"This example will throw a " { $link stream-exhausted } " exception:" +{ $unchecked-example """USING: io.streams.throwing prettyprint ; +"abc" [ 4 read ] stream-throw-on-eof""" +"" +} ; + +HELP: throw-on-eof +{ $values + { "quot" quotation } +} +{ $description "Wraps the value stored in the " { $link input-stream } " variable and causes a stream read that exhausts the input stream to throw a " { $link stream-exhausted } " exception. The stream is left open after this combinator returns." } $nl +"This example will throw a " { $link stream-exhausted } " exception:" +{ $unchecked-example """USING: io.streams.throwing prettyprint ; +"abc" [ [ 4 read ] throw-on-eof ] with-string-reader""" +"" +} ; + +ARTICLE: "io.streams.throwing" "Throwing exceptions on stream exhaustion" +"The " { $vocab-link "io.streams.throwing" } " vocabulary implements combinators for changing the behavior of a stream to throw an exception upon exhaustion instead of returning " { $link f } "." $nl +"A general combinator to wrap any stream:" +{ $subsections stream-throw-on-eof } +"A combinator for the " { $link input-stream } " variable:" +{ $subsections throw-on-eof } +"The exception itself:" +{ $subsections stream-exhausted } ; + +ABOUT: "io.streams.throwing" diff --git a/basis/io/streams/throwing/throwing-tests.factor b/basis/io/streams/throwing/throwing-tests.factor index 1c9e32914b..f1567be842 100644 --- a/basis/io/streams/throwing/throwing-tests.factor +++ b/basis/io/streams/throwing/throwing-tests.factor @@ -15,9 +15,8 @@ IN: io.streams.throwing.tests [ [ - "asdf" &dispose [ - [ 4 swap stream-read ] - [ stream-read1 ] bi + "asdf" [ + 4 read read1 ] stream-throw-on-eof ] with-destructors ] [ stream-exhausted? ] must-fail-with diff --git a/basis/io/streams/throwing/throwing.factor b/basis/io/streams/throwing/throwing.factor index f2cdeab4f7..0b1f214d07 100644 --- a/basis/io/streams/throwing/throwing.factor +++ b/basis/io/streams/throwing/throwing.factor @@ -6,12 +6,12 @@ IN: io.streams.throwing ERROR: stream-exhausted n stream word ; - throws-on-eof-stream +> stream-element-type ; M: throws-on-eof-stream dispose stream>> dispose ; @@ -41,7 +41,7 @@ M: throws-on-eof-stream stream-read-until PRIVATE> : stream-throw-on-eof ( ..a stream quot: ( ..a stream' -- ..b ) -- ..b ) - [ ] dip call ; inline + [ ] dip with-input-stream* ; inline : throw-on-eof ( ..a quot: ( ..a -- ..b ) -- ..b ) [ input-stream get ] dip with-input-stream* ; inline