[Zope-Checkins] CVS: Zope/lib/python/ZConfig/doc - zconfig.tex:1.5.4.2

[Chris McDonough]

Update of /cvs-repository/Zope/lib/python/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv22840/doc

Modified Files:
      Tag: chrism-install-branch
	zconfig.tex 
Log Message:
Merging ZConfig on chrism-install-branch with its HEAD.


=== Zope/lib/python/ZConfig/doc/zconfig.tex 1.5.4.1 => 1.5.4.2 ===
--- Zope/lib/python/ZConfig/doc/zconfig.tex:1.5.4.1	Thu Oct 10 14:29:12 2002
+++ Zope/lib/python/ZConfig/doc/zconfig.tex	Tue Oct 15 20:53:38 2002
@@ -37,23 +37,273 @@
 License, version 2.0.
 
 The \module{ZConfig} package has been tested with Python 2.1 and 2.2.
+Python 2.0 is not supported.
 It only relies on the Python standard library.
 
 
 \section{Configuration Syntax \label{syntax}}
 
+Like the \ulink{\module{ConfigParser}}
+{http://www.python.org/doc/current/lib/module-ConfigParser.html}
+format, this format supports key-value pairs arranged in sections.
+Unlike the \module{ConfigParser} format, sections are typed and can be
+organized hierarchically, and support delegation of value lookup to
+other sections.  Additional files may be imported or included at the
+top level if needed.  Though both formats are substantially
+line-oriented, this format is more flexible.
+
+The intent of supporting nested section is to allow setting up the
+configurations for loosely-associated components in a container.  For
+example, each process running on a host might get its configuration
+section from that host's section of a shared configuration file.  Each
+section may use the delegation syntax to share a base configuration
+with other components of the same type.
+
+The top level of a configuration file consists of a series of imports,
+inclusions, key-value pairs, and sections.
+
+Comments can be added on lines by themselves.  A comment has a
+\character{\#} as the first non-space character and extends to the end
+of the line:
+
+\begin{verbatim}
+# This is a comment
+\end{verbatim}
+
+An import is expressed like this:
+
+\begin{verbatim}
+import defaults.conf
+\end{verbatim}
+
+while an inclusion is expressed like this:
+
+\begin{verbatim}
+include defaults.conf
+\end{verbatim}
+
+The resource to be imported or included can be a relative or absolute
+URL, resolved relative to the URL of the resource the import is
+located in.
+
+
+A key-value pair is expressed like this:
+
+\begin{verbatim}
+key value
+\end{verbatim}
+
+The key may include any non-white characters except for parentheses.
+The value contains all the characters between the key and the end of
+the line, with surrounding whitespace removed.
+
+Since comments must be on lines by themselves, the \character{\#}
+character can be part of a value:
+
+\begin{verbatim}
+key value # still part of the value
+\end{verbatim}
+
+Sections may be either empty or non-empty.  An empty section may be
+used to provide an alias for another section.
+
+A non-empty section starts with a header, contains configuration
+data on subsequent lines, and ends with a terminator.
+
+The header for a non-empty section has this form (square brackets
+denote optional parts):
+
+\begin{alltt}
+<\var{section-type} \optional{\var{name}} \optional{(\var{basename})} >
+\end{alltt}
+
+\var{section-type}, \var{name}, and \var{basename} all have the same
+syntactic constraints as key names.
+
+The terminator looks like this:
+
+\begin{verbatim}
+</\var{section-type}>
+\end{verbatim}
+
+The configuration data in a non-empty section consists of a sequence
+of one or more key-value pairs and sections.  For example:
+
+\begin{verbatim}
+<my-section>
+    key-1 value-1
+    key-2 value-2
+
+    <another-section>
+        key-3 value-3
+    </another-section>
+</my-section>
+\end{verbatim}
+
+(The indentation is used here for clarity, but is not required for
+syntactic correctness.)
+
+If the \var{basename} component is given for a section header
+(regardless of the presence of the name component), that section
+acquires additional values from another section having \var{basename}
+as its \var{name} and an application-supported type.  For example, an
+application that supports the types \code{host} and \code{hostclass}
+might use configuration like this:
+
+\begin{verbatim}
+<hostclass secondary>
+    server-type secondary
+    port 1234
+</hostclass>
+
+<host grendel (secondary)>
+    port 2345
+</host>
+\end{verbatim}
+
+In this application, sections of type \code{host} would be allowed to
+acquire configuration data only from the \code{hostclass} type, so the
+section named \code{grendel} would only be allowed to to acquire
+configuration data from a section with type \code{hostclass} and name
+\code{secondary}.  The \code{hostclass} section named \code{secondary}
+could in turn acquire additional key-value pairs from some other
+section, based on the allowed type relationships of the
+\code{hostclass} type.
+
+The header for empty sections is similar to that of non-empty
+sections:
+
+\begin{alltt}
+<\var{section-type} \optional{\var{name}} \optional{(\var{basename})} />
+\end{alltt}
+
 
 \section{\module{ZConfig} --- Basic configuration support}
 
 \declaremodule{}{ZConfig}
 \modulesynopsis{Configuration package}
 
+The main \module{ZConfig} package exports a single function:
+
+\begin{funcdesc}{load}{url}
+  Load and return a configuration from a URL or pathname given by
+  \var{url}.  \var{url} may be a URL, absolute pathname, or relative
+  pathname.  Fragment identifiers are not supported.
+\end{funcdesc}
+
 
 \section{\module{ZConfig.Context} --- Application context}
 
 \declaremodule{}{ZConfig.Context}
 \modulesynopsis{Application context}
 
+The \module{ZConfig} package uses the idea of an \dfn{application
+context} to consolidate the connections between the different
+components of the package.  Most applications should not need to worry
+about the application context at all; the \function{load()} function
+in the \module{ZConfig} module uses the default context implementation
+to glue everything together.
+
+For applications that need to change the way their configuration data
+is handled, the best way to do it is to provide an alternate
+application context.  The default implementation is designed to be
+subclassed, so this should not prove to be difficult.
+
+\begin{classdesc}{Context}{}
+  Constructs an instance of the default application context.  This is
+  implemented as an object to allow applications to adjust the way
+  components are created and how they are knit together.  This
+  implementation is designed to be used once and discarded; changing
+  this assumption in a subclass would probably lead to a complete
+  replacement of the class.
+\end{classdesc}
+
+The context object offers one method that is intended to be called
+once:
+
+\begin{methoddesc}{load}{url}
+  Load and return a configuration object from a resource.  The
+  resource is identified by a URL or path given as \var{url}.
+  Fragment identifiers are not supported.
+\end{methoddesc}
+
+The following methods are defined to be individually overridable by
+subclasses; this should suffice for most context specialization.
+
+\begin{methoddesc}{createImportedSection}{parent, url}
+  Create a new section that represents a section loaded using
+  \keyword{import}.  The returned section should be conform to the
+  interface of the \class{ImportingConfiguration} class (see the
+  \refmodule{ZConfig.Config} module's documentation for more
+  information on this interface).  \var{parent} is the section that
+  contains the \keyword{import} statement, and \var{url} is the
+  resource that will be loaded into the new section.  This method
+  should not cause the \method{addImport()} of \var{parent} to be
+  called, nor should it cause the resource to actually be loaded.
+  Since the new section represents the top level of an external
+  resource, it's \member{type} and \member{name} attributes should be
+  \code{None}.
+\end{methoddesc}
+
+\begin{methoddesc}{createNestedSection}{parent, type, name, delegatename}
+  Create a new section that represents a child of the section given by
+  \var{parent}.  \var{type} is the type that should be given to the
+  new section and should always be a string.  \var{name} should be the
+  name of the section, and should be a string or \code{None}.
+  \var{delegatename} should also be a string or \code{None}; if not
+  \code{None}, this will be the name of the section eventually passed
+  to the \method{setDelegate()} method of the returned section.  The
+  returned section should be conform to the interface of the
+  \class{Configuration} class (see the \refmodule{ZConfig.Config}
+  module's documentation for more information on this interface).
+\end{methoddesc}
+
+\begin{methoddesc}{createToplevelSection}{url}
+  Create a new section that represents a section loaded and returned
+  by the \method{load()} method of the context object.  The returned
+  section should be conform to the interface of the
+  \class{ImportingConfiguration} class (see the
+  \refmodule{ZConfig.Config} module's documentation for more
+  information on this interface).  \var{url} is the resource that will
+  be loaded into the new section.
+  Since the new section represents the top level of an external
+  resource, it's \member{type} and \member{name} attributes should be
+  \code{None}.
+\end{methoddesc}
+
+\begin{methoddesc}{getDelegateType}{type}
+  Return the type of sections to which sections of type \var{type} may
+  delegate to, or \code{None} if they are not allowed to do so.
+\end{methoddesc}
+
+\begin{methoddesc}{parse}{file, section, url}
+  This method allows subclasses to replace the resource parser.
+  \var{file} is a file object which provides the content of the
+  resource, \var{section} is the section object into which the
+  contents of the resources should be loaded, and \var{url} is the URL
+  from which the resource is being loaded.  The default implementation
+  implements the configuration language described in
+  section~\ref{syntax} using the \function{Parse()} function provided
+  by the \refmodule{ZConfig.ApacheStyle} module.  Providing an
+  alternate parser is most easily done by overriding this method and
+  calling the parser support methods of the context object from the
+  new parser, though different strategies are possible.
+\end{methoddesc}
+
+The following methods are provided to make it easy for parsers to
+support common semantics for the \keyword{import} and
+\keyword{include} statements, if those are defined for the syntax
+implemented by the alternate parser.
+
+\begin{methoddesc}{importConfiguration}{parent, url}
+\end{methoddesc}
+
+\begin{methoddesc}{includeConfiguration}{parent, url}
+\end{methoddesc}
+
+\begin{methoddesc}{nestSection}{parent, type, name, delegatename}
+\end{methoddesc}
+
 
 \section{\module{ZConfig.Config} --- Section objects}
 
@@ -61,16 +311,190 @@
 \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}
 \modulesynopsis{Exceptions}
 
+\begin{excdesc}{ConfigurationError}
+  Base class for exceptions specific to the \module{ZConfig} package.
+  All instances provide a \member{message} attribute that describes
+  the specific error.
+\end{excdesc}
+
+\begin{excdesc}{ConfigurationSyntaxError}
+  Exception raised when a configuration source does not conform to the
+  allowed syntax.  In addition to the \member{message} attribute,
+  exceptions of this type offer the \member{url} and \member{lineno}
+  attributes, which provide the URL and line number at which the error
+  was detected.
+\end{excdesc}
+
+\begin{excdesc}{ConfigurationTypeError}
+\end{excdesc}
+
+\begin{excdesc}{ConfigurationMissingSectionError}
+\end{excdesc}
+
+\begin{excdesc}{ConfigurationConflictingSectionError}
+\end{excdesc}
+
 
 \section{\module{ZConfig.ApacheStyle} --- Apache-style parser}
 
 \declaremodule{}{ZConfig.ApacheStyle}
 \modulesynopsis{Parser for Apache-style configurations}
+
+The \module{ZConfig.ApacheStyle} module implements the configuration
+parser.  Most applications will not need to use this module directly.
+
+This module provides a single function:
+
+\begin{funcdesc}{Parse}{file, context, section, url}
+  Parse text from the open file object \var{file}.  The application
+  context is given as \var{context}, the section object that values
+  and sections should be added to is given as \var{section}, and the
+  URL of the resource being parsed is given in \var{url}.
+\end{funcdesc}
 
 
 \section{\module{ZConfig.Interpolation} --- String interpolation}