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