Doc/libmailcap.tex

   1 \section{Standard Module \module{mailcap}}
   2 \label{module-mailcap}
   3 \stmodindex{mailcap}
   4
   5 Mailcap files are used to configure how MIME-aware applications such
   6 as mail readers and Web browsers react to files with different MIME
   7 types. (The name ``mailcap'' is derived from the phrase ``mail
   8 capability''.)  For example, a mailcap file might contain a line like
   9 \samp{video/mpeg; xmpeg \%s}.  Then, if the user encounters an email
  10 message or Web document with the MIME type \mimetype{video/mpeg},
  11 \samp{\%s} will be replaced by a filename (usually one belonging to a
  12 temporary file) and the \program{xmpeg} program can be automatically
  13 started to view the file.
  14
  15 The mailcap format is documented in \rfc{1524}, ``A User Agent
  16 Configuration Mechanism For Multimedia Mail Format Information,'' but
  17 is not an Internet standard.  However, mailcap files are supported on
  18 most \UNIX{} systems.
  19
  20 \begin{funcdesc}{findmatch}{caps, MIMEtype%
  21                             \optional{, key\optional{,
  22                             filename\optional{, plist}}}}
  23 Return a 2-tuple; the first element is a string containing the command
  24 line to be executed
  25 (which can be passed to \code{os.system()}), and the second element is
  26 the mailcap entry for a given MIME type.  If no matching MIME
  27 type can be found, \code{(None, None)} is returned.
  28
  29 \var{key} is the name of the field desired, which represents the type
  30 of activity to be performed; the default value is 'view', since in the
  31 most common case you simply want to view the body of the MIME-typed
  32 data.  Other possible values might be 'compose' and 'edit', if you
  33 wanted to create a new body of the given MIME type or alter the
  34 existing body data.  See \rfc{1524} for a complete list of these
  35 fields.
  36
  37 \var{filename} is the filename to be substituted for \samp{\%s} in the
  38 command line; the default value is
  39 \code{'/dev/null'} which is almost certainly not what you want, so
  40 usually you'll override it by specifying a filename.
  41
  42 \var{plist} can be a list containing named parameters; the default
  43 value is simply an empty list.  Each entry in the list must be a
  44 string containing the parameter name, an equals sign (\code{=}), and the
  45 parameter's value.  Mailcap entries can contain
  46 named parameters like \code{\%\{foo\}}, which will be replaced by the
  47 value of the parameter named 'foo'.  For example, if the command line
  48 \samp{showpartial \%\{id\}\ \%\{number\}\ \%\{total\}}
  49 was in a mailcap file, and \var{plist} was set to \code{['id=1',
  50 'number=2', 'total=3']}, the resulting command line would be
  51 \code{"showpartial 1 2 3"}.
  52
  53 In a mailcap file, the "test" field can optionally be specified to
  54 test some external condition (e.g., the machine architecture, or the
  55 window system in use) to determine whether or not the mailcap line
  56 applies.  \code{findmatch()} will automatically check such conditions
  57 and skip the entry if the check fails.
  58 \end{funcdesc}
  59
  60 \begin{funcdesc}{getcaps}{}
  61 Returns a dictionary mapping MIME types to a list of mailcap file
  62 entries. This dictionary must be passed to the \code{findmatch()}
  63 function.  An entry is stored as a list of dictionaries, but it
  64 shouldn't be necessary to know the details of this representation.
  65
  66 The information is derived from all of the mailcap files found on the
  67 system. Settings in the user's mailcap file \file{\$HOME/.mailcap}
  68 will override settings in the system mailcap files
  69 \file{/etc/mailcap}, \file{/usr/etc/mailcap}, and
  70 \file{/usr/local/etc/mailcap}.
  71 \end{funcdesc}
  72
  73 An example usage:
  74 \begin{verbatim}
  75 >>> import mailcap
  76 >>> d=mailcap.getcaps()
  77 >>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
  78 ('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
  79 \end{verbatim}