$Id: tconfpy-spec.txt,v 1.1 2003/07/01 19:46:31 tundra Exp $

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


API
===

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

                 ---> [SymTable, ErrList, FatalError]


where,

FileName   --->  String

Options    --->  {"BoolOpts" : [bopt, bopt, ...],
                 "NumOpts"  : [nopt, nopt, ...],
                 "StrOpts"  : [sopt, sopt, ...]
                 }

 
                 bopt = [name, default]

                 nopt = [name, default, [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, [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 throughout config file.

SymTable   --->  {Symbol Name : Symbol Value}

ErrList    --->  [ParseErr, ParseErr, ...]

                 ParseErr = [File Name, Line Number, Error String]

FatalError --->  If True, means parsing failed pathologically, and
                 pgm should not continue



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 Names & Dereferencing
------------------------------

Variables 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 are
considered predefined and are intialized 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


Assignment
----------

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 ('=').  Any symbol which appears as a predfined
Option passed into the parsing API may only have one value
associated with it AND that value must conform to the 
set of legal values defined for that variable in the associated
Options entry.

x = y = z ... 

This means the Symbol Table will return an entry in this form:

{'x' : ['y', 'z', ...]}