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

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:"

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"

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

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