Fork: 0
tundra / tconfpy
Browse code
Minor edits.
master
1 parent 7ba6de6 commit 9f2cbbfdc1363eba9bd9d243b229bfbab1ddf3bd
@tundra tundra authored on 19 Jan 2005
Patch
Unified Split
Showing 1 changed file
View
80
■■■■■
 tconfpy.3
.TP
.B InitialSymTable (Default: \fCSymbolTable()\fP)
 
Used to pass a pre-initialized Symbol Table from the application to
the parser.
the parser. Defaults to an empty symbol table.
 
.TP
.B AllowNewVars (Default: \fCTrue\fP)
 
.TP
.B VarDescriptor.Default (Default: \fCEmpty String\fP)
 
This is a place to store the default value for a given variable. When
a variable is newly-defined in a configuration file, \fCtconfpy\fP places the
first value assigned to that variable into this attribute. For
variables already in the symbol table, \fCtconfpy\fP does nothing to this
attribute. This attribute is not actually used by \fCtconfpy\fP for anything.
It is provided as a convenience so that the calling program can easily
"reset" every variable to its default value if desired.
 
The one place \fCVarDescriptor.Default\fP is used within the parser is when
using Variable Templates. Suppose a \fCFoo\fP is a templated variable and the
configuration file contains the statement:
 
.ft C \" Courier
.nf
Foo =
.fi
.ft \" revert
 
This will reset the templated variable to its
.B default
value. This is unlike the case of a "normal" variable where such
a statement sets it to a null string - literally the Right Hand Side
contains nothing in this case. The section entitled,
.B Using Variable Templates
discusses the rationale' for these semantics.
a variable is newly-defined in a configuration file, \fCtconfpy\fP
places the first value assigned to that variable into this attribute.
For variables already in the symbol table, \fCtconfpy\fP does nothing
to this attribute. This attribute is not actually used by
\fCtconfpy\fP for anything. It is provided as a convenience so that
the calling program can easily keep track of each variable's default
value. This makes it easy to do things like "reset" every variable
when restarting a program, for example.
 
 
.TP
.B VarDescriptor.LegalVals (Default: \fC[]\fP)
 
.B NOTE:
If you want this test to be skipped, then set \fCLegalVals\fP to an
empty list, []. (This is the default when you first create an
instance of \fCtconfpy.VarDescriptor\fP.) Do not set it to a Python
None or anything else. \fCtconfpy\fP expects this attribute to be a list in
\fCNone\fP or anything else. \fCtconfpy\fP expects this attribute to be a list in
every case.
 
 
 
.fi
.ft \" revert
 
In all cases, if you want either of these tests skipped, set \fCMin\fP
or \fCMax\fP to the Python None.
or \fCMax\fP to the Python \fCNone\fP.
 
.P
All these various validations are logically "ANDed" together.
i.e., A new value for a variable must be allowed
the namespace that was in effect when the parse completed. i.e.,
It will contain the last namespace used.
 
 
.SS How The \fCtconfpy\fP Parser Validates The Initial Symbol Table
 
When you pass an initial symbol table to the parser, \fCtconfpy\fP does some
basic validation that the table contents properly conform to the
\fCVarDescriptor\fP format and generates error messages if it finds
problems. However, the program does
.SS How The \fCtconfpy\fP Parser Validates The Initial Symbol And Template Tables
 
When you pass an initial symbol and/or template table to the parser,
\fCtconfpy\fP does some basic validation that the table contents
properly conform to the \fCVarDescriptor\fP format and generates error
messages if it finds problems. However, the program does
.B not
check your specifications to see if they make sense. For instance
if you define an integer with a minimum value of 100 and a maximum
value of 50, \fCtconfpy\fP cheerfully accepts these limits even though they
to be recorded. Similarly, if you put a value in \fCLegalVals\fP that
is outside the range of \fCMin\fP to \fCMax\fP, \fCtconfpy\fP will accept
it quietly.
 
In the case of templates, \fCtconfpy\fP all makes sure that they are all
named "canonically". That is, a template name may not itself contain
a namespace. This effectively means that there can be no namespace
separator characters (".") in the template name.
 
 
.SS The \fCAllowNewVars\fP API Option
 
By default, \fCtconfpy\fP lets the user define any new variables they
wish in a configuration file, merely by placing a line in the
Variable Templates are supported with two API options:
\fCTemplates\fP And \fCTemplatesOnly\fP. \fCTemplates\fP
is used to pass a symbol table (separate from the main symbol
table) containing the Variable Templates. By default, this
option is set to \fC{}\fP which means no templates are
defined.
option is set to an object of type \fCTemplate\fP containing
no templates.
 
So what exactly is a "Variable Template"? It is the
.B exact same thing
as a predefined variable you might pass in the initial symbol
.fi
.ft \" revert
 
.SH DOCUMENT REVISION INFORMATION
$Id: tconfpy.3,v 1.153 2005/01/19 09:15:10 tundra Exp $
$Id: tconfpy.3,v 1.154 2005/01/19 22:30:55 tundra Exp $