NIDR Extensions

Here is a brief account of facilities added to nidrgen
after SAND2008-2261P ("Specifying and Reading Program Input with NIDR",
http://www.sandia.gov/~dmgay/nidr08.pdf) was written.
The facilities are meant to simplify preparation and maintenance
of an updated Jaguar (a GUI for DAKOTA).

New possible items in the input .spec file:

	>  num
	>= num
	<= num
	<  num

specify bounds on numerical entities (INTEGER, INTEGERLIST,
REAL, REALLIST).

	:= value
	:= defname value

specifies a default value (string-valued for STRING and STRINGLIST,
numeric for INTEGER, INTEGERLIST, REAL, REALLIST); if defname is
present, it must be of a form acceptable as a C-preprocessor name
(i.e., starting with an upper or lower case letter, followed by
a possibly empty string of letters, digits and underscores).
With suitable nidrgen invocations (described below), the collection
of defnames is turned into a header file of #define lines, so
the defnames can be used in the DAKOTA source to provide initial
values that are automatically in sync with the .nspec file
(and which the GUI can show).

The following new items are included in a variant of NIDR_keywds.H,
tentatively called $DAKOTA/src/NIDR_guikeywds.h, that has extra
information for GUIs.

	DESC string

provides a description of the associated keyword, perhaps
including a URL for more detailed discussion.

	GROUP string

provides details about screen layout and possibly a
"screen name" for the associated keyword.

	LEN keyname

indicates an INTEGER-valued keyword whose value specifies
the length of the present keyword, which should be of type
INTEGERLIST, REALLIST, or STRINGLIST.

	TAG string

provides a way to connect this keyword with further entries
for it (typically GROUP, LEN, and DESC) taken from a second
input file (tentative called $DAKOTA/src/dakota.input.desc).
Such entries begin with the same "TAG string".

Two new fields appear in NIDR_keywds.H:  REAL-valued lower
and upper bounds for INTEGER, INTEGERLIST, REAL, and REALLIST
keywords (if specified with the <, <=, >=, and/or > operators
above).  New bits in the "kind" field indicate whether bounds
are present and whether they are strict.

The GUI variant NIDR_guikeywds.h omits function details
(pointers to functions that the NIDR parser calls when DAKOTA
runs) and adds a keyword number, initial values (numeric and
string, the relevant one depending on the keyword's type),
and the GROUP and DESC strings.

Strings are delimited by " characters.  A "string" value
can be broken into several adjacent quoted strings
(separated by white space, including newlines), which are
concatenated, as in C or C++ source files.  For example,

	"This is an"
	" example of strings"
	" to be concatenated."

is treated the same as

	"This is an example of strings to be concatenated."

When invoked with any of

	nidrgen -?
	nidrgen -h
	nidrgen --help

the parser-generator nidrgen explains its usage.  For example,

	nidrgen foo.spec foo.desc outdefs.h outkeywds.h

reads the first two files and writes the second two
(with outdefs.h containing #define lines and outkeywds.h
corresponding to $DAKOTA/src/NIDR_keywds.H).  For another example,

	nidrgen -g foo.spec foo.desc >guikeywds.h

writes the GUI variant of the keyword header (called NIDR_guikeywds.h
above).  For more examples, see the makefile.

As a possible convenience, for keywords that have a TAG but not
a GROUP specification, the TAG is supplied as GROUP in
NIDR_guikeywds.h (unless nidrgen is invoked with -G to suppress
this behavior).

-- David M. Gay, 16 Dec. 2008
