diff --git a/tconfpy.3 b/tconfpy.3 index 57c0468..8107396 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -188,7 +188,7 @@ .ft C \" Courier .nf .if [APPVERSION] == 1.0 - # Set configuration for older application releases + # Set configuration for original application version .else # Set configuration for newer releases .endif @@ -363,7 +363,7 @@ This is a place to store the default value for a given variable. When a variable is newly-defined in a configuration file, \*(TC places the first value assigned to that variable into this attribute. For -variables already in the symbol table, \*TC does nothing to this +variables already in the symbol table, \*(TC does nothing to this attribute. This attribute is not actually used by \*(TC for anything. It is provided as a convenience so that the calling program can easily "reset" every variable to its default value if desired. @@ -534,7 +534,7 @@ .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, \*(TC cheerfully accepts these limits even they they +value of 50, \*(TC cheerfully accepts these limits even though they are impossible. You'll just be unable to do anything with that variable - any attempt to change its value will cause an error to be recorded. Similarly, if you put a value in \fCLegalVals\fP that @@ -712,8 +712,8 @@ .SS \*(TC Return Values -When \*(TC is finished processing the configuration file it returns an -object which contains the entire results of the parse. This includes +When \*(TC is finished processing the configuration file, it returns an +object that contains the entire results of the parse. This includes a symbol table, any relevant error or warning messages, debug information (if you requested this via the API), and any "literal" lines encountred in the configuration. @@ -760,7 +760,8 @@ literal text anywhere in the configuration file. This effectively makes \*(TC useful as a preprocessor for any other language or text. retval.Literals is a Python list containing all literal text -discovered during the parse. +discovered during the parse. The lines appear there in the order +they were discovered in the configuration file. .TP .B retval.Debug @@ -944,7 +945,8 @@ .SS Getting And Using The Value Of A Variable You can get the value of any currently defined variable by -"referencing" it like this: +.B referencing +it like this: .ft C \" Courier .nf @@ -1007,6 +1009,13 @@ .B strings regardless of the actual type of the variables involved. +.IP \(bu 4 +Variables must be +.B defined +before they can be +.B referenced. +\*(TC does not support so-called "forward" references. + .IP \(bu 4 Unless a variable as been marked as "Read Only" by the application @@ -1155,8 +1164,8 @@ .SS Introducing Lexical Namespaces So far,the discussion of variables and references has conveniently -ignored the presence of another related \*(TC feature, "lexical -namespaces." Namespaces are a way to automatically group +ignored the presence of another related \*(TC feature, "Lexical +Namespaces." Namespaces are a way to automatically group related variables together. Suppose you wanted to describe the options on your car in a configuration file. You might do this: @@ -1196,7 +1205,7 @@ variable assigned or referenced. It does this automatically and invisibly, so \fCBrand\fP is turned into \fCMyCar.Brand\fP and so on. You can actually check this by loading the example above into a test -configuration file and running the \fCtest-tc\fP program on it. You will +configuration file and running the \fCtest-tc.py\fP program on it. You will see the "fully qualified" variable names that actually were loaded into the symbol table, each beginning with \fCMyCar.\fP and ending with the variable name you specified. @@ -1257,7 +1266,7 @@ why our early examples in the previous section worked. When we assigned a value to a variable and then referenced that variable value, we did so while in the so-called "root" namespace, "". When -the namespace is "", nothing is done to the variable names +the namespace is "", nothing is done to the variable names. Bear in mind that the programmer can change this default namespace to something other than "" before the configuration file is ever @@ -1269,9 +1278,10 @@ .ft C \" Courier .nf - [NewNameSpace] # Must appear on a line by itself or with a comment only + [NewNameSpace] # May optionally have a comment + OR - NAMESPACE = NewNamespace + NAMESPACE = NewNamespace # May optionally have a comment .fi .ft \" revert @@ -1342,7 +1352,7 @@ [MyNameSpace] foo = 123 # Creates a variable called MyNameSpace.foo - x = bar # Means: MyNameSpace.x = MyNameSpace.bar + x = [bar] # Means: MyNameSpace.x = [MyNameSpace.bar] .fi .ft \" revert @@ -1387,13 +1397,6 @@ .ft \" revert .IP \(bu 4 -\*(TC keeps track of every new namespace you create and returns that -list to the calling program to use as it wishes. (See the section -above entitled, -.B The Initial Symbol Table And Lexical Namespaces -for details.) - -.IP \(bu 4 Lexical namspaces are implemented by having \fCNAMESPACE\fP just be nothing more than (yet) another variable in the symbol table. \*(TC just understands that variable to be special - it treats it as the @@ -1468,9 +1471,9 @@ .OSRELEASE - The version of the operating system in use. - .OSTYPE - Generic type of operating system in use. + .OSTYPE - Generic type of the operating system in use. - .PLATFORM - The generic type of the operating system in use. + .PLATFORM - Generic name of the operating system in use. .PYTHONVERSION - The version of Python in use. .fi @@ -1620,7 +1623,7 @@ that can be assigned to a variable. For instance, the programmer might specify that the floating point variable \fCTranscend\fP can only be set to either 3.14 or 2.73. Similarly, the programmer might -specify that the string variable \fCColor\fP can only ever be set to +specify that the string variable \fCCOLOR\fP can only ever be set to \fCRed\fP, \fCGreen\fP, or \fCBlue\fP. 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 @@ -1669,8 +1672,7 @@ For purposes of processing the configuration file, .B variable references are always converted to strings regardless of the actual type of the variable in question. (Variables are -.B stored in the symbol table -in their actual type.) +stored in the symbol table in their actual type.) For instance, suppose the programmer defines variable \fCFoo\fP to be floating point. Then: @@ -1827,9 +1829,8 @@ .fi .ft \" revert -This makes maintenance of complex configuration files -.B much -simpler. There is only one master copy of the configuration that needs to be +This makes maintenance of complex configuration files much simpler. +There is only one master copy of the configuration that needs to be edited when system-wide changes are required. .P @@ -1846,11 +1847,12 @@ condition and .B include or exclude configuration information based on the outcome of the test. -What's the point? You can build large, complex configurations that test things -like environment variables, one of the Predefined Variables, or even a variable -you've set previously in the configuration file. The resulting configuration is then -produced in a way that is appropriate for -.B that particular system, on that particular day, for that particular user, ... +What's the point? You can build large, complex configurations that +test things like environment variables, one of the Predefined +Variables, or even a variable you've set previously in the +configuration file. In other words, resulting configuration is then +produced in a way that is appropriate for that particular system, on +that particular day, for that particular user, ... By using conditional directives, you can create a single configuration file that works for every user regardless of operating system, location, and so on. @@ -2009,7 +2011,7 @@ .ft C \" Courier .nf - F00 = 1 + FOO = 1 BAR = 2 z = 0 @@ -2044,7 +2046,7 @@ .fi .ft \" revert -You can also use variable references here to get the name of a varible +Finally, you can use variable references here to get the name of a varible to test by "indirection" (as we saw in the previous section on accessing/setting variables indirectly0. This is not a recommended way of doing things because it can be kind of obscure to understand, @@ -2156,7 +2158,8 @@ This tells \*(TC to ignore everything between \fC.literal\fP and \fC.endliteral\fP and just pass it back to the calling program (in \fCretval.Literals\fP - see -previous section on the \*(TC API). +previous section on the \*(TC API). Literal text is returned in the order +it is found in the configuration file. What good is this? It is a nifty way to embedd plain text or even programs written in other languages within a configuration file and @@ -2244,7 +2247,7 @@ statement will be ignored. -.SH GOTCHAS +.SS GOTCHAS \*(TC is a "little language". It is purpose-built to do one and only one thing well: process configuration options. Even @@ -2291,10 +2294,10 @@ .B value of the variable \fCfoo\fP with the string \fCbar\fP. -By the way, this was done for a very good reason. By requiring the user -explicitly note whether they want the name or value of a variable (instead of -inferring it from context), you can mix both literal text and variable values -on either side of a comparison or assignment: +This was done for a very good reason. By requiring the user +explicitly note whether they want the name or value of a variable +(instead of inferring it from context), you can mix both literal text +and variable values on either side of a comparison or assignment: .ft C \" Courier .nf @@ -2422,7 +2425,7 @@ options to \fCFalse\fP. Now call the parser. This general approach allows you to write programs that support a -wide range of options which are enablde/disabled on a per-user, +wide range of options which are enabled/disabled on a per-user, per-machine, per-domain, per-ip, per-company... basis. .SS Iterative Parsing @@ -2444,7 +2447,7 @@ # Program calls the parser with PASS set to 1 - .if PASS == 1 + .if [PASS] == 1 # Do 1st Pass Stuff .endif @@ -2453,7 +2456,7 @@ # Program examines the results of the first pass, does # what is has to, and sets PASS to 2 - .if PASS == 2 + .if [PASS] == 2 # Do 2nd Pass Stuff .endif