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 { $subsection duplex-stream }
   7 { $subsection <duplex-stream> }
   8 "A pair of combinators for rebinding both default streams at once:"
   9 { $subsection with-stream }
  10 { $subsection with-stream* } ;
  11
  12 ABOUT: "io.streams.duplex"
  13
  14 HELP: duplex-stream
  15 { $class-description "A bidirectional stream wrapping an input and output stream." } ;
  16
  17 HELP: <duplex-stream>
  18 { $values { "in" "an input stream" } { "out" "an output stream" } { "duplex-stream" duplex-stream } }
  19 { $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." } ;
  20
  21 HELP: with-stream
  22 { $values { "stream" duplex-stream } { "quot" quotation } }
  23 { $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." } ;
  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." }
  28 { $notes "This word does not close the stream. Compare with " { $link with-stream } "." } ;
  29
  30 HELP: <encoder-duplex>
  31 { $values { "stream-in" "an input stream" }
  32     { "stream-out" "an output stream" }
  33     { "encoding" "an encoding descriptor" }
  34     { "duplex" "an encoded duplex stream" } }
  35 { $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" } "." }
  36 $low-level-note ;