Fork: 0
tundra / tconfpy
Browse code
Wrote validation sections.
master
1 parent 4483ab5 commit 5d07ad4b230092c7de415c2b370b95776357a177
@tundra tundra authored on 15 Apr 2004
Patch
Unified Split
Showing 1 changed file
View
327
■■■■■
 tconfpy.3
retval = ParseConfig(cfgfile,
InitialSymTable={},
AllowNewVars=True,
AllowNewNamespaces=True,
LiteralVars=False,
LiteralVars=True,
Debug=False
)
 
where:
.TP
.B LiteralVars (Default: False)
 
 
If set to True this option enables variable substitutions within
If set to False 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 any
other language or text.
 
 
 
.SS The \'Debug\' API Option
 
\*(TC has a fairly rich set of debugging features built into its
parser. It can provide some detail about each line parsed as well
.fi
 
 
 
.SS The \'.include\' Directive
 
.SS Conditional Directives
 
.SS \'.literal\. - Using \*(TC As A Preprocessor For Other Languages
 
.SS Type And Value Enforcement
 
.SS Some Notes On Boolean Variables
By default, any variable (or namespace) you create in a configuration file
is understood to just hold a string of characters. There are no limits
to what that string may contain, how long it is, and so on.
 
However, \*(TC gives the programmer considerable power to enforce variable
types and values, if they so choose. (See the section above entitled,
.B PROGRAMMING USING THE \*(TC API
for the details.) The programmer can set all kinds of limitations
about a variable's type, permissible values, and (in the case of
strings) how long or short it may be. The programmer does this by
defining these limitations for each variable of interest
.B prior to calling \*(TC to parse your configuration file.
In that case, when \*(TC actually processes the configuration file,
it "enforces" these restrictions any time you attempt to change the
value of one of these variables. If you try to assign a value that
fails one of these "validation" tests, \*(TC will produce an error
and leave the variable's value unchanged.
 
For instance, suppose the programmer has defined
variable "Foo" to be a floating point number, and that it must have
a value between -10.5 and 100.1. In that case:
 
.nf
Foo = 6.023E23 # Error - Value is out of range
Foo = MyGoodness # Error - Value must be a FP number, not a string
Foo = -2.387 # Good - Value is both FP an in range
.fi
 
 
.SS What Specific Validations Are Available?
 
The programmer has several different restrictions they can place on
a variable's value. You do not need to understand how they work,
merely what they are so that any error messages you see will make sense.
 
.IP \(bu 4
The programmer may declare any variable to be
.B Read Only.
This means you can still use references to that variable to extract
its value, but any attempt to change it value within the configuration
file will fail and produce an error.
 
.IP \(bu 4
The programmer may specify the variable's
.B type
as string (the default), integer, floating point, complex, or boolean.
 
.IP \(bu 4
The programmer may specify
.B the set of all legal values
that can be assigned to a variable. For instance, the programmer
might specify that the floating point variable \'Transcend\' can only
be set to either 3.14 or 2.73. Similarly, the programmer might
specify that the string variable \'Color\' can only ever be set to
\'Red\', \'Green\', or \'Blue\'. In fact, in the case of string
variables, the programmer can actually specify a set of patterns
(regular expressions) the value has to match. For instance, they can
demand that you only set a particular string variable to strings that
begin with \'a'\ and end with \'bob\'.
 
.IP \(bu 4
For integer and floating point variables, the programmer can specify
a legal
.B value range
for the variable. If you change the value of such a variable, that value
must be within the defined range or you'll get an error.
 
.IP \(bu 4
For string variables, the programmer can specify a minimum and maxium
.B length
for the strings you assign to the variable in question.
 
.IP \(bu 4
The programmer can limit you to
.B only being able to use existing variables.
(.i.e. The Predefined variables and any variables the programmer
has defined ahead of time.) In that case, any attempt to create a
new variable in the configuration file will fail and produce an error.
 
.IP \(bu 4
The programmer can limit you to
.B only being able to use namespaces they have defined ahead of time.
In that case, if you attempt to enter a namespace not on the list
the programmer created ahead of time will fail and produce an error.
 
.IP \(bu 4
The programmer can enable or prevent
.B the substitution of variable references in literal blocks
(see below). If they disable this option, something like \'[Foo]\'
is left unchanged within the literal block. i.e., It too, is treated
"literally".
 
 
.SS Notes On Variable Type/Value Enforcement
 
There are a few other things you should know about how \*(TC
enforces restrictions on variables:
 
.IP \(bu 4
Within the configuration file,
.B variable references are always converted to strings
regardless of the actual type of the variable in question. For
instance, suppose the programmer defines variable \'Foo\' to be
floating point. Then:
 
.nf
Foo = 1.23
Bar = Value is [Foo] # Creates a new *string* variable with the
# value: "Value is 1.23"
.fi
 
In other words, variable values are "coerced" into strings for
the purposes of substution and conditional testing within a
configuration file.
 
.IP \(bu 4
You cannot create anything but a string variable with no limitations
from within a configuration file. All validation features
.B require
the limitations to be specified by the calling program ahead of time.
 
.IP \(bu 4
Similarly, you cannot change any of the enforcement options from
within a configuration file. These features are only available
under program control, presumably by the application program that
is calling \*(TC.
 
.IP \(bu 4
There is no way to know what the limitations are on a particular
variable from within the configuration file. Programmers
who use these features should document the variable restrictions
they've employed as a part of the documentation for the application
in question.
 
 
 
.SS Some Further Notes On Boolean Variables
 
One last note here concerns Boolean variables. Booleans are actually
stored in the symbol table as the Python values, True or False.
stored in the symbol table as the Python boolean values,
.B True
or
.B False.
However, \*(TC accepts user statements that set the value of the
boolean in a number of formats:
 
.nf
.B must
observe case and test for either \'True\' or \'False\':
 
.nf
boolvar = YES
 
.if [boolvar] != False # This works fine
 
.if [boolvar] != FALSE # This does not work - Case is not being observed
 
.if [boolvar] != Off # Neither does this - Only True and False can be tested
 
.fi
 
boolvar = No
 
.if [boolvar] == False # This works fine
 
.if [boolvar] == FALSE # This does not work - Case is not being observed
 
.if [boolvar] == Off # Neither does this - Only True and False can be tested
 
.fi
 
 
.SS The \'.include\' Directive
 
.SS Conditional Directives
 
.SS The \'.literal\. Directive
 
.SH ADVANCED TOPICS
 
.SS Guaranteeing A Correct Base Configuration