diff --git a/tconfpy.3 b/tconfpy.3 index bc04bcc..862e7c4 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -105,7 +105,10 @@ retval = ParseConfig(cfgfile, InitialSymTable={}, AllowNewVars=True, + Templates={}, + TemplatesOnly={}, LiteralVars=True, + ReturnPredefs=True, Debug=False ) @@ -117,13 +120,11 @@ .TP .B cfgfile (Required Parameter - No Default) - The the name of a file containing configuration information .TP .B InitialSymTable (Default: \fC{}\fP) - A prepopulated symbol table (a Python dictionary). As described below, this must contain valid \fCVarDescriptor\fP entries for each symbol in the table. @@ -131,28 +132,63 @@ .TP .B AllowNewVars (Default: \fCTrue\fP) - Allow the user to create new variables in the configuration file. + +.TP +.B Templates (Default: \fC{}\fP) + +This option is used to pass variable templates to the parser. If present, +\*(TC expects this option to pass a data structure in the same format as +a symbol table. i.e., You must pass a Python dictonary whose keys are the +names of the variable templates and each entry must be a \fCVarDescriptor\fP +object. See the section below entitled, +.B Using Variable Templates +for all the details. By default, no variable templates are passed to +the parser. + + +.TP +.B TemplatesOnly (Default: \fCFalse\fP) + +If this option is set to \fCTrue\fP, \*(TC will not permit a new variable to +be created unless a variable template exists for it. By default, \*(TC will +use a variable template if one is present for a new variable, but it does +not require one. If a new variable is created, and no Template exists for +it, the variable is just created as a string type with no restrictions on +content or length. When this option is set to \fCTrue\fP, then a +template +.B must +exist for each newly created variable. + + .TP .B LiteralVars (Default: \fCFalse\fP) - If set to \fCTrue\fP this option enables variable substitutions within \fC.literal\fP blocks of a configuration file. See the section in the language reference below on \fC.literal\fP usage for details. + +.TP +.B ReturnPredefs (Default: \fCTrue\fP) +\fCtconfpy\fC "prefefines" some variables internally. By default, +these are returned in the symbol table along with the variables +actually defined in the configuration file. If you want a +"pure" symbol table - that is, a table with +.B only +your variables in it - set this option to \fCFalse\fP. + + .TP .B Debug (Default: \fCFalse\fP) - If set to \fCTrue\fP, \*(TC will provide detailed debugging information about each line processed when it returns. .TP .B retval - An object of type \fCtconfpy.RetObj\fP used to return parsing results. @@ -614,6 +650,9 @@ table passed to the parser. +.SS Using Variable Templates - The \fCTemplates\fP And \fCTemplatesOnly\fP API Options + + .SS The \fCLiteralVars\fP API Option \*(TC supports the inclusion of literal text anywhere in a @@ -682,6 +721,26 @@ other language or text. +.SS The \fCReturnPredefs\fP API Option + +As described below, \fCtconfpy\fP internally "predefines" a number of +variables. These include variables that describe the current runtime +environment as well as variables that substitute for language +keywords. + +These predefined variables are just stored in the symbol table like +any other variable. By default, they are returned with all the "real" +variables discovered in the configuration file. If you want +.B only +the variables actually encountered in the configuration file itself, +set \fCReturnPredefs=False\fP in the \fCParseConfig()\fP API call. +This will cause \fCtconfpy\fP to strip out all the predefined +variables before returning the final symbol table. Note that this +option also removes the \fCNAMESPACE\fP variable since it is understood +to also be outside the configuration file (even though you may have +passed an initial version of \fCNAMESPACE\fP to the parser). + + .SS The \fCDebug\fP API Option \*(TC has a fairly rich set of debugging features built into its