Fork: 0
tundra / tconfpy
Browse code
Added sections on Debug and LiteralVars options.
master
1 parent 1bd5bb5 commit 02028a75a707388b985cdffb046a63622c8ba3d6
@tundra tundra authored on 6 Apr 2004
Patch
Unified Split
Showing 1 changed file
View
199
■■■■■
 tconfpy.3
substitutions within \'.literal\' blocks of a configuration file.
See the section in the language reference below on \'.literal\'
usage for details.
 
 
.SS Parsing A Configuration File
.SS The \'Debug\' 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
as overall information about the parse. Be default, debugging is
turned off. To enable debugging, merely set \'Debug=True' in the
API call:
 
.nf
retval = ParseConfig("myconfigfile", Debug=True)
.fi
 
.SS The \'LiteralVars\' Option
 
\*(TC supports the inclusion of literal text anywhere in a
configuration file via the \'.literal\' directive. This
directive effectively tells the \*(TC parser to pass
every line it encounters "literally" until it sees a
corresponding \'.endlinteral\' directive. By default,
\*(TC does
.B exactly
this. However, \*(TC has very powerful variable substitution
mechanisms. You may want to embed variable references in a
"literal" block and have them replaced by \*(TC.
 
Here is an example:
 
.nf
MyEmail = me@here.com # This defines variable MyEmail
 
.literal
printf("[MyEmail]"); /* A C Statement */
.endliteral
.fi
 
By default, \'ParseConfig()\' will leave everything within
the \'.literal\'/\'.endliteral\' block unchanged. In our
example, the string:
 
.nf
printf("[MyEmail]"); /* A C Statement */
.fi
 
would be in the list of literals returned by \'ParseConfig()\'.
 
However, we can ask \*(TC to do variable replacement
.B within
literal blocks by setting \'LiteralVars=True\' in the
\'ParseConfig()\' call:
 
.nf
retval = ParseConfig("myconfigfile", LiteralVars=True)
.fi
 
 
In this example, \*(TC would return:
 
.nf
printf("me@here.com"); /* A C Statement */
.fi
 
At first glance this seems only mildly useful, but it is
actually very handy. As described later in this document,
\*(TC has a rich set of conditional operators and string
sustitution facilities. You can use these features along
with literal block processing and variable substitution
within those blocks. This effectively lets you use
\*(TC as a preprocessor for
.B any
other language or text.
 
 
 
.SS Passing An Initial Symbol Table
 
.SS The \'Debug\' Option
 
.SS The \'LiteralVars\' Option
 
 
.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
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.
 
The return object is an instance of the class \'twander.RetObj\' which is
nothing more than a container to hold return data. In the simplest
case, we can parse and extract results like this:
 
.nf
from tconfpy import *
 
retval = ParseConfig("myconfigfile", Debug=True)
.fi
 
\'retval\' now contains the results of the parse:
 
.nf
retval.Errors - A Python list containing error messages. If this list
is empty, you can infer that there were no parsing
errors - i.e., The configuration file was OK.
 
retval.Warnings - A Python list containing warning messages. These
describe minor problems not fatal to the parse
process, but that you really ought to clean up in
the configuration file.
 
 
retval.SymTable - A Python dictionary which lists all the defined
symbols and their associated values. A "value"
in this case is always an object of type
tconfpy.VarDescriptor (as described above).
 
retval.Literals - As described below, the \*(TC configuration language
supports a \'.literal\' directive. This directive
allows the user to embed 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.
 
retval.Debug - A Python list containing detailed debug information for
each line parsed as well as some brief summary
information about the parse. retval.Debug defaults
to an empty list and is only populated if you set
\'Debug=True\' in the API call that initiated the
parse (as in the example above).
.fi
 
 
.SH CONFIGURATION LANGUAGE REFERENCE