diff --git a/tconfpy.3 b/tconfpy.3 index 2bd8437..0cb066f 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -91,7 +91,7 @@ InitialSymTable={}, AllowNewVars=True, AllowNewNamespaces=True, - LiteralVars=False, + LiteralVars=True, Debug=False ) @@ -129,7 +129,7 @@ .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. @@ -670,7 +670,6 @@ other language or text. - .SS The \'Debug\' API Option \*(TC has a fairly rich set of debugging features built into its @@ -1442,18 +1441,152 @@ -.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: @@ -1479,17 +1612,23 @@ observe case and test for either \'True\' or \'False\': .nf - boolvar = YES + boolvar = No - .if [boolvar] != False # This works fine + .if [boolvar] == False # This works fine - .if [boolvar] != FALSE # This does not work - Case is not being observed + .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 + .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