Doc/lib/libpipes.tex

   1 \section{\module{pipes} ---
   2          Interface to shell pipelines}
   3
   4 \declaremodule{standard}{pipes}
   5   \platform{Unix}
   6 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   7 \modulesynopsis{A Python interface to \UNIX{} shell pipelines.}
   8
   9
  10 The \module{pipes} module defines a class to abstract the concept of
  11 a \emph{pipeline} --- a sequence of convertors from one file to
  12 another.
  13
  14 Because the module uses \program{/bin/sh} command lines, a \POSIX{} or
  15 compatible shell for \function{os.system()} and \function{os.popen()}
  16 is required.
  17
  18 The \module{pipes} module defines the following class:
  19
  20 \begin{classdesc}{Template}{}
  21 An abstraction of a pipeline.
  22 \end{classdesc}
  23
  24 Example:
  25
  26 \begin{verbatim}
  27 >>> import pipes
  28 >>> t=pipes.Template()
  29 >>> t.append('tr a-z A-Z', '--')
  30 >>> f=t.open('/tmp/1', 'w')
  31 >>> f.write('hello world')
  32 >>> f.close()
  33 >>> open('/tmp/1').read()
  34 'HELLO WORLD'
  35 \end{verbatim}
  36
  37
  38 \subsection{Template Objects \label{template-objects}}
  39
  40 Template objects following methods:
  41
  42 \begin{methoddesc}{reset}{}
  43 Restore a pipeline template to its initial state.
  44 \end{methoddesc}
  45
  46 \begin{methoddesc}{clone}{}
  47 Return a new, equivalent, pipeline template.
  48 \end{methoddesc}
  49
  50 \begin{methoddesc}{debug}{flag}
  51 If \var{flag} is true, turn debugging on. Otherwise, turn debugging
  52 off. When debugging is on, commands to be executed are printed, and
  53 the shell is given \code{set -x} command to be more verbose.
  54 \end{methoddesc}
  55
  56 \begin{methoddesc}{append}{cmd, kind}
  57 Append a new action at the end. The \var{cmd} variable must be a valid
  58 bourne shell command. The \var{kind} variable consists of two letters.
  59
  60 The first letter can be either of \code{'-'} (which means the command
  61 reads its standard input), \code{'f'} (which means the commands reads
  62 a given file on the command line) or \code{'.'} (which means the commands
  63 reads no input, and hence must be first.)
  64
  65 Similarly, the second letter can be either of \code{'-'} (which means
  66 the command writes to standard output), \code{'f'} (which means the
  67 command writes a file on the command line) or \code{'.'} (which means
  68 the command does not write anything, and hence must be last.)
  69 \end{methoddesc}
  70
  71 \begin{methoddesc}{prepend}{cmd, kind}
  72 Add a new action at the beginning. See \method{append()} for explanations
  73 of the arguments.
  74 \end{methoddesc}
  75
  76 \begin{methoddesc}{open}{file, mode}
  77 Return a file-like object, open to \var{file}, but read from or
  78 written to by the pipeline.  Note that only one of \code{'r'},
  79 \code{'w'} may be given.
  80 \end{methoddesc}
  81
  82 \begin{methoddesc}{copy}{infile, outfile}
  83 Copy \var{infile} to \var{outfile} through the pipe.
  84 \end{methoddesc}