From pippin at owlriver.net  Fri Feb 19 19:27:19 2010
From: pippin at owlriver.net (Bill Pippin)
Date: Fri, 19 Feb 2010 19:27:19 -0500
Subject: [ts-gen] New "init" option, "let" command, and config syntax
Message-ID: <E1NidBn-0006vJ-Gy@pippin.first.lan>

There have been a number of changes to how configuration information
is provided to a shim process, including a non-portable change of
the configuration file syntax.

In brief, there is a new cmd line option "init", and a new
command, "let", e.g.:

    let DbmsHost = xps400,	# you may use comments 
        ApiLevel = 23;		# and whitespace freely

The let statement must occur as either the first statement in the
cmd input stream, or as the first and only statement in the .shimrc
config file.  Note that, with the config file now consisting of a
let command, the older name-value pair syntax is no longer supported. 

Note also that the tarball shimrc file as delivered no longer is
named with the leading dot, so that the user will need to copy or
rename this file before it is visible to the shim.

The tarball shimrc file includes a list of configuration variables
with explanation and default values, and that text is not repeated
herein; if you're interested, see the tarball shimrc file.

The tarball shimrc also includes an extensive explanation of the
init option and let command, and the following text is paraphrased
from that material, so, as for configuration itself, and the let
command, in more detail:
________________________________________________________________________

File configuration occurs first, with the shim reading in a .shimrc
file if one exists in the current directory, or else from the home
directory if one exists there, and not in the local directory.  Next
and last, if the "init" option occurs on the command line, a let
statement is read in from the command input stream, the stdin.

Later configuration values override earlier ones.  The language of
configuration files and the init option is the same; both expect
exactly one let command, and the reading of config input, whether
from a file or the stdin, ceases once it is reached.  Once any
config file and init option let statements have been read in, the
then shim goes on to finish internal configuration.  Any regular
commands from the stdin following the let command are ignored
until main loop processing, after initialization is complete.

The functionality of the let command subsumes that of the older
dbms and feed commands used previously with the link option, and
those commands have been eliminated.  The rules for the syntax of
the let command are as follows:

    LetCmd <- "let" NvPair EqList
    EqList <- ","   NvPair EqList
            | ";"
    NvPair <- Name "=" Value

In the bnf above, "<-" stands for reverse implication, "|" for
disjunction, literals are quoted, non-literal language symbols
have initial caps, and the undefined terminal symbols "Name" and
"Value" refer to shim configuration variable names and the values
with which they are to be bound, about which, see the tarball
shimrc.

The use in the let command of command punctuation, whether equals
sign, comma, or semicolon, is not optional, and syntax errors while
parsing configuration input will, by design, lead to program
termination.

Comments and whitespace may be used freely throughout the .shimrc,
and for that matter, in the command input stream as well.

All configuration variables have default values, and in most cases,
those will be what you want.  For more information about these, see
the shimrc file in a recent (2010) tarball.

Thanks,

Bill