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

Andreas Jung andreas@andreas-jung.com
Sat, 9 Nov 2002 03:43:29 -0500


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

Modified Files:
      Tag: ajung-restructuredtext-integration-branch
	zconfig.tex 
Log Message:
merge from trunk


=== Zope/lib/python/ZConfig/doc/zconfig.tex 1.11 => 1.11.4.1 ===
--- Zope/lib/python/ZConfig/doc/zconfig.tex:1.11	Mon Oct 21 14:59:54 2002
+++ Zope/lib/python/ZConfig/doc/zconfig.tex	Sat Nov  9 03:42:58 2002
@@ -183,7 +183,7 @@
 \declaremodule{}{ZConfig}
 \modulesynopsis{Configuration package}
 
-The main \module{ZConfig} package exports a single function:
+The main \module{ZConfig} package exports two convenience functions:
 
 \begin{funcdesc}{load}{url}
   Load and return a configuration from a URL or pathname given by
@@ -191,6 +191,14 @@
   pathname.  Fragment identifiers are not supported.
 \end{funcdesc}
 
+\begin{funcdesc}{loadfile}{file\optional{, url}}
+  Load and return a configuration from an opened file object.
+  If \var{url} is omitted, one will be computed based on the
+  \member{name} attribute of \var{file}, if it exists.  If no URL can
+  be determined, all \keyword{include} statements in the configuration
+  must use absolute URLs.
+\end{funcdesc}
+
 
 \section{\module{ZConfig.Context} --- Application context}
 
@@ -218,8 +226,9 @@
   replacement of the class.
 \end{classdesc}
 
-The context object offers one method that is intended to be called
-once:
+The context object offers two methods that are used to load a
+configuration.  Exactly one of these methods should be called, and it
+should be called only once:
 
 \begin{methoddesc}{load}{url}
   Load and return a configuration object from a resource.  The
@@ -227,6 +236,14 @@
   Fragment identifiers are not supported.
 \end{methoddesc}
 
+\begin{methoddesc}{loadfile}{file\optional{, url}}
+  Load and return a configuration from an opened file object.
+  If \var{url} is omitted, one will be computed based on the
+  \member{name} attribute of \var{file}, if it exists.  If no URL can
+  be determined, all \keyword{include} statements in the configuration
+  must use absolute URLs.
+\end{methoddesc}
+
 The following methods are defined to be individually overridable by
 subclasses; this should suffice for most context specialization.
 
@@ -448,6 +465,17 @@
   already set, raises \exception{ConfigurationError}.
 \end{methoddesc}
 
+This method is called on each section when the configuration is
+completely loaded.  This is called for all sections contained within a
+section before it is called on the containing section.
+
+\begin{methoddesc}[Configuration]{finish}{}
+  Perform any initialization for the section object that needs to
+  occur after the content of the section is loaded and delegation
+  chains have been established.  (This method may not have been called
+  for delegates before being called on the delegating section.)  The
+  default implementation does nothing.
+\end{methoddesc}
 
 The \class{ImportingConfiguration} subclass offers an additional
 method, normally not needed by applications, but possibly useful for
@@ -507,10 +535,10 @@
 \end{funcdesc}
 
 
-\section{\module{ZConfig.Interpolation} --- String interpolation}
+\section{\module{ZConfig.Substitution} --- String substitution}
 
-\declaremodule{}{ZConfig.Interpolation}
-\modulesynopsis{Shell-style string interpolation helper}
+\declaremodule{}{ZConfig.Substitution}
+\modulesynopsis{Shell-style string substitution helper}
 
 This module provides a basic substitution facility similar to that
 found in the Bourne shell (\program{sh} on most \UNIX{} platforms).  
@@ -536,47 +564,53 @@
 \end{description}
 
 In each case, \var{name} is a non-empty sequence of alphanumeric and
-underscore characters not starting with a digit.  If there is not
-a replacement for \var{name}, it is replaced with an empty string.
+underscore characters not starting with a digit.  If there is not a
+replacement for \var{name}, these functions search up the containment
+chain for a suitable replacement.  The containment chain is found by
+looking for an attribute \member{container} on the \var{mapping}
+object; the value of that attribute should be another mapping or
+\code{None}.  If this search does not yield a value, an empty string
+is used.
 
 For these functions, the \var{mapping} argument can be a \class{dict},
 or any type that supports the \method{get()} method of the mapping
-protocol.
+protocol.  The \member{container} attribute used to search the
+containment chain is optional.
 
-\begin{funcdesc}{interpolate}{s, mapping}
-  Interpolate values from \var{mapping} into \var{s}.  Replacement
+\begin{funcdesc}{substitute}{s, mapping}
+  Substitute values from \var{mapping} into \var{s}.  Replacement
   values are copied into the result without further interpretation.
-  Raises \exception{InterpolationSyntaxError} if there are malformed
+  Raises \exception{SubstitutionSyntaxError} if there are malformed
   constructs in \var{s}.
 \end{funcdesc}
 
 \begin{funcdesc}{get}{mapping, name\optional{, default}}
-  Return the value for \var{name} from \var{mapping}, interpolating
+  Return the value for \var{name} from \var{mapping}, replacing
   values recursively if needed.  If \var{name} cannot be found in
   \var{mapping}, \var{default} is returned without being
-  interpolated.
-  Raises \exception{InterpolationSyntaxError} if there are malformed
-  constructs in \var{s}, or \exception{InterpolationRecursionError} if
+  replaced.
+  Raises \exception{SubstitutionSyntaxError} if there are malformed
+  constructs in \var{s}, or \exception{SubstitutionRecursionError} if
   any name expands to include a reference to itself either directly or
   indirectly.
 \end{funcdesc}
 
 The following exceptions are defined:
 
-\begin{excdesc}{InterpolationError}
-  Base class for errors raised by the \module{ZConfig.Interpolation}
+\begin{excdesc}{SubstitutionError}
+  Base class for errors raised by the \module{ZConfig.Substitution}
   module.  Instances provide the attributes \member{message} and
   \member{context}.  \member{message} contains a description of the
   error.  \member{context} is either \code{None} or a list of names
-  that have been looked up in the case of nested interpolation.
+  that have been looked up in the case of nested substitution.
 \end{excdesc}
 
-\begin{excdesc}{InterpolationSyntaxError}
-  Raised when interpolation source text contains syntactical errors.
+\begin{excdesc}{SubstitutionSyntaxError}
+  Raised when the source text contains syntactical errors.
 \end{excdesc}
 
-\begin{excdesc}{InterpolationRecursionError}
-  Raised when a nested interpolation is recursive.  The
+\begin{excdesc}{SubstitutionRecursionError}
+  Raised when a nested substitution is recursive.  The
   \member{context} attribute will always be a list for this
   exception.  An additional attribute, \member{name}, gives the name
   for which an recursive reference was detected.
@@ -585,18 +619,18 @@
 
 \subsection{Examples}
 
-These examples show how \function{get()} and \function{interpolate()}
+These examples show how \function{get()} and \function{substitute()}
 differ.
 
 \begin{verbatim}
->>> from ZConfig.Interpolation import get, interpolate
+>>> from ZConfig.Substitution import get, substitute
 >>> d = {'name': 'value',
 ...      'top': '$middle',
 ...      'middle' : 'bottom'}
 >>>
->>> interpolate('$name', d)
+>>> substitute('$name', d)
 'value'
->>> interpolate('$top', d)
+>>> substitute('$top', d)
 '$middle'
 >>>
 >>> get(d, 'name')