Doc/lib/libquopri.tex

   1 \section{\module{quopri} ---
   2          Encode and decode MIME quoted-printable data}
   3
   4 \declaremodule{standard}{quopri}
   5 \modulesynopsis{Encode and decode files using the MIME
   6                 quoted-printable encoding.}
   7
   8
   9 This module performs quoted-printable transport encoding and decoding,
  10 as defined in \rfc{1521}: ``MIME (Multipurpose Internet Mail
  11 Extensions) Part One: Mechanisms for Specifying and Describing the
  12 Format of Internet Message Bodies''.  The quoted-printable encoding is
  13 designed for data where there are relatively few nonprintable
  14 characters; the base64 encoding scheme available via the
  15 \refmodule{base64} module is more compact if there are many such
  16 characters, as when sending a graphics file.
  17 \indexii{quoted-printable}{encoding}
  18 \index{MIME!quoted-printable encoding}
  19
  20
  21 \begin{funcdesc}{decode}{input, output\optional{,header}}
  22 Decode the contents of the \var{input} file and write the resulting
  23 decoded binary data to the \var{output} file.
  24 \var{input} and \var{output} must either be file objects or objects that
  25 mimic the file object interface. \var{input} will be read until
  26 \code{\var{input}.readline()} returns an empty string.
  27 If the optional argument \var{header} is present and true, underscore
  28 will be decoded as space. This is used to decode
  29 ``Q''-encoded headers as described in \rfc{1522}: ``MIME (Multipurpose Internet Mail Extensions)
  30 Part Two: Message Header Extensions for Non-ASCII Text''.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{encode}{input, output, quotetabs}
  34 Encode the contents of the \var{input} file and write the resulting
  35 quoted-printable data to the \var{output} file.
  36 \var{input} and \var{output} must either be file objects or objects that
  37 mimic the file object interface. \var{input} will be read until
  38 \code{\var{input}.readline()} returns an empty string.
  39 \var{quotetabs} is a flag which controls whether to encode embedded
  40 spaces and tabs; when true it encodes such embedded whitespace, and
  41 when false it leaves them unencoded.  Note that spaces and tabs
  42 appearing at the end of lines are always encoded, as per \rfc{1521}.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{decodestring}{s\optional{,header}}
  46 Like \function{decode()}, except that it accepts a source string and
  47 returns the corresponding decoded string.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{encodestring}{s\optional{, quotetabs}}
  51 Like \function{encode()}, except that it accepts a source string and
  52 returns the corresponding encoded string.  \var{quotetabs} is optional
  53 (defaulting to 0), and is passed straight through to
  54 \function{encode()}.
  55 \end{funcdesc}
  56
  57
  58 \begin{seealso}
  59   \seemodule{mimify}{General utilities for processing of MIME messages.}
  60   \seemodule{base64}{Encode and decode MIME base64 data}
  61 \end{seealso}