Fork: 0
tundra / tconfpy
Browse code
Removed references to AllowNewNamespaces. Clarified discussion of how
validation for NAMESPACE works.
master
1 parent 15ac4c0 commit 0f0e5e2364d05142ca76acd75a127e0f2b6d7fd9
@tundra tundra authored on 16 Apr 2004
Patch
Unified Split
Showing 1 changed file
View
124
■■■■■
 tconfpy.3
 
retval = ParseConfig(cfgfile,
InitialSymTable={},
AllowNewVars=True,
AllowNewNamespaces=True,
LiteralVars=True,
Debug=False
)
 
.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 LiteralVars (Default: False)
 
it as a regex, and checks to see if the value the user wants to set
matches. If you define an illegal regular expression here, \*(TC will
catch it and produce an appropriate error.
 
You may also want to specify a set of legal strings that are
.B exact matches
not open-ended regular expressions. For example, suppose you have
a variable, \'COLOR\' and you only want the user to be able to only set it
to one of, \'Red\', \'White\', or \'Blue\'. In that case, use the Python
regular expression metacharacters that indicate "Start Of String" and
"End Of String" do do this:
 
.nf
des = VarDescriptor()
des.LegalVals = [r'^Red$', r'^White$', r'^Blue$']
...
 
SymTable['COLOR'] = des
.fi
 
 
.TP
.B VarDescriptor.Min and VarDescriptor.Max (Default: None)
 
on. If the initial namespace value you provide is illegal, \*(TC will
produce an error and reset the initial namespace to "".
 
.IP \(bu 4
Each time the user enters a new namespace, it is added to the
\'LegalVals\' attribute of the \'NAMESPACE\' variable descriptor.
This is done to keep a "history" of all namespaces encountered during
parsing.
 
.IP \(bu 4
The semantics of \'LegalVals\' are slightly different than usual
in the case of the \'NAMESPACE\' variable. As described above, the
presence of anything in \'LegalVals\' ordinarily means that the
variable in question is limited to one of those values. However,
in the case of \'NAMESPACE\'
.B this is only true if \'AllowNewNamespaces=False\' is passed to the API.
In other words, if \'AllowNewNamespaces=True\' (default), the user can
create new namespaces of their own choosing - i.e., They can create
namespaces not yet in \'LegalVals\'. In this case, \'LegalVals\'
is just a list of all the namespaces they created.
 
.IP \(bu 4
If you are inhibiting the creation of new namespaces (via the
\'AllowNewNamespaces = False\' option described below) you can
enumerate the namespaces the user
.B is
allowed to use by pre-defining them. You do this by adding each
permitted namespace to the \'LegalVals\' attribute of the
\'NAMESPACE\' variable descriptor in the initial symbol table.
Because lexical namespaces are implemented by treating \'NAMESPACE\'
as just another variable, all the type and value validations available
for string variables can be applied to \'NAMESPACE\'. As discussed above,
this means you can limit the length and content of what the user assigns
to \'NAMESPACE\'. In effect, this means you can limit the number and
name of namespaces available for use by the user. There is one slight
difference here than for other variables.
.B The root namespace is always legal,
regardless of what other limitations you may impose via
the \'LegalVals\', \'Min\', and \'Max\' attributes of the \'NAMESPACE\'
variable descriptor.
 
.IP \(bu 4
When the call to \'ParseConfig()\' completes, the \'Value\'
attribute of the \'NAMESPACE\' variable descriptor will contain
the namespace that was in effect when the parse completed. i.e.,
It will contain the last namespace used.
 
.IP \(bu 4
Similarly, on parser completion, the \'LegalVals\' attribute of the
\'NAMESPACE\' variable descriptor will contain the name of all the
namespaces encountered during parsing. This is
.B not
true if you suppressed new namespace creation with the
\'AllowNewNamespaces = False\' API option. In that case, the
\'LegalVals\' attribute will contain only those namespaces you
pre-defined. Any or all of these may- or may not have been used in the
configuration file, there is no way to tell.
 
 
.SS How The \*(TC Parser Validates The Initial Symbol Table
 
and \'realvar\' are pre-defined in the initial symbol
table passed to the parser.
 
 
.SS The \'AllowNewNamespaces\' API Option
 
By default, \*(TC supports the use of an arbitrary number of
lexical namespaces. They can be pre-defined in an initial
symbol table passed to the parser and/or created in the configuration
file as desired. (The details are described in a later section
of this document.)
 
There may be times, however, when you do not want users creating new
namespaces on their own. The reasons are much the same as for
preventing the creation of new variables in the option above:
Maintaining simplicity and clarity in the configuration file and
preventing "silent" errors due to misspellings.
 
In this case, call the API with \'AllowNewNamespaces=False\' and the
creation of new namespaces in the configuration file will be disabled.
Any attempt to create a new namespaces via either the
\'[new-ns-name]\' or \'NAMESPACE=new-ns-name\' methods will cause a
parse error to be generated.
 
It is important to realize that this option only disables the
creation of
.B new
namespaces. As discussed in the previous section on namespace
processing, it is possible to pass an initial symbol table to the
parser which has one or more pre-defined namespaces in it. Each of
these pre-defined namespaces is available for use throughout the
configuration file even if \'AllowNewNamespaces\' is set to False.
 
 
.SS The \'LiteralVars\' API Option
 
\*(TC supports the inclusion of literal text anywhere in a
configuration file via the \'.literal\' directive. This
 
.IP \(bu 4
It helps enforce correct configuration files. By default, you can
introduce new namespaces into the configuration file any time you
like. However, as described in the previous section on the
\*(TC API, the application programmer can limit you to a pre-defined
set of legal namespaces (via the \'AllowNewNamespaces=False\' API
option). By doing this, the programmer is helping you avoid
incorrect configuration file entries by limiting just which
like. However, as described in the previous section on the \*(TC API,
the application programmer can limit you to a pre-defined set of legal
namespaces (via the \'LegalVals\' attribute of the \'NAMESPACE\'
variable descriptor). By doing this, the programmer is helping you
avoid incorrect configuration file entries by limiting just which
namespaces you can enter to reference or create variables.
 
 
.SS Rules For Using Lexical Namespace