diff --git a/tconfpy-spec.txt b/tconfpy-spec.txt index 95e9a0e..5af5cff 100644 --- a/tconfpy-spec.txt +++ b/tconfpy-spec.txt @@ -1,61 +1,27 @@ -$Id: tconfpy-spec.txt,v 1.103 2004/03/14 09:16:06 tundra Exp $ +$Id: tconfpy-spec.txt,v 1.104 2004/03/21 12:36:29 tundra Exp $ tconfpy SPECIFICATION ===================== + API === -tconfpy.ParseConfig(FileName, Options, IgnoreCase=False, Debug=False) +tconfpy.ParseConfig(FileName, InitialSymTbl, Debug=False, LiteralVars=False) - ---> [SymTable, ErrorMsgs, WarningMsgs, DebugMsgs] + ---> [SymTable, ErrorMsgs, WarningMsgs, DebugMsgs, LiteralLines] where, -FileName ---> String +FileName ---> String -Options ---> {"BoolOpts" : [bopt, bopt, ...], (Optional, Default={}) - "NumOpts" : [nopt, nopt, ...], - "StrOpts" : [sopt, sopt, ...] - } +InitialSymbolTbl ---> Dictionary in {varname:tconfpy.VarDescriptor, ...} format - - For each of these these types of entries, - 'Configurable' is a boolean which must be True for - the Option to be settable in the Configuration File. - If Configurable == False, then the option is set to - its default value during initial parsing and may not - be changed further in the Configuration File. +Debug ---> Turn on debug output. - Similarly, NumVals sets how many values may - be associated with that option. A value of - 0 means there is no limit. - - bopt = [name, default, Configurable, NumVals=1] - - A bopt can only be True/False - - nopt = [name, default, Configurable, NumVals, [min, max]] - - If min or max are None, then no bound in that - direction is enforced. For no bounds checking, - use [None, None] or []. - - - sopt = [name, default, Configurable, NumVals, [list of legal vals - regex]] - - Each entry in the list of legal vals may be a - literal string or a regular expression. If the - list of legal vals is [], it means there are no - restrictions on what string values may be - associated with a particular sopt. - - -IgnoreCase ---> Case is ignored during parse of config file. (Optional. Default: False) - -Debug ---> Turn on debug output. (Optional. Default: False) +LiteralVars ---> Replace variable references in Literal Lines @@ -63,129 +29,17 @@ ------------- -SymTable ---> {Symbol Name : [Symbol Value, option, option, ...]} +SymTable ---> {Symbol Name : [Symbol Value, option, option, ...]} -ErrorMsgs ---> List of Error Messages +ErrorMsgs ---> List of Error Messages -WarningMsgs ---> List of Warning Messages +WarningMsgs ---> List of Warning Messages -DebugMsgs ---> List of Debug Messages (empty if Debug=False) +DebugMsgs ---> List of Debug Messages (empty if Debug=False) + +LiteralLines ---> Lines processed literally - w/vars replaced if LiteralVars=True ------------------------------------------------------------------------------ -CONFIGURATION LANGUAGE -====================== - -All statements must fit on single line. There is no line -continuation support. Case is significant unless the -IgnoreCase option is invoked when calling the Parsing API. - - -Variable Naming & Dereferencing -------------------------------- - -Variable names may be arbitrary length and contain any printable -character except '$', '=', or '#'. - -Variables must be defined before being referenced. No forward -references are permitted. Variables named in the Options list passed -into the Parsing API are considered predefined and are intitialized to -their default values. Environment Variables are also considered -predefined with values as set in the invoking environment. - -A variable is dereferenced by enclosing it in square brackets: - - -[FOO] - Configuration Variable -[$FOO] - Environment Variable - - -Comment -------- - -'#' introduces comment - text ignored from # to EOL - -Special -------- - -[HASH] - Allows '#' to be inserted in a configuration line -[EQUAL] - Allows '=' to be inserted in a configuration line - - -PreProcessor Directives ------------------------ - - -All conditionals except Existential, are string literal tests (with -possible case ignored). - -CONDSTR = ([var]|string)+ - -.include CONDSTR # Inline include - -.if CONDSTR == CONDSTR # Equality -.if CONDSTR != CONDSTR # Inequality -.if [var]+ # Existential -.ifnot [var]+ -.endif # Conditional block delimiter - - - -Configuration Variables -======================= - -The heart of tconfpy is the association of one or more values with -so-called "Configuration Variables". These variables and their values -are returned in the Symbol Table constructed by the parser. - - -User-Defined Configuration Variables ------------------------------------- - -Users may define their own configuration variables and associate one -or more values with that variable. The general idea is to associate a -symbol name with a list of one or more values. Each value in the list -is delimited with the equal symbol ('='). - -x = y = z ... - -This means, after parsing, the Symbol Table will contain an entry in this form: - -{'x' : ['y', 'z', ...]} - - - -Pre-Defined Option Variables ----------------------------- - -Pre-Defined Option Variables (one of the entries in the Options passed into the -Parsing API) are similar to User-Defined Variables but with more rigid -restrictions: - -- An option has a fixed number of possible values assigned to it. This - is set by the NumVals field in that option in the Options data structure. - - Say, and 'opt1' has NumVals set to 2, then this would not be a legal - config statement: - - opt1 = val1 = val2 = val3 - -- Boolean Options always are limited to a single value (True or False) - (NumVal = 1). The Right-Hand Side of a Boolean option assignment - may be the string "True" or "False" in any case regardless of the - IgnoreCase setting passed to the Parsing API. - -- Numeric and String Options may have as many values associated with - them as their associated NumVals entry permits. Each such value - must conform to either the min/max criteria (for Numerics) or - the literal/regex criteria (for Strings) in their associated - Options entry. - - - - - - -