.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 .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 PARSING A CONFIGURATION FILE .SS PASSING AN INITIAL SYMBOL TABLE .SS THE \'Debug\' OPTION .SS THE \'LiteralVars\' OPTION .SS WHAT \*(TC RETURNS .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