Most of the files in this "parserTestFiles" directory are DMIS input files
and have the suffix ".dmi". These are files for testing DMIS parsers.

The OK.out file in the okOut directory has two lines: 
  0 errors
  0 warnings

The OKconf.out file in the okOut directory has three lines: 
  0 errors
  0 warnings
  0 conformance checker errors

All the other files in this directory that have the suffix ".out" are files
containing the error messages that the NIST DMIS parser prints when it
parses a file with the same base name and a ".dmi" suffix. The files in
this directory that have the suffix ".out" are NOT DMIS output files.

This directory has the following subdirectories:
   annexAIn
   annexAOut
   errorIn
   errorOut
   okIn
   okOut

The annexAIn directory contains the examples from Annex A of DMIS
5.2, in most cases modified by adding DMISMN and ENDFIL.

The okIn directory contains one or more syntactically correct
parser test files for each subsection of section 6 of DMIS 5.2. The
name of most of these files corresponds to the name of a DMIS
statement. These directories also contain syntactically correct programs
testing expressions and the preprocessor of the NIST DMIS parser.

The errorIn directory contains parser test files with errors in
them. The file names of all of these files include the string "Error".
 
The errorOut directory contain ".out" files corresponding to the
errorIn files. Each file contains the error messages printed by the
NIST DMIS parser when it parses the corresponding errorIn file.

******************************************************************

The files in this directory are PARSER TEST FILES and may make
little or no sense as programs. Read on for an explanation.

DMIS input test files might be written for three purposes:

1. to test DMIS parsers -
   Parser test files test only a parser's ability to handle the syntax
   of the language. Statements may violate semantic rules, such as allowing
   reference to an actual feature before the feature has been measured or
   constructed. Also, the sequence of statements does not necessarily do
   anything useful. The files in this directory are parser test files
   with a few checks added, as described below.

2. to test DMIS interpreters
   Interpreter test files test the interpreter's ability to parse, to
   enforce semantic rules, and to perform computations. The sequence
   of statements does not necessarily do anything useful. Many of the
   files in this directory are NOT interpreter test files. They are
   full of violations of semantic rules.

3. to test DMIS execution systems
   Execution system test files test the system's ability to parse,
   to enforce semantic rules, to perform computations, and
   to carry out DMIS statements properly. Most of the files in
   this directory are NOT execution system test files.

Many constraints may be expressed either (1) in syntax rules that run while
a DMIS input file is being parsed, or (2) in the source code of checking
functions that run after reading a statement (or an entire file) is complete.
The files in this directory conform to those syntax rules implicit in the
EBNF for DMIS plus additional rules about variables and labels. The parsers
in the parsers directory enforce all of these rules. These syntax rules
include the following requirements that might not be enforced at the parser
level in some DMIS execution systems:

1. Except for comment lines (which may appear anywhere), the first line
must be a DMISMN or DMISMD statement, and the last line must be ENDFIL.

2. All variables must be explicitly declared with DECL or implicitly
declared by being parameters of a MACRO.

3. A variable of a given name may not be declared twice with DECL or
used twice as a parameter of the same MACRO.

4. Whenever a statement or expression requires a variable to be of a
given type, the variable used must be of the correct type.

5. Integer values (not real values) must be used where DMIS requires
integer values.

6. A label with a given label type and label name may not be defined
more than once (except for feature labels).

7. A label may not be referenced before it is defined.

8. Each block of statements defined in DMIS (MEAS-ENDMES, SELECT-ENDSEL,
   etc.) must end with a specific statement that matches the statement at
   the beginning of the block.

9. Some blocks of statements defined in DMIS may contain only certain types
   of statement (for example, a GOTARG-ENDGO block may contain only GOTOs).

The way the parsers check labels and variables is not foolproof. The
following constructions in a DMIS input file will fool a parser.
A. A label name is constructed using the "@variable" method. The
   parser does not evaluate variables, so it will not know what
   label has been defined in this case. If the label is referenced
   literally later on in the file, the parser will think it is undefined.
B. A variable is DECLared near the end of a file and referenced near the
   beginning of the file, but the program uses JUMPTOs so that when
   the program is executed, the DECLaration is executed before the
   line referencing the variable is executed. The parser does not
   follow JUMPTOs, so it will think the variable has not been
   DECLared when it is referenced.
   See parserTestFiles/errorIn/foolParser.dmi
C. The same variable is DECLared (or the same label is defined) in two
   branches of an IF-ELSE or a SELECT-ENDSEL. The parser does not
   execute IF-ELSEs or SELECT-ENDSELs, so it will think that the
   variable is DECLared twice (or the label is defined twice).
   The parser can be fooled in the same way if there is a
   sequence of IFs each of which DECLares the same variable and
   only one of which can possibly be executed.

Because the parsers can be confused regarding labels and variables,
the parsers usually issue warning messages rather than error messages
for undefined or multiply defined labels and variables, except that
situation B above is so perverse that an error is reported if it occurs.

