2009-01-20 14:21:58 -05:00
! Copyright (C) 2009 Doug Coleman.
! See http://factorcode.org/license.txt for BSD license.
USING: help.markup help.syntax kernel math io ;
IN: io.streams.limited
HELP: <limited-stream>
{ $values
2009-03-20 02:47:09 -04:00
{ "stream" "an input stream" } { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
2009-01-20 14:21:58 -05:00
{ "stream'" "an input stream" }
}
2009-01-20 16:42:41 -05:00
{ $description "Constructs a new " { $link limited-stream } " from an existing stream. User code should use " { $link limit } " or " { $link limit-input } "." } ;
HELP: limit
{ $values
2009-03-20 02:47:09 -04:00
{ "stream" "an input stream" } { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
2009-01-20 16:42:41 -05:00
{ "stream'" "a stream" }
}
{ $description "Changes a decoder's stream to be a limited stream, or wraps " { $snippet "stream" } " in a " { $link limited-stream } "." }
2009-01-20 14:21:58 -05:00
{ $examples "Throwing an exception:"
{ $example
"USING: continuations io io.streams.limited io.streams.string"
"kernel prettyprint ;"
"["
2009-01-20 16:42:41 -05:00
" \"123456\" <string-reader> 3 stream-throws limit"
2009-01-20 14:21:58 -05:00
" 100 swap stream-read ."
"] [ ] recover ."
2009-10-03 20:39:06 -04:00
"" "T{ limit-exceeded
{ n 1 }
{ stream
T{ limited-stream
{ stream
T{ string-reader
{ underlying "123456" }
{ i 3 }
}
}
{ mode stream-throws }
{ count 4 }
{ limit 3 }
}
}
}"""
2009-01-20 14:21:58 -05:00
}
"Returning " { $link f } " on exhaustion:"
{ $example
"USING: accessors continuations io io.streams.limited"
"io.streams.string kernel prettyprint ;"
2009-01-20 16:42:41 -05:00
"\"123456\" <string-reader> 3 stream-eofs limit"
2009-01-20 14:21:58 -05:00
"100 swap stream-read ."
"\"123\""
}
} ;
2009-03-20 02:47:09 -04:00
HELP: unlimited
2009-01-20 14:21:58 -05:00
{ $values
2009-01-20 16:42:41 -05:00
{ "stream" "an input stream" }
2009-01-20 14:21:58 -05:00
{ "stream'" "a stream" }
}
2009-01-20 16:42:41 -05:00
{ $description "Returns the underlying stream of a limited stream." } ;
2009-01-20 14:21:58 -05:00
HELP: limited-stream
{ $values
{ "value" "a limited-stream class" }
}
2009-01-20 16:42:41 -05:00
{ $description "Limited streams wrap other streams, changing their behavior to throw an exception or return " { $link f } " upon exhaustion." } ;
2009-01-20 14:21:58 -05:00
HELP: limit-input
{ $values
2009-03-20 02:47:09 -04:00
{ "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
2009-01-20 14:21:58 -05:00
}
{ $description "Wraps the current " { $link input-stream } " in a " { $link limited-stream } "." } ;
2009-03-20 02:47:09 -04:00
HELP: unlimited-input
2009-01-20 16:42:41 -05:00
{ $description "Returns the underlying stream of the limited-stream stored in " { $link input-stream } "." } ;
2009-01-20 14:21:58 -05:00
HELP: stream-eofs
{ $values
2009-03-20 02:47:09 -04:00
{ "value" { $link stream-throws } " or " { $link stream-eofs } }
2009-01-20 14:21:58 -05:00
}
{ $description "If the " { $slot "mode" } " of a limited stream is set to this singleton, the stream will return " { $link f } " upon exhaustion." } ;
HELP: stream-throws
{ $values
2009-03-20 02:47:09 -04:00
{ "value" { $link stream-throws } " or " { $link stream-eofs } }
2009-01-20 14:21:58 -05:00
}
{ $description "If the " { $slot "mode" } " of a limited stream is set to this singleton, the stream will throw " { $link limit-exceeded } " upon exhaustion." } ;
{ stream-eofs stream-throws } related-words
ARTICLE: "io.streams.limited" "Limited input streams"
2009-10-05 17:16:59 -04:00
"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
2009-01-20 14:21:58 -05:00
"Wrap a stream in a limited stream:"
2009-10-01 15:56:36 -04:00
{ $subsections limit }
2009-01-20 14:21:58 -05:00
"Wrap the current " { $link input-stream } " in a limited stream:"
2009-10-01 15:56:36 -04:00
{ $subsections limit-input }
2009-01-20 16:42:41 -05:00
"Unlimits a limited stream:"
2009-10-01 15:56:36 -04:00
{ $subsections unlimited }
2009-01-20 16:42:41 -05:00
"Unlimits the current " { $link input-stream } ":"
2009-10-01 15:56:36 -04:00
{ $subsections unlimited-input }
2009-01-20 14:21:58 -05:00
"Make a limited stream throw an exception on exhaustion:"
2009-10-01 15:56:36 -04:00
{ $subsections stream-throws }
2009-01-20 14:21:58 -05:00
"Make a limited stream return " { $link f } " on exhaustion:"
2009-10-01 15:56:36 -04:00
{ $subsections stream-eofs } ;
2009-01-20 14:21:58 -05:00
ABOUT: "io.streams.limited"