Fork: 0
tundra / tconfpy
Browse code
Further commentary on variable type as stored vs. as used within parsing.
master
1 parent 6323a05 commit aa70ad84de64c8c6fe296c2333359b366e557704
@tundra tundra authored on 19 Jan 2005
Patch
Unified Split
Showing 1 changed file
View
127
■■■■■
 tconfpy.3
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.
 
\fCtconfpy\fP is a Python module for parsing such configuration files. \fCtconfpy\fP
understands and parses a configuration "language" which has a rich set
of string-substitution, variable name, conditional, and validation
features.
 
By using \fCtconfpy\fP, you relieve your program of the major responsibility
of configuration file parsing and validation, while providing your
users a rich set of configuration features.
\fCtconfpy\fP is a Python module for parsing such configuration
files. \fCtconfpy\fP understands and parses a configuration "language"
which has a rich set of string-substitution, variable name,
conditional, and validation features.
 
By using \fCtconfpy\fP, you relieve your program of the major
responsibility of configuration file parsing and validation, while
providing your users a rich set of configuration features.
 
.B NOTE:
Throughout this document we use the term "configuration file". However,
\fCtconfpy\fP can parse configurations both in files as well as in-memory
lists. Whenever you see the term "file", think "a file or a set of
configuration statements stored in a list".
 
If you run \fCtconfpy\fP directly, it will dump version and copyright
information, as well as the value of the current predefined
System Variables:
 
 
.SS Core Objects
 
In order to use \fCtconfpy\fP effectively, you need to be familiar with the
objects used to communicate between your program and the parser.
This section provides a brief overview of these objects for
In order to use \fCtconfpy\fP effectively, you need to be familiar
with the objects used to communicate between your program and the
parser. This section provides a brief overview of these objects for
reference use later in the document.
 
.TP
.B The Symbol Table Object
LiteralVars=True,
ReturnPredefs=True,
Debug=False
)
 
.fi
.ft \" revert
 
where:
or list here, \fCtconfpy\fP will produce an error.
 
 
.TP
.B CallingProgram (\'tconfpy\' + Version Number)
.B CallingProgram (Default: \fC\fCtconfpy\fP + Version Number\fP)
 
Change the prompt introducer string used for Debug, Error, and Warning
messages.
 
By default, each time \fCtconfpy\fP produces an Error, Warning, or Debug
message, it prepends it with the string \'tconfpy\' followed by the
message, it prepends it with the string \fCtconfpy\fP followed by the
version number. Since \fCtconfpy\fP is designed to be called from
applications programs, you may wish to substitute your own program
name or other information in these messages. You do so by setting the
\fCCallingProgram\fP keyword to the desired text.
 
.TP
.B Templates (Default: \fCTemplate()\fP)
 
This option is used to pass variable templates to the parser. If present,
\fCtconfpy\fP expects this option to pass a data structure in the same format as
a symbol table. i.e., You must pass a Python dictonary whose keys are the
names of the variable templates and each entry must be a \fCVarDescriptor\fP
object. See the section below entitled,
This option is used to pass variable templates to the parser. If
present, \fCtconfpy\fP expects this option to pass an object of type
\fCTemplate\fP. See the section below entitled,
.B Using Variable Templates
for all the details. By default, no variable templates are passed to
the parser.
for all the details. By default, an empty template table (no templates)
is passed to the parser.
 
 
.TP
.B TemplatesOnly (Default: \fCFalse\fP)
version, so it sets the variable \fCAPPVERSION\fP in a symbol table
which is passed to \fCParseConfig()\fP.
 
.IP \(bu 4
You may wish to "protect" certain variable names be creating
them ahead of time and marking them as "Read Only". This is
useful when you want a variable to be available for use
within a configuration file, but you do not want users to
be able to change its value. In this case, the variable can
be referenced in a string substitution or conditional test,
but cannot be changed.
You may wish to "protect" certain variable names be creating them
ahead of time and marking them as "Read Only"
(\fCVarDescriptor.Writeable=False \fP). This is useful when you want
a variable to be available for use within a configuration file, but
you do not want users to be able to change its value. In this case,
the variable can be referenced in a string substitution or conditional
test, but cannot be changed.
 
.IP \(bu 4
You may want to place limits on what values can be assigned to a
particular variable. When a variable is newly defined in a a
.B VarDescriptor.Value (Default: \fCEmpty String\fP)
 
Holds the current value for the variable.
 
 
.TP
.B VarDescriptor.Writeable (Default: \fCTrue\fP)
 
Sets whether or not the user can change the variable's value. Setting
the configuration file is TYPE_STRING: they can accept
pretty much
.B any
value.
 
.B NOTE:
\fCtconfpy\fP always stores a variable's value in it native type in
the symbol table entry for that variable - i.e., You'll get the
variable's value back from the parser in the proper type. However,
when the variable is actually referenced within a configuration file,
it is converted to a
.B string
for purposes of configuration processing.
 
For instance, when doing conditional comparisons, the parser coerces
the variable's value into a string for purposes of the comparsion.
Say you have the floating point variable \fCmyfloat\fP whose value is
\fC6.023\fP and the configuration file contains a statement like:
 
.ft C \" Courier
.nf
.if myfloat == 6.023
.fi
.ft \" revert
 
When doing this conditional check, the parser will convert the current
value of \fCmyfloat\fP into a string and compare it to the
.B string
\fC"6.023"\fP on the Right Hand Side.
 
This can be tricky when dealing with Boolean variables. As described
later in this document, you can do conditional tests based on the
.B state
of a Boolean, but if you do this:
 
.ft C \" Courier
.nf
.if myboolean == whatever...
.fi
.ft \" revert
 
The parser converts \fCmyboolean\fP to a
.B string
of either \fC"True"\fP or \fC"False"\fP, so watch out for this. As a
general matter, you're more likely to need the boolean tests that
check the state of the variable, but the above construct is handy if
you want to use regular string variables to control conditional
bodies:
 
.ft C \" Courier
.nf
MYCONTROL = True
.if myboolean == MYCONTROL
.fi
.ft \" revert
 
Where, \fCMYCONTROL\fP is a regular old string variable - i.e., It has not
been defined to be a boolean by either a Template or Initial Symbol table
passed to the parser.
 
.TP
.B VarDescriptor.Default (Default: \fCEmpty String\fP)
 
.fi
.ft \" revert
 
.SH DOCUMENT REVISION INFORMATION
$Id: tconfpy.3,v 1.151 2005/01/18 08:45:17 tundra Exp $
$Id: tconfpy.3,v 1.152 2005/01/19 08:31:33 tundra Exp $