Commit bf718289 authored by Fred Drake's avatar Fred Drake

add a convenient mapping section type with documentation

parent fbe71932
...@@ -872,6 +872,113 @@ The following data types are provided by the default type registry. ...@@ -872,6 +872,113 @@ The following data types are provided by the default type registry.
\end{definitions} \end{definitions}
\section{Standard \module{ZConfig} Schema Components
\label{standard-components}}
\module{ZConfig} provides a few convenient schema components as part
of the package. These may be used directly or can server as examples
for creating new components.
\subsection{\module{ZConfig.components.basic}}
The \module{ZConfig.components.basic} package provides small
components that can be helpful in composing application-specific
components and schema. There is no large functionality represented by
this package. The default component provided by this package simply
imports all of the smaller components. This can be imported using
\begin{verbatim}
<import package="ZConfig.components.basic"/>
\end{verbatim}
Each of the smaller components is documented directly; importing these
selectively can reduce the time it takes to load a schema slightly,
and allows replacing the other basic components with alternate
components (by using different imports that define the same type
names) if desired.
\subsubsection{The Mapping Section Type \label{basic-mapping}}
There is a basic section type that behaves like a simple Python
mapping; this can be imported directly using
\begin{verbatim}
<import package="ZConfig.components.basic" file="mapping.xml"/>
\end{verbatim}
This defines a single section type, \datatype{ZConfig.basic.mapping}.
When this is used, the section value is a Python dictionary mapping
keys to string values.
This type is intended to be used by extending it in simple ways. The
simplest is to create a new section type name that makes more sense
for the application:
\begin{verbatim}
<import package="ZConfig.components.basic" file="mapping.xml"/>
<sectiontype name="my-mapping"
extends="ZConfig.basic.mapping"
/>
<section name="*"
type="my-mapping"
attribute="map"
/>
\end{verbatim}
This allows a configuration to contain a mapping from
\datatype{basic-key} names to string values like this:
\begin{verbatim}
<my-mapping>
This that
and the other
</my-mapping>
\end{verbatim}
The value of the configuration object's \member{map} attribute would
then be the dictionary
\begin{verbatim}
{'this': 'that',
'and': 'the other',
}
\end{verbatim}
(Recall that the \datatype{basic-key} data type converts everything to
lower case.)
Perhaps a more interesting application of
\datatype{ZConfig.basic.mapping} is using the derived type to override
the \attribute{keytype}. If we have the conversion function:
\begin{verbatim}
def email_address(value):
userid, hostname = value.split("@", 1)
hostname = hostname.lower() # normalize what we know we can
return "%s@%s" % (userid, hostname)
\end{verbatim}
then we can use this as the key type for a derived mapping type:
\begin{verbatim}
<import package="ZConfig.components.basic" file="mapping.xml"/>
<sectiontype name="email-users"
extends="ZConfig.basic.mapping"
keytype="mypkg.datatypes.email_address"
/>
<section name="*"
type="email-users"
attribute="email_users"
/>
\end{verbatim}
\section{\module{ZConfig} --- Basic configuration support} \section{\module{ZConfig} --- Basic configuration support}
\declaremodule{}{ZConfig} \declaremodule{}{ZConfig}
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment