Fix io.streams.throwing word and write docs for it. Fix typo in io.streams.limited...

diff --git a/basis/io/streams/limited/limited-docs.factor b/basis/io/streams/limited/limited-docs.factor
index 5a06dedf0d890e2a253ca8e2525dd706c7e301b1..18b4545fde4d1185d78aa4aba852998e1870c6fc 100644 (file)
--- 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 (file)
index 0000000..14ceb6c
--- /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 <throws-on-eof-stream> } " 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" <string-reader> [ 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 1c9e32914ba338687e63e239eba4fbede7b0ad6b..f1567be84227414c9f13d3d856a169cb0aa944c5 100644 (file)
--- 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" <string-reader> &dispose [
-            [ 4 swap stream-read ]
-            [ stream-read1 ] bi
+        "asdf" <string-reader> [
+            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 f2cdeab4f733d939c00646f566d40c1759370bb0..0b1f214d07de92c0fec8083e676c692e7cd74826 100644 (file)
--- 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 ;
 
-<PRIVATE
-
 TUPLE: throws-on-eof-stream stream ;
 
 C: <throws-on-eof-stream> throws-on-eof-stream
 
+<PRIVATE
+
 M: throws-on-eof-stream stream-element-type 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 )
-    [ <throws-on-eof-stream> ] dip call ; inline
+    [ <throws-on-eof-stream> ] dip with-input-stream* ; inline
 
 : throw-on-eof ( ..a quot: ( ..a -- ..b ) -- ..b )
     [ input-stream get <throws-on-eof-stream> ] dip with-input-stream* ; inline