USAGE
=====
Use: testgen testdescriptionfile.tst

generates .mms files from a testdescription file

OPTIONS
=======
-Ipath
    add the path to the list of directories 
    searched for include files after . and ./lib

-Xextension
   append extension instead of mms as the extension to the
   generated testfiles

-M  
    generate rules for use in a Makefile
    instead of generating Testfiles, it outputs 
    a list of all the files that are included.
    
    Specifying -M twice, will output rules for all the generated
    test files.


TEST DESCRIPTION FILES
======================
These files contain:
Specials and Plain Text.
Specialls are: Comments, Variable Definitions, Variables, 
Include Files, and Test Declarations.

Specials start with [[ and end with ]].

Plain Text from the description file is copied to an output file
if such an output file is defined.

At the beginning of the description file, there is no output file,
but the file may contain usefull variable definitions.
An output file is opend and closed with a Test Declaration.

Test Declaration
================
A Test Declaration has two parts:
[[TEST number]] then some text [[END number]]

The number in the TEST and in the END Special must be the same.
If there are (as usual) multiple Test Declarations is the file,
they must not overlap and the numbers must be in increasing order.

The name of the output file is formed by the name of the input file
followed by '-', followed by the number, followed by '.mms'.

The [[TEST number]] opens the file, the [[END number]] closes the file.
The Text in between is copied into the file.

Comments
========
A Comment has the form 
[[COMMENT some text]]
the text inside this Special is just ignored.
The text inside the Comment must not contain a ']]'
The first occurence of ']]' ends the comment (so no nesting).

Include Files
=============
The Special [[INCLUDE filename optionalArguments]]
opens the named file (either in the current directory
or in the directory where the program testgen is located
and replaces the Special [[INCLUDE ...]] by the content
of this file and reading continues with the first character
of that file.

(For optional Arguments see below).

Variable Definitions
====================
The Special [[SET name value]]
defines a new variable with the given name and assigns it
the given value.
The name may consists of upper- and lower-case letters and
the decimal digits from 0 to 9. 
It must not be SET, COMMENT, TEST, END, or INCLUDE.

The value, can be anny text. It may contain properly nested
'[[' and ']]' pairs. So the value may contain Specials.
It is ended by the final ']]'.

Using Variables
===============
The special [[name optionalArguments]] requires the
name of a previosly defined variable. The special 
[[name ...]] is then replaced by the value of that variable
and reading continues with the first character of that value.

There are some predefined variables (see below).

(For optional Arguments see below).

Skope
=====
Variables are defined within a scope and are deleted, when the scope
ends. Scopes can be nested. Variables in outer scopes
can be used in inner scopes, but they can also be shadowed by
variables of the same name in inner scopes.

The outermost scope starts with the test description file and ends 
with the fiel.

Every Test has its own scope. It starts with the [[TEST ...]] special
and ends with the [[END ...]] special.

Every include file has its own scope. It starts with the [[INCLUDE ..
special and ends with the end of the include file.

Every value of a variable has its own scope, it starts with [[name ..
and ends with the end of the value of the variable.

Include files as well as variabled can be arbitrarily mixed and nested.

Optional Arguments
==================
Variable values and include files can have parameters.
These are variables with the names 1, 2, 3, ...
If an include or variable special has optional arguments,
first the new scope for the file or the value is created and
then the optional arguments are assigned to the 
variables 1, 2, 3, ... in the order in which they are listed.
Inside the file or the value, they can be used as [[1]], [[2]], ...

Optional arguments are just text. The text may contain
properly nested '[[' and ']]' pairs. Multiple arguments are
separated by white space outside of  '[[' and ']]' pairs.

Predefined Variables
====================
Currently there are the following predeifined variables:

OctaEqual
---------
Adding [[OctaEqual A B n]] to your driver code includes a MMIX code
that expects three parameters: A, B, and n
A and B are addresses of octa arrays, n ist the number of octas in
each of these arrays. The code compares the two arrays
and exits with 1 if the arrays are not equal.

ByteEqual
---------
Like OctaEqual but compares arrays of byte.

StringEqual
-----------
Like ByteEqual, but there is no third parameter for the size,
instead the comparison stops with the first zero byte encountered.


EXAMPLE 1
=========

the file to test: set17.mms
--------------------------
	SET $1,17
--------------------------

the testfile: set17.tst
--------------------------

	set17.mms

[[SET DRIVER

	LOC	#100
Main	SET	$3,123

	[[INCLUDE set17.mms]]

	CMP	$0,[[register]],[[number]]
	BNZ	$0,Error
	SET	$255,0; TRAP 0,Halt,0
Error	SET	$255,1; TRAP 0,Halt,0

]]


[[SET register $1]]

[[COMMENT first test: set variable number and expand DRIVER into set17.tst-1.mms]]
[[TEST 1]]
[[SET number 17]]
[[DRIVER]]
[[END  1]]

[[COMMENT second test: shadow register, set number number and expand DRIVER into set17.tst-2.mms]]
[[TEST 2]]
[[SET register $3]]
[[SET number 123]]
[[DRIVER]]
[[END  2]]


-------------------------------------------
Calling

testgen set17.tst

will generate 3 files: set17.tst-1.mms set17.tst-2.mms 

set17.tst-1.mms
--------------------------------------------
        LOC     #100
Main    SET     $3,123

        SET $1,17

        CMP     $0,$1,17
        BNZ     $0,Error
        SET     $255,0; TRAP 0,Halt,0
Error   SET     $255,1; TRAP 0,Halt,0
--------------------------------------------

set17.tst-2.mms
--------------------------------------------
        LOC     #100
Main    SET     $3,123

        SET $1,17


        CMP     $0,$3,123
        BNZ     $0,Error
        SET     $255,0; TRAP 0,Halt,0
Error   SET     $255,1; TRAP 0,Halt,0

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


running the script 

testrun set17.tst will produce:

--------------------------------------------
set17.tst-1.mms OK
set17.tst-2.mms OK
--------------------------------------------
     
EXAMPLE 2
=========
The following file bubble.tst tests bubble.mms containing the
procedure BubbleSort.
After specifiying the Driver code that includes the Program 
fragment under test and the predefined code OctaEqual to test
two Octa Arrays for equality, there are 6 tests, that use
the variables In, Out and n to specify several test parameters.
--------------------------------------------

[[SET Driver

		LOC	Data_Segment
		GREG	@
Data		[[In]]
Size		IS	[[n]]		
Sorted		[[Out]]

		LOC	#100
Main		LDA	$1,Data
		SET	$2,Size
		PUSHJ	$0,BubbleSort

		[[OctaEqual Data Sorted Size]] 

		SET	$255,$0 
		TRAP 0,Halt,0

[[INCLUDE bubble.mms]]

]]

[[TEST 1]]
	[[SET In  OCTA 5,0]]
	[[SET n     1]]
	[[SET Out OCTA 5,0]]

	[[Driver]]
[[END 1]]

[[TEST 2]]
[[SET In OCTA 5,2,0]]
[[SET n  2]]
[[SET Out OCTA 2,5,0]]
[[Driver]]
[[END 2]]

[[TEST 3]]

[[SET In OCTA 2,5,0]]
[[SET n  2]]
[[SET Out OCTA 2,5,0]]

[[Driver]]
[[END 3]]

[[TEST 4]]
  [[SET In OCTA 3,2,5,0]] [[SET n  3]] [[SET Out OCTA 2,3,5,0]]
  [[Driver]]
[[END 4]]

[[TEST 5]]

[[SET In OCTA 5,3,2,5,0]]
[[SET n  4]]
[[SET Out OCTA 2,3,5,5,0]]

[[Driver]]

[[END 5]]

[[TEST 6]]

[[SET In OCTA 5,3,2,5,7,11,-3,2,99,5,0]]
[[SET n  10]]
[[SET Out OCTA -3,2,2,3,5,5,5,7,11,99,0]]

[[Driver]]

[[END 6]]

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