Doc/lib/libcfgparser.tex

   1 \section{\module{ConfigParser} ---
   2          Configuration file parser.}
   3
   4 \declaremodule{standard}{ConfigParser}
   5
   6 \modulesynopsis{Configuration file parser.}
   7 \sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
   8
   9 This module defines the class \class{ConfigParser}. The
  10 \class{ConfigParser} class implements a basic configuration file
  11 parser language which provides a structure similar to what you would
  12 find on Microsoft Windows INI files.  You can use this to write Python
  13 programs which can be customized by end users easily.
  14
  15 The configuration file consists of sections, lead by a
  16 \samp{[section]} header and followed by \samp{name: value} entries,
  17 with continuations in the style of \rfc{822}.  The optional values
  18 can contain format strings which refer to other values in the same
  19 section, or values in a special \code{DEFAULT} section.  Additional
  20 defaults can be provided upon initialization and retrieval.  Lines
  21 beginning with \character{\#} are ignored and may be used to provide
  22 comments.
  23
  24 For example:
  25
  26 \begin{verbatim}
  27 foodir: %(dir)s/whatever
  28 \end{verbatim}
  29
  30 would resolve the \samp{\%(dir)s} to the value of dir. All reference
  31 expansions are done late, on demand.
  32
  33 Intrinsic defaults can be specified by passing them into the
  34 \class{ConfigParser} constructor as a dictionary.  Additional defaults
  35 may be passed into the \method{get} method which will override all
  36 others.
  37
  38 \begin{classdesc}{ConfigParser}{\optional{defaults}}
  39 Return a new instance of the \class{ConfigParser} class.  When
  40 \var{defaults} is given, it is initialized into the dictionairy of
  41 intrinsic defaults.  They keys must be strings, and the values must be
  42 appropriate for the \samp{\%()s} string interpolation.  Note that
  43 \var{__name__} is always an intrinsic default; it's value is the
  44 section name.
  45 \end{classdesc}
  46
  47 \begin{excdesc}{NoSectionError}
  48 Exception raised when a specified section is not found.
  49 \end{excdesc}
  50
  51 \begin{excdesc}{DuplicateSectionError}
  52 Exception raised when mutliple sections with the same name are found.
  53 \end{excdesc}
  54
  55 \begin{excdesc}{NoOptionError}
  56 Exception raised when a specified option is not found in the specified
  57 section.
  58 \end{excdesc}
  59
  60 \begin{excdesc}{InterpolationError}
  61 Exception raised when problems occur performing string interpolation.
  62 \end{excdesc}
  63
  64 \begin{excdesc}{MissingSectionHeaderError}
  65 Exception raised when attempting to parse a file which has no section
  66 headers.
  67 \end{excdesc}
  68
  69 \begin{excdesc}{ParsingError}
  70 Exception raised when errors occur attempting to parse a file.
  71 \end{excdesc}
  72
  73
  74 \subsection{ConfigParser Objects \label{ConfigParser-objects}}
  75
  76 \class{ConfigParser} instances have the following methods:
  77
  78 \begin{methoddesc}{defaults}{}
  79 Return a dictionairy containing the instance-wide defaults.
  80 \end{methoddesc}
  81
  82 \begin{methoddesc}{sections}{}
  83 Return a list of the sections available.
  84 \end{methoddesc}
  85
  86 \begin{methoddesc}{has_section}{section}
  87 Indicates whether the named section is present in the
  88 configuration. The \code{DEFAULT} section is not acknowledged.
  89 \end{methoddesc}
  90
  91 \begin{methoddesc}{options}{section}
  92 Returns a list of options available in the specified \var{section}.
  93 \end{methoddesc}
  94
  95 \begin{methoddesc}{read}{filenames}
  96 Read and parse a list of filenames.
  97 \end{methoddesc}
  98
  99 \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
 100 Get an \var{option} value for the provided \var{section}.  All the
 101 \samp{\%} interpolations are expanded in the return values, based on
 102 the defaults passed into the constructor, as well as the options
 103 \var{vars} provided, unless the \var{raw} argument is true.
 104 \end{methoddesc}
 105
 106 \begin{methoddesc}{getint}{section, option}
 107 A convenience method which coerces the \var{option} in the specified
 108 \var{section} to an integer.
 109 \end{methoddesc}
 110
 111 \begin{methoddesc}{getfloat}{section, option}
 112 A convenience method which coerces the \var{option} in the specified
 113 \var{section} to a floating point number.
 114 \end{methoddesc}
 115
 116 \begin{methoddesc}{getboolean}{section, option}
 117 A convenience method which coerces the \var{option} in the specified
 118 \var{section} to a boolean value.  Note that the only accepted values
 119 for the option are \code{0} and \code{1}, any others will raise
 120 \exception{ValueError}.
 121 \end{methoddesc}