$Id: tconfpy-spec.txt,v 1.102 2004/03/09 23:50:16 tundra Exp $

                        tconfpy SPECIFICATION
                        =====================


API
===

tconfpy.ParseConfig(FileName, Options, IgnoreCase=False, Debug=False)

                 ---> [SymTable, ErrorrMsgs, WarningMsgs, DebugMsgs, ParseOK]


where,

FileName   --->  String

Options    --->  {"BoolOpts" : [bopt, bopt, ...],    (Optional, Default={})
                 "NumOpts"  : [nopt, nopt, ...],
                 "StrOpts"  : [sopt, sopt, ...]
                 }

 
                 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.

                 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)



RETURN VALUES
-------------


SymTable    --->  {Symbol Name : [Symbol Value, option, option, ...]}

ErrorMsgs   --->  List of Error Messages

DebugMsgs   ---> List of Debug Messages (empty if Debug=False)

WarningMsgs ---> List of Warning Messages

ParseOK     --->  If True, parsing was successful.


------------------------------------------------------------------------------


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).

.include REF | Filename     # Inline include

.if REF == REF | String     # Equality
.if REF != REF | String     # Inequality
.if REF                     # Existential
.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.