Fork: 0
tundra / tconfpy
Browse code
Reformatting and cleanup.
master
1 parent eb48343 commit 29309b66d0b93097c5ea6d051d14395ded3b81e4
@tundra tundra authored on 7 Apr 2004
Patch
Unified Split
Showing 1 changed file
View
174
■■■■■
 tconfpy.3
 
you will have to prepend all references to a \*(TC object with
\'tconfpy.\'. So \'retval=ParseConfig(...\' becomes
\'retval = tconfpy.ParseConfig(...\' and so on.
 
You will also find the test driver code provided in the \*(TC package
helpful as you read through the following sections. \'test-tc.py\' is
a utility to help you learn and exercise the \*(TC API. Perusing the
code therein is helpful as an example of the topics discussed below.
 
 
.SS API Overview
The \*(TC API consists of a single call. Only the configuration file
to be processed is a required parameter, all the others are optional
)
 
where:
 
.B cfgfile
The the name of a file containing configuration information
 
.B InitialSymTbl
A pre-populated symbol table (a Python dictionary). Defaults to
an empty symbol table. As described below, this must contain
valid \'VarDescriptor\' entries for each symbol in the table.
 
.B AllowNewVars
Allow the user to create new variables in the configuration
file. Defaults to True.
 
.B AllowNewNamespaces
Allow new namespaces to be created in the configuration file.
Defaults to True.
 
.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.
 
.fi
 
.TP
.B cfgfile (Required Parameter - No Default)
 
 
The the name of a file containing configuration information
 
.TP
.B InitialSymTbl (Default: {})
 
 
A pre-populated symbol table (a Python dictionary). As described
below, this must contain valid \'VarDescriptor\' entries for each
symbol in the table.
 
.TP
.B AllowNewVars (Default: True)
 
 
Allow the user to create new variables in the configuration file.
 
.TP
.B AllowNewNamespaces (Default: True)
 
 
Allow new namespaces to be created in the configuration file.
 
.TP
.B Debug (Default: False)
 
 
If set to True, \*(TC will provide detailed debugging information
about each line processed when it returns.
 
.TP
.B LiteralVars (Default: 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.
 
.TP
.B retval
An object of type \'tconfpy.RetObj\' used to return parsing
results.
 
 
An object of type \'tconfpy.RetObj\' used to return parsing results.
 
 
.SS Reasons For Passing An Initial Symbol Table
 
 
When \*(TC encounters a new variable in a configuration file, it just
instantiates one of these descriptor objects with these defaults for
that variable. That is, variables newly-defined in a configuration
file are entered into the symbol table as string types with no
restriction on content or length.
file are entered into the symbol table as string types, with an
initial value of "" and with no restriction on content or length.
 
But, when you create variables under program control to "prime" an
initial symbol table, you can modify the content of any of these
attributes for each variable. These descriptor attributes are what
 
.TP
.B VarDescriptor.Value (Default: Empty String)
 
Hold the current value for the variable.
Holds the current value for the variable.
 
.TP
.B VarDescriptor.Writeable (Default: True)
 
Sets whether or not the user can change the variable's value. Setting
this attribute to False makes the variable "Read Only".
this attribute to False makes the variable
.B Read Only.
 
.TP
.B VarDescriptor.Type (Default: TYPE_STRING)
 
As a general matter, for existing variables, \*(TC attempts to coerce
the right-hand-side of an assignment to the type declared for that
variable. The least fussy operation here is when the variable is
defined as TYPE_STRING because pretty much everything can be coerced
into a string. For example, here is how \'foo = 3+8j\' is treated:
 
 
If VarDescriptor.Type = TYPE_COMPLEX then Var.Descriptor.Value will
hold the
.B complex number
3+8j.
 
If VarDescriptor.Type = TYPE_STRING then Var.Descriptor.Value will
hold the
.B string
"3+8j".
into a string. For example, here is how \'foo = 3+8j\' is treated for
different type declarations:
 
 
.nf
 
VarDescriptor.Type VarDescriptor.Value
------------------ -------------------
 
TYPE_BOOL Type Error
TYPE_COMPLEX 3+8j (A complex number)
TYPE_FLOAT Type Error
TYPE_INT Type Error
TYPE_STRING \'3+8j\' (A string)
.fi
 
This is why the default type for newly-defined variables in
the configuration file is TYPE_STRING: they can accept
pretty much
.B any
value.
 
.TP
.B VarDescriptor.Default (Default: Empty String)
 
All these various validations are logically "ANDed" together.
i.e., A new value for a variable must be allowed
AND of the appropriate type AND one of the legal values AND
within the min/max range.
 
\*(TC makes no attempt to harmonize these validation
conditions with each other. If you specify a value in
\'LegalVals\' that is, say, lower than allowed by
\'Min\' you will always get an error when the user sets
the variable to that value: It passed the \'LegalVals\'
validation but failed it for \'Min\'.
 
One last note here concerns Boolean variables. Booleans
are actually stored in the symbol table as True or False.
However, \*(TC accepts user statements in a number of
the desired variable name will be flagged as an error.
 
.fi
 
Note, however, that there is one big drawback to disabling
new variable creation. \*(TC processes the configuration
file on a line-by-line basis. No line "continuation" is
supported. For really long variable names and ease of
maintenance, it is sometimes helpful to create "intermediate"
variables what hold temporary values used to construct
a variable actually needed by the calling program. For example:
Note, however, that there is one big drawback to disabling new
variable creation. \*(TC processes the configuration file on a
line-by-line basis. No line "continuation" is supported. For really
long variable values and ease of maintenance, it is sometimes helpful
to create "intermediate" variables what hold temporary values used to
construct a variable actually needed by the calling program. For
example:
 
.nf
 
inter1 = Really, really, really, really, long argument #1
.SS Iterative Parsing
 
 
.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.