Add a lot of information on the API for a configuration section.

doc/ZConfig/zconfig.tex

@@ -69,6 +69,145 @@ The main \module{ZConfig} package exports a single function:
 \modulesynopsis{Standard section objects}
 
 
+The \module{ZConfig.Config} module provides implementations of the
+standard key-value section.  There are two implementations: the basic
+implementation used for ``internal'' sections, and a subclass that
+provides additional support for the \keyword{import} statement (used
+for the top level of a configuration and for imported resources).
+
+\begin{classdesc}{Configuration}{type, name, url}
+  A typed section with an optional name.  The type is given by the
+  \var{type} argument, and the URL the configuration is loaded from is
+  given by \var{url}.  Both \var{type} and \var{url} must be strings.
+  The optional name of the section is given by \var{name}; if there is
+  no name, \var{name} should be \code{None}.
+\end{classdesc}
+
+\begin{classdesc}{ImportingConfiguration}{type, name, url}
+  A subclass of \class{Configuration} which supports the context
+  needed to support the \keyword{import} directive.  This class
+  differs from the base class in that it offers an additional method
+  and changes the lookup semantics of the \method{get()} method.
+\end{classdesc}
+
+\class{Configuration} objects provide the following methods to
+retrieve values from the section:
+
+\begin{methoddesc}[Configuration]{get}{key\optional{, default}}
+  Returns the value for \var{key} as a string; a value from the
+  delegate section is used if needed.  If there is no value for
+  \var{key}, returns \var{default}.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{getbool}{key\optional{, default}}
+  Returns the value for \var{key} as a \class{bool}.  If there is no
+  value for \var{key}, returns \var{default}.  Conversions to
+  \class{bool} are case-insensitive; the strings \code{true},
+  \code{yes}, and \code{on} cause \code{True} to be returned; the
+  strings \code{false}, \code{no}, and \code{off} generate
+  \code{False}.  All other strings cause \exception{ValueError} to be
+  raised.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{getfloat}{key\optional{,
+        default\optional{, min\optional{, max}}}}
+  Return the value for \var{key} as a float.  If there is no
+  value for \var{key}, returns \var{default}.  If the value cannot
+  be converted to a float, \exception{ValueError} is raised.  If
+  \var{min} is given and the value is less than \var{min}, or if
+  \var{max} is given and the value is greater than \var{max},
+  \exception{ValueError} is raised.  No range checking is performed if
+  neither \var{min} nor \var{max} is given.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{getint}{key\optional{,
+        default\optional{, min\optional{, max}}}}
+  Return the value for \var{key} as an integer.  If there is no
+  value for \var{key}, returns \var{default}.  If the value cannot
+  be converted to an integer, \exception{ValueError} is raised.  If
+  \var{min} is given and the value is less than \var{min}, or if
+  \var{max} is given and the value is greater than \var{max},
+  \exception{ValueError} is raised.  No range checking is performed if
+  neither \var{min} nor \var{max} is given.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{items}{}
+  Return a list of key-value pairs from this section, including any
+  available from the delegate section.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{keys}{}
+  Return a list of keys from this section, including any available
+  from the delegate section.
+\end{methoddesc}
+
+
+The following methods are used to modify the values defined in a
+section:
+
+\begin{methoddesc}[Configuration]{addValue}{key, value}
+  Add the key \var{key} with the value \var{value}.  If there is
+  already a value for \var{key}, \exception{ConfigurationError} is
+  raised.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{setValue}{key, value}
+  Set the value for \var{key} to \var{value}.  If there is already a
+  value for \var{key}, it is replaced.  \var{key} and \var{value} must
+  be strings.
+\end{methoddesc}
+
+
+The following methods are used in retrieving and managing sections:
+
+\begin{methoddesc}[Configuration]{addChildSection}{section}
+  Add a section that is a child of the current section.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{addNamedSection}{section}
+  Add a named section to this section's context.  This is only used to
+  add sections that are descendents but not children of the current
+  section.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{getChildSections}{}
+  Returns a sequence of all child sections, in the order in which they
+  were added.
+\end{methoddesc}
+
+\begin{methoddesc}[Configuration]{getSection}{type\optional{, name}}
+  Returns a single typed section.  The type of the retrieved section
+  is given by \var{type}.  If \var{name} is given and not \code{None},
+  the name of the section must match \var{name}.  If there is no
+  section matching in both name and type, \exception{KeyError} is
+  raised.  If \var{name} is not given or is \code{None}, there must be
+  exactly one child section of type \var{type}; that section is
+  returned.  If there is more than one section of type \var{type},
+  \exception{ConfigurationConflictingSectionError} is raised.  If
+  there is no matching section and a delegate is available, it's
+  \method{getSection()} method is called to provide the return value,
+  otherwise \code{None} is returned.
+\end{methoddesc}
+
+Delegation is supported by one additional method:
+
+\begin{methoddesc}[Configuration]{setDelegate}{section}
+  Set the delegate section to \var{section} if not already set.  If
+  already set, raises \exception{ConfigurationError}.
+\end{methoddesc}
+
+
+The \class{ImportingConfiguration} subclass offers an additional
+method, normally not needed by applications, but possibly useful for
+alternate configuration parsers.  Objects returned by the
+context object's \method{createToplevelSection()} method need to
+support this interface.
+
+\begin{methoddesc}[ImportingConfiguration]{addImport}{section}
+  Add a configuration generated from an import.
+\end{methoddesc}
+
+
 \section{\module{ZConfig.Common} --- Exceptions}
 
 \declaremodule{}{ZConfig.Common}