basis/io/pipes/pipes-docs.factor

   1 USING: help.markup help.syntax continuations destructors io ;
   2 IN: io.pipes
   3
   4 HELP: pipe
   5 { $class-description "A low-level pipe. Instances are created by calling " { $link (pipe) } " and closed by calling " { $link dispose } "." } ;
   6
   7 HELP: (pipe)
   8 { $values { "pipe" pipe } }
   9 { $description "Opens a new pipe. This is a low-level word; the " { $link <pipe> } " and " { $link run-pipeline } " words can be used in most cases instead." } ;
  10
  11 HELP: <pipe>
  12 { $values { "encoding" "an encoding specifier" } { "stream" "a bidirectional stream" } }
  13 { $description "Opens a new pipe and wraps it in a stream. Data written from the stream can be read back from the same stream instance." }
  14 { $notes "Pipe streams must be disposed by calling " { $link dispose } " or " { $link with-disposal } " to avoid resource leaks." } ;
  15
  16 HELP: run-pipeline
  17 { $values { "seq" "a sequence of pipeline components" } { "results" "a sequence of pipeline results" } }
  18 { $description
  19     "Creates a pipe between each pipeline component, with the output of each component becoming the input of the next."
  20     $nl
  21     "The first component reads input from " { $link input-stream } " and the last component writes output to " { $link output-stream } "."
  22     $nl
  23     "Each component runs in its own thread, and the word returns when all components finish executing. Each component outputs a result value."
  24     $nl
  25     "Pipeline components must be one of the following:"
  26     { $list
  27         { "A quotation. The quotation is called with both " { $link input-stream } " and " { $link output-stream } " rebound, except for the first and last pipeline components, and it must output a single value." }
  28         { "A process launch descriptor. See " { $link "io.launcher.descriptors" } "." }
  29     }
  30 }
  31 { $examples
  32     "Print the lines of a log file which contain the string ``error'', sort them and filter out duplicates, using Unix shell commands only:"
  33     { $code "{ \"cat log.txt\" \"grep error\" \"sort\" \"uniq\" } run-pipeline" }
  34 } ;
  35
  36 ARTICLE: "io.pipes" "Pipes"
  37 "A " { $emphasis "pipe" } " is a unidirectional channel for transfer of bytes. Data written to one end of the pipe can be read from the other. Pipes can be used to pass data between processes; they can also be used within a single process to implement communication between coroutines."
  38 $nl
  39 "Low-level pipes:"
  40 { $subsection pipe }
  41 { $subsection (pipe) }
  42 "High-level pipe streams:"
  43 { $subsection <pipe> }
  44 "Pipelines of coroutines and processes:"
  45 { $subsection run-pipeline } ;
  46
  47 ABOUT: "io.pipes"