basis/io/streams/throwing/throwing-docs.factor

   1 ! Copyright (C) 2010 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io math quotations words ;
   4 IN: io.streams.throwing
   5
   6 HELP: stream-exhausted
   7 { $values
   8     { "n" integer } { "stream" "an input stream" } { "word" word }
   9 }
  10 { $description "The exception that gets thrown when a stream is exhausted." } ;
  11
  12 HELP: stream-throw-on-eof
  13 { $values
  14     { "stream" "an input stream" } { "quot" quotation }
  15 }
  16 { $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." }
  17 "This example will throw a " { $link stream-exhausted } " exception:"
  18 { $unchecked-example "USING: io.streams.throwing prettyprint ;
  19 \"abc\" <string-reader> [ 4 read ] stream-throw-on-eof"
  20 ""
  21 } ;
  22
  23 HELP: throw-on-eof
  24 { $values
  25     { "quot" quotation }
  26 }
  27 { $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
  28 "This example will throw a " { $link stream-exhausted } " exception:"
  29 { $unchecked-example "USING: io.streams.throwing prettyprint ;
  30 \"abc\" [ [ 4 read ] throw-on-eof ] with-string-reader"
  31 ""
  32 } ;
  33
  34 ARTICLE: "io.streams.throwing" "Throwing exceptions on stream exhaustion"
  35 "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
  36 "A general combinator to wrap any stream:"
  37 { $subsections stream-throw-on-eof }
  38 "A combinator for the " { $link input-stream } " variable:"
  39 { $subsections throw-on-eof }
  40 "The exception itself:"
  41 { $subsections stream-exhausted } ;
  42
  43 ABOUT: "io.streams.throwing"