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

   1 USING: help.markup help.syntax io continuations quotations ;
   2 IN: io.streams.duplex
   3
   4 ARTICLE: "io.streams.duplex" "Duplex streams"
   5 "Duplex streams combine an input stream and an output stream into a bidirectional stream."
   6 { $subsections
   7     duplex-stream
   8     <duplex-stream>
   9 }
  10 "A pair of combinators for rebinding both default streams at once:"
  11 { $subsections
  12     with-stream
  13     with-stream*
  14 } ;
  15
  16 ABOUT: "io.streams.duplex"
  17
  18 HELP: duplex-stream
  19 { $class-description "A bidirectional stream wrapping an input and output stream." } ;
  20
  21 HELP: <duplex-stream>
  22 { $values { "in" "an input stream" } { "out" "an output stream" } { "duplex-stream" duplex-stream } }
  23 { $description "Creates a duplex stream. Writing to a duplex stream will write to " { $snippet "out" } ", and reading from a duplex stream will read from " { $snippet "in" } ". Closing a duplex stream closes both the input and output streams." } ;
  24
  25 HELP: with-stream
  26 { $values { "stream" duplex-stream } { "quot" quotation } }
  27 { $description "Calls the quotation in a new dynamic scope, with both " { $link input-stream } " and " { $link output-stream } " rebound to " { $snippet "stream" } ", which must be a duplex stream. The stream is closed if the quotation returns or throws an error." } ;
  28
  29 HELP: with-stream*
  30 { $values { "stream" duplex-stream } { "quot" quotation } }
  31 { $description "Calls the quotation in a new dynamic scope, with both " { $link input-stream } " and " { $link output-stream } " rebound to " { $snippet "stream" } ", which must be a duplex stream." }
  32 { $notes "This word does not close the stream. Compare with " { $link with-stream } "." } ;
  33
  34 HELP: <encoder-duplex>
  35 { $values { "stream-in" "an input stream" }
  36     { "stream-out" "an output stream" }
  37     { "encoding" "an encoding descriptor" }
  38     { "duplex" "an encoded duplex stream" } }
  39 { $description "Wraps the given streams in an encoder or decoder stream, and puts them together in a duplex stream for input and output. If either input stream is already encoded, that encoding is stripped off before it is reencoded. The encoding descriptor must conform to the " { $link "encodings-protocol" } "." }
  40 $low-level-note ;