diff --git a/tconfpy.3 b/tconfpy.3 new file mode 100644 index 0000000..3dabd70 --- /dev/null +++ b/tconfpy.3 @@ -0,0 +1,119 @@ +.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 +