.ds CP 2003-2004
.ds TC \'tconfpy\'
.TH TCONFPY 3 "TundraWare Inc."

.SH NAME tconfpy.py
 Configuration File Support For Python Applications

.SH SYNOPSIS

It is common to provide an external "configuration file" when writing
sophisticated applications.  This gives the end-user the ability to
easily change program options by editing that file.

\*(TC is a Python module for parsing such configuration files. \*(TC
understands and parses a configuration "language" which has a rich set
of string-substitution, variable name, conditional, and validation
features.

By using \*(TC, you unburden your program from the major responsibility
of configuration file parsing and validation, while providing your
users a rich set of configuration features.


.SH INSTALLATION
There are three ways to install \*(TC depending on your preferences
and type of system.  In each of these installation methods you must be
logged in with root authority on Unix-like systems or as the
Administrator on Win32 systems.


.SS Preparation - Getting And Extracting The Package


For the first two installation methods, you must first download the
latest release from:

.nf
   http://www.tundraware.com/Software/tconfpy/
.fi

Then unpack the contents by issuing the following command:

.nf
   tar -xzvf py-tconfpy-X.XXX.tar.gz   (where X.XXX is the version number)
.fi

Win32 users who do not have tar installed on their system can find
a Windows version of the program at:

.nf
    http://unxutils.sourceforge.net/
.fi


.SS Install Method #1 - All Systems (Semi-Automated)


Enter the directory created in the unpacking step above.  Then issue
the following command:

.nf
    python setup.py install
.fi

This will install the \*(TC module and compile it.

You will manually have to copy the 'test-tc.py' program to a directory
somewhere in your executable path.  Similarly, copy the documentation
files to locations appropriate for your system.


.SS Install Method #2 - All Systems (Manual)


Enter the directory created in the unpacking step above.  Then,
manually copy the tconfpy.py file to a directory somewhere in your
PYTHONPATH.  The recommended location for Unix-like systems is:

.nf
    .../pythonX.Y/site-packages
.fi

For Win32 systems, the recommended location is:

.nf
    ...\\PythonX.Y\\lib\\site-packages
.fi

Where X.Y is the Python release number.


You can pre-compile the \*(TC module by starting Python interactively
and then issuing the command:

.nf
    import tconfpy
.fi

Manually copy the 'test-tc.py' program to a directory
somewhere in your executable path.  Copy the documentation
files to locations appropriate for your system.


.SS Install Method #3 - FreeBSD Only (Fully-Automated)


Make sure you are logged in as root, then:

.nf
      cd /usr/ports/devel/py-tconfpy
      make install
.fi

This is a fully-automated install that puts both code and
documentation where it belongs.  After this command has completed
you'll find the license agreement and all the documentation (in the
various formats) in:

.nf
     /usr/local/share/doc/py-tconfpy
.fi

The 'man' pages will have been properly installed so either of these
commands will work:

.nf
    man tconfpy
    man test-tc
.fi

.SS Bundling \*(TC With Your Own Programs


If you write a program that depends on \*(TC you'll need to ensure
that the end-users have it installed on their systems.  There are two
ways to do this:

1) Tell them to download and install the package as described above.
   This is not recommended since you cannot rely on the technical
   ability of end users to do this correctly.

2) Just include 'tconfpy.py' in your program distribution directory.
   This ensures that the module is available to your program
   regardless of what the end-user system has installed.




.SH PROGRAMMING USING THE \*(TC API

\*(TC is a Python module and thus available for use by any Python
program.  This section discusses how to invoke the \*(TC parser, the
options available when doing so, and what the parser returns to
the calling program.

.SS API Overview

.nf
    
.B ParseConfig(cfgfile, InitialSymTbl={}, Debug=False, LiteralVars=False)

where:

.B cfgfile
    The the name of a file containing configuration information
.B InitialSymTbl
    A pre-populated symbol table.  Defaults to an empty symbol table.  As
    described below, this must contain valid \'VarDescriptor\' entries
    for each symbol in the table.
.B Debug
    Defaults to False.  If set to True, \*(TC will provide detailed
    debugging information about each line processed when it returns.
.B LiteralVars
    Defaults to False.  If set to True this option Enables variable 
    substitutions within \'.literal\' blocks of a configuration file.
    See the section in the language reference below on \'.literal\'
    usage for details.

.SS The \'Debug\' Option

\*(TC has a fairly rich set of debugging features built into its
parser.  It can provide some detail about each line parsed as well
as overall information about the parse.  Be default, debugging is
turned off.  To enable debugging, merely set \'Debug=True' in the
API call:

.nf
retval = ParseConfig("myconfigfile", Debug=True)
.fi

.SS The \'LiteralVars\' Option

\*(TC supports the inclusion of literal text anywhere in a
configuration file via the \'.literal\' directive.  This
directive effectively tells the \*(TC parser to pass
every line it encounters "literally" until it sees a
corresponding \'.endlinteral\' directive.   By default,
\*(TC does
.B exactly
this.  However, \*(TC has very powerful variable substitution
mechanisms.  You may want to embed variable references in a
"literal" block and have them replaced by \*(TC.

Here is an example:

.nf
     MyEmail = me@here.com   # This defines variable MyEmail

    .literal
        printf("[MyEmail]");  /* A C Statement */
    .endliteral
.fi

By default, \'ParseConfig()\' will leave everything within
the \'.literal\'/\'.endliteral\' block unchanged.  In our
example, the string:

.nf
    printf("[MyEmail]");  /* A C Statement */
.fi

would be in the list of literals returned by \'ParseConfig()\'.

However, we can ask \*(TC to do variable replacement
.B within
literal blocks by setting \'LiteralVars=True\' in the
\'ParseConfig()\' call:

.nf
retval = ParseConfig("myconfigfile", LiteralVars=True)
.fi


In this example, \*(TC would return:

.nf
    printf("me@here.com");  /* A C Statement */
.fi

At first glance this seems only mildly useful, but it is
actually very handy.  As described later in this document,
\*(TC has a rich set of conditional operators and string
sustitution facilities.  You can use these features along
with literal block processing and variable substitution
within those blocks.  This effectively lets you use
\*(TC as a preprocessor for
.B any
other language or text.



.SS Passing An Initial Symbol Table



.SS \*(TC Return Values

When \*(TC is finished processing the configuration file it returns an
object which contains the entire results of the parse.  This includes
a symbol table, any relevant error or warning messages, debug information
(if you requested this via the API), and any "literal" lines encountred
in the configuration.

The return object is an instance of the class \'twander.RetObj\' which is
nothing more than a container to hold return data.  In the simplest
case, we can parse and extract results like this:

.nf
from tconfpy import *

retval = ParseConfig("myconfigfile", Debug=True)
.fi

\'retval\' now contains the results of the parse:

.nf
retval.Errors -   A Python list containing error messages.  If this list
                  is empty, you can infer that there were no parsing
                  errors - i.e., The configuration file was OK.

retval.Warnings - A Python list containing warning messages.  These
                  describe minor problems not fatal to the parse
                  process, but that you really ought to clean up in
                  the configuration file.


retval.SymTable - A Python dictionary which lists all the defined
                  symbols and their associated values.  A "value"
                  in this case is always an object of type
                  tconfpy.VarDescriptor (as described above).

retval.Literals - As described below, the \*(TC configuration language
                  supports a \'.literal\' directive.  This directive
                  allows the user to embed literal text anywhere in
                  the configuration file.  This effectively makes
                  \*(TC useful as a preprocessor for any other
                  language or text.  retval.Literals is a Python list
                  containing all literal text discovered during the parse.

retval.Debug -    A Python list containing detailed debug information for
                  each line parsed as well as some brief summary
                  information about the parse.  retval.Debug defaults
                  to an empty list and is only populated if you set
                  \'Debug=True\' in the API call that initiated the
                  parse (as in the example above).
.fi


.SH CONFIGURATION LANGUAGE REFERENCE


\*(TC recognizes a full-featured configuration language that includes
variable creation and value assignment, a full preprocessor with
conditionals, type and value enforcement, and lexical namespaces.
This section of the document describes that language and provides
examples of how each feature can be used.

.SS General Rules For The \*(TC Configuration Language

.SS Variables And Variable References

.SS Predefined Variables

.SS The \'.include\' Directive

.SS Conditional Directives

.SS \'.literal\. - Using \*(TC As A Preprocessor For Other Languages

.SS Type And Value Enforcement

.SS Lexical Namespaces

.SH ADVANCED TOPICS

.SS Guaranteeing A Correct Base Configuration

.SS Enforcing Mandatory Configurations


.SH OTHER

\*(TC requires Python 2.3 or later.

.SH BUGS AND MISFEATURES
None known as of this release.

.SH COPYRIGHT AND LICENSING
\*(TC is Copyright(c) \*(CP TundraWare Inc.  For terms of use, see
the tconfpy-license.txt file in the program distribution.  If you
install \*(TC  on a FreeBSD system using the 'ports' mechanism, you
will also find this file in /usr/local/share/doc/py-tconfpy.

.SH AUTHOR
.nf
Tim Daneliuk
tconfpy@tundraware.com