[Zope-Checkins] CVS: Packages/ZConfig/doc - zconfig.tex:1.9

Fred L. Drake, Jr. fdrake@acm.org
Mon, 14 Oct 2002 16:58:58 -0400


Update of /cvs-repository/Packages/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv24808

Modified Files:
	zconfig.tex 
Log Message:
Added a summary of the syntax.  (Based on a text version that's been
passed around and revised for almost a month.)  This is accurate, but
not necessarily complete.


=== Packages/ZConfig/doc/zconfig.tex 1.8 => 1.9 ===
--- Packages/ZConfig/doc/zconfig.tex:1.8	Mon Oct 14 15:33:42 2002
+++ Packages/ZConfig/doc/zconfig.tex	Mon Oct 14 16:58:58 2002
@@ -42,6 +42,140 @@
 
 \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}