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

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel math io ;
   4 IN: io.streams.limited
   5
   6 HELP: <limited-stream>
   7 { $values
   8      { "stream" "an input stream" } { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
   9      { "stream'" "an input stream" }
  10 }
  11 { $description "Constructs a new " { $link limited-stream } " from an existing stream. User code should use " { $link limit } " or " { $link limit-input } "." } ;
  12
  13 HELP: limit
  14 { $values
  15      { "stream" "an input stream" } { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
  16      { "stream'" "a stream" }
  17 }
  18 { $description "Changes a decoder's stream to be a limited stream, or wraps " { $snippet "stream" } " in a " { $link limited-stream } "." }
  19 { $examples "Throwing an exception:"
  20     { $example
  21         "USING: continuations io io.streams.limited io.streams.string"
  22         "kernel prettyprint ;"
  23         "["
  24         "    \"123456\" <string-reader> 3 stream-throws limit"
  25         "    100 swap stream-read ."
  26         "] [ ] recover ."
  27 """T{ limit-exceeded
  28     { n 1 }
  29     { stream
  30         T{ limited-stream
  31             { stream
  32                 T{ string-reader
  33                     { underlying "123456" }
  34                     { i 3 }
  35                 }
  36             }
  37             { mode stream-throws }
  38             { count 4 }
  39             { limit 3 }
  40         }
  41     }
  42 }"""
  43     }
  44     "Returning " { $link f } " on exhaustion:"
  45     { $example
  46         "USING: accessors continuations io io.streams.limited"
  47         "io.streams.string kernel prettyprint ;"
  48         "\"123456\" <string-reader> 3 stream-eofs limit"
  49         "100 swap stream-read ."
  50         "\"123\""
  51     }
  52 } ;
  53
  54 HELP: unlimited
  55 { $values
  56      { "stream" "an input stream" }
  57      { "stream'" "a stream" }
  58 }
  59 { $description "Returns the underlying stream of a limited stream." } ;
  60
  61 HELP: limited-stream
  62 { $values
  63     { "value" "a limited-stream class" }
  64 }
  65 { $description "Limited streams wrap other streams, changing their behavior to throw an exception or return " { $link f } " upon exhaustion." } ;
  66
  67 HELP: limit-input
  68 { $values
  69      { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
  70 }
  71 { $description "Wraps the current " { $link input-stream } " in a " { $link limited-stream } "." } ;
  72
  73 HELP: unlimited-input
  74 { $description "Returns the underlying stream of the limited-stream stored in " { $link input-stream } "." } ;
  75
  76 HELP: stream-eofs
  77 { $values
  78     { "value" { $link stream-throws } " or " { $link stream-eofs } }
  79 }
  80 { $description "If the " { $slot "mode" } " of a limited stream is set to this singleton, the stream will return " { $link f } " upon exhaustion." } ;
  81
  82 HELP: stream-throws
  83 { $values
  84     { "value" { $link stream-throws } " or " { $link stream-eofs } }
  85 }
  86 { $description "If the " { $slot "mode" } " of a limited stream is set to this singleton, the stream will throw " { $link limit-exceeded } " upon exhaustion." } ;
  87
  88 { stream-eofs stream-throws } related-words
  89
  90 ARTICLE: "io.streams.limited" "Limited input streams"
  91 "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
  92 "Wrap a stream in a limited stream:"
  93 { $subsections limit }
  94 "Wrap the current " { $link input-stream } " in a limited stream:"
  95 { $subsections limit-input }
  96 "Unlimits a limited stream:"
  97 { $subsections unlimited }
  98 "Unlimits the current " { $link input-stream } ":"
  99 { $subsections unlimited-input }
 100 "Make a limited stream throw an exception on exhaustion:"
 101 { $subsections stream-throws }
 102 "Make a limited stream return " { $link f } " on exhaustion:"
 103 { $subsections stream-eofs } ;
 104
 105 ABOUT: "io.streams.limited"