diff --git a/tconfpy.3 b/tconfpy.3 index 0cb066f..b9647c4 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -90,7 +90,6 @@ retval = ParseConfig(cfgfile, InitialSymTable={}, AllowNewVars=True, - AllowNewNamespaces=True, LiteralVars=True, Debug=False ) @@ -120,12 +119,6 @@ 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) @@ -387,6 +380,22 @@ 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) @@ -453,31 +462,17 @@ 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\' @@ -485,17 +480,6 @@ 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 @@ -580,36 +564,6 @@ 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 @@ -1151,11 +1105,11 @@ .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.