[Pntool-developers] SF.net SVN: pntool:[197] spnbox

[<Ste...@us...>]

Revision: 197
          http://pntool.svn.sourceforge.net/pntool/?rev=197&view=rev
Author:   StephenCamp
Date:     2009-07-14 21:32:17 +0000 (Tue, 14 Jul 2009)

Log Message:
-----------
Added notes to spnbox.h function comments about the differences between C and Matlab usage.
Added a "help" feature to the test routines, allowing a user to get some information from the test programs themselves about how they should be used. (Had to modify virtually all test files very slightly to get this done.)

Modified Paths:
--------------
    spnbox/spnbox.h
    spnbox/tests/StructuredIO.c
    spnbox/tests/StructuredIO.h
    spnbox/tests/test-actn.c
    spnbox/tests/test-extendedmatrix.c
    spnbox/tests/test-ilpadm.c
    spnbox/tests/test-ipsolve.c
    spnbox/tests/test-isadm.c
    spnbox/tests/test-issiph.c
    spnbox/tests/test-linenf.c
    spnbox/tests/test-matrixmath.c
    spnbox/tests/test-msplit.c
    spnbox/tests/test-nltrans.c
    spnbox/tests/test-pn2acpn.c
    spnbox/tests/test-pn2eacpn.c
    spnbox/tests/test-reduce.c
    spnbox/tests/test-supervis.c
    spnbox/tests/test-tactn.c
    spnbox/tests/test.c
    spnbox/tests/test.h

Modified: spnbox/spnbox.h
===================================================================
--- spnbox/spnbox.h	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/spnbox.h	2009-07-14 21:32:17 UTC (rev 197)
@@ -6,8 +6,8 @@
 #include "../third-party/lp_solve_5.5/lpkit.h"
 
 typedef struct supervis_r { /* result of supervis */
-  matrix Dfm;
-  matrix Dfp;
+  matrix Dfm;		//The supervised net output matrix
+  matrix Dfp;		//The supervised net input matrix
 } supervis_r;
 
 typedef struct ipslv_r {
@@ -17,17 +17,19 @@
 } ipslv_r;
 
 typedef struct ipsolve_r { /*Result of ipsolve*/
-  double* res;
-  char* mhow;
+  double* res;	//A pointer to an array of doubles containing the solution.
+  char* mhow;		//A pointer to a statically-defined result message. DO NOT
+								//DEALLOCATE!
 } ipsolve_r;
 
 typedef struct ilpadm_r {/*Result of ilpadm*/
-  matrix La;
-  int* ba;
-  matrix R1;
-  matrix R2;
-  char* how;
-  char** dhow;
+  matrix La;		//The new constraint matrix.
+  int* ba;			//The new constraint vector, given as a pointer to an integer array.
+  matrix R1;		//The transform matrix R1.
+  matrix R2;		//The transform matrix R2.
+  char* how;		//Overall result message. Statically defined (do not deallocate).
+  char** dhow;	//Array of result messages, one for each constraint. The array
+								//may be deallocated, but the individual messages should not be.
 } ilpadm_r;
 
 typedef struct linenf_r 
@@ -67,58 +69,90 @@
 
 typedef struct nltrans_r
 {
-	int* dtr;
-	int dtrCount;
+	int* dtr;				//The list of unraisable transitions given as a pointer to an array
+	int dtrCount;		//The number of elements in the dtr array
 } nltrans_r;
 
 typedef struct pn2acpn_r
 {
-	matrix Df;
-	matrix Dmf;
-	matrix Dpf;
-	matrix MXF;
+	//The final Petri net matrices
+	matrix Df;		
+	matrix Dmf;		
+	matrix Dpf;		
+	//Modified constraint matrices
+	matrix MXF;		
 	matrix L0F;
 	matrix LF;
+	//The new independent place list, given as a pointer to an array of integers
 	int *iplf;
+	//The number of independent places (length of the iplf array)
 	int iplfCount;
 } pn2acpn_r;
 
 typedef struct pn2eacpn_r
 {
+	//New Petri net matrices
 	matrix Df;
 	matrix Dmf;
 	matrix Dpf;
+	//New constraint matrices
 	matrix MXF;
 	matrix L0F;
 	matrix LF;
+	//New independent place list, given as a pointer to an array of integers.
 	int *iplf;
+	//Length of the independent place list.
 	int iplfCount;
+	/*New list of transitions that are unraisable when a given transition is dead.
+	This is a pointer to an array of integer arrays. There is an element for each
+	transition. Each array lists the transitions that cannot be raised if the
+	transition that array corresponds to is dead.*/
 	int **TD;
+	/*The number of elements in each of the arrays in the TD array of arrays.
+	This is a pointer to an array of integers, one for each transition, that lists
+	the number of elements in the corresponding array in TD.*/
 	int *TDCount;
 } pn2eacpn_r;
 
 typedef struct chkcons_r
 {
+	/*The solution of the ipsolve problem that is done internally.*/
 	double* res;
+	/*The number of elements in the solution array.*/
 	int resCount;
 } chkcons_r;
 
 typedef struct reduce_r
 {
+	/*The new constraint matrix*/
 	matrix Lf;
+	/*The new constraint vector (an array of integers)*/
 	int* Bf;
+	/*An array of integers, each one of which is the index of an original transition
+	that was kept. 
+	Has as many elements as there are rows in Lf.*/
 	int* indf;
+	/*An integer giving a status message. See "reduce" for meaning.*/
 	int how;
 } reduce_r;
 
 typedef struct actn_r
 {
+	/*The input and output matrices of the active subnet, given as a copy of the 
+	original subnet with dead	transitions and/or places overwritten with zeroes.*/
 	matrix Dma;
 	matrix Dpa;
+	/*The input and output matrices of the active subnet, given as those rows from
+	Dma and Dpa that were not overwritten with zeroes.*/
 	matrix Dmra;
 	matrix Dpra;
+	/*The list of active transitions. This is a pointer to an array of integers,
+	each one of which is the index of a transition that made it into the active
+	subnet.*/
 	int* TA;
+	/*The number of active transitions, i.e. length of the TA list.*/
 	int TACount;
+	/*This flag will be meaninful only if a uniqueness check was done. See actn.*/
 	int unique;
 } actn_r;
 
@@ -171,6 +205,7 @@
 
 msplit_r msplit(matrix* Dm, matrix* Dp, int* mask, matrix* M, matrix* L0, matrix* L, int* ipl, int ipCount, int* dpl, int dpCount, int** TD, int* TDCount);
 /*MSPLIT - split transitions to make a Petri net PT-ordinary.
+Original Matlab Usage:
 [DF, DFM, DFP] = msplit(DM, DP)
 
 [DF, DFM, DFP] = msplit(DM, DP, mask)
@@ -192,11 +227,27 @@
 through transition split.
 Used in DP.
 
+Usage In C:
+msplit_r msplit(matrix *Dm, matrix *Dp, int *mask, matrix *M, matrix *L0, 
+matrix *L, int *ipl, int ipCount, int *dpl, int dpCount, int **TD, int *TDCount)
+Parameters have the same meaning and usage as in Matlab with the following
+differences and notes:
+* Mask: Integer array. Same as "mask" in matlab. Not required. If not present
+  Mask is assumed to be all 1's.
+* ipl, ipCount: Pointer to an integer array and the number of elements in the
+  array, respectively. Same as ipl in Matlab. Not required. If not present,
+	defaults to an array containing the index of each place in the net. This also
+	forces dpl to default to empty. Note that the sum of ipCount and dpCount must
+	be the same as the total number of places in the Petri net.
+* dpl, dpCount: Pointer to an integer array and the number of elements in the
+	array, respectively. Same as dpl in Matlab. See ipl, ipCount for defaults.
+
 Written for Matlab by Marian V. Iordache, mar...@le....
 Converted to C by Marian V. Iordache and Stephen Camp, ste...@le....*/
 
 ilpadm_r ilpadm(matrix* L, int* b, matrix* D, int TucCount, int* Tuc, int TuoCount, int* Tuo, int* m0);
 /*ILP_ADM - transformation to admissible constraints based on linear integer programming
+Original Matlab usage:
 [La, ba, R1, R2, how, dhow] = ilp_adm(L, b, D, Tuc, Tuo, m0, vrb)
 
 The function transforms a marking constraint L*m <= b to an admissible 
@@ -218,6 +269,20 @@
  
 Use m0 = [] or only the first five arguments if the initial marking is not of interest. 
 
+Usage in C:
+ilpadm_r ilpadm(matrix* L, int* b, matrix* D, int TucCount, int* Tuc, int TuoCount, 
+int* Tuo, int* m0);
+The parameters have the same meaning as in Matlab with the following notes and
+exceptions:
+* b is an integer array, used as in matlab. If not present defaults to all zeroes.
+* TucCount, Tuc. The number of elements in and an array of integers containing 
+  the list of uncontrollable transition indices, respectively. Not required.
+	Same as Tuc in Matlab.
+* TuoCount, Tuo. The same as Tuc but for unobservable transitions. Same as Tuo
+  in Matlab.
+* The vrb parameter from Matlab has been dispensed with. ilpadm now uses the 
+  program-wide verbosity level.
+
 Written for Matlab by Marian V. Iordache, mar...@le.... 
 Converted to C by Marian V. Iordache and Stephen Camp, ste...@le....*/
 
@@ -241,7 +306,7 @@
 
 ipsolve_r ipsolve(matrix* L, double* B, double* f, short int *IntList, double *ub, double *lb, short int *ctype);
 /* ipsolve - Interface to the Mixed Integer Program Solver LP_SOLVE
-
+Original Usage in Matlab:
 [res, how] = ipsolve(L, B, f, intlist, ub, lb, ctype)
 The function minimizes f'*x subject to Lx >= B and lb <= x <= ub.
 x(i) is an integer if intlist(i) is not zero. 
@@ -266,6 +331,12 @@
 
 Another integer program solver is SOLVE_IP.
 
+Usage in C:
+ipsolve_r ipsolve(matrix* L, double* B, double* f, short int *IntList, double *ub, double *lb, short int *ctype)
+All parameters have the same meaning as in Matlab. B, f, IntList, ub, and lb are
+all pointers that should point to the first element of an array of the appropriate
+length or be given as a null pointer.
+
 This interface to the LP_SOLVE package has been 
 written by Marian V. Iordache, mar...@le....
 It was converted to C by Marian V. Iordache and Stephen Camp, ste...@le....*/
@@ -295,7 +366,7 @@
 The function returns the structure that corresponds to the supervised
 Petri net, and the initial marking of the supervised Petri net (ms0),
 (the argument m0 specifies the initial marking of the plant Petri net.)
-The initial firing vector v0 is assumed to be 0. The syntax is:
+The initial firing vector v0 is assumed to be 0. The Matlab syntax is:
 
 [Df^-, Df^+, ms0] = linenf(pn, L, b, F, C)
 
@@ -380,6 +451,15 @@
 The disadvantage of using a precomputed plant coverability graph is that
 it is more likely to have a v(i) equal to -1.
 
+Usage in C:
+linenf_r linenf(matrix* Dm, matrix* Dp, matrix* L, int* b, int* m0, matrix* F, matrix* C, int TucCount, int* Tuc, int TuoCount, int* Tuo)
+All parameters have the same names as their counterparts in Matlab. Parameters
+in matlab that were vectors are passed in C as array pointers. The variable-length
+vectors Tuc and Tuo are given in two parts, an integer (TucCount/TuoCount) specifying
+the length of the array followed by a pointer (Tuc/Tuo) to the first element of the
+array. The form of the function call making use of a pnobj structure is no longer
+valid.
+
 See LINENF and PNCGRAPH.
 
 Written for Matlab by Marian V. Iordache, mar...@le....
@@ -390,6 +470,7 @@
 /*
 NLTRANS - Find all transitions that cannot be made live
 
+Usage in Matlab:
 [nlt] = nltrans(D)
 
 [nlt] = nltrans(D^-, D^+, X)
@@ -400,6 +481,14 @@
 other reasons. E.g. X = [1, 3, 6] indicates the transitions t_1, t_3
 and t_6.
 
+Usage in C:
+nltrans_r nltrans(matrix* D, int* UnraisableTransitions, int urtCount)
+D is the same as D in Matlab. The function no longer accepts separate D+ and D-
+matrices. X in Matlab corresponds to the array pointer UnraisableTransitions.
+UnraisableTransitions should be the pointer to the array containing the
+transitions to be assumed unraisable, and urtCount should be set to the number
+of elements in the array.
+
 Written by Marian V. Iordache, mar...@le....
 Converted to C by Marian V. Iordache and Stephen Camp, ste...@le...
 */
@@ -408,6 +497,7 @@
 /*
 PN2ACPN - Transforms a Petri net to an asymmetric choice Petri net
 
+Matlab Usage:
 [Df, Dmf, Dpf] = pn2acpn(D)
 
 [Df, Dmf, Dpf] = pn2acpn(Dm, Dp)
@@ -428,6 +518,13 @@
 
 See MSPLIT.
 
+C Usage:
+pn2acpn_r pn2acpn(matrix* Dm, matrix* Dp, int* Mask, matrix* MX, matrix* L0, 
+matrix* L, int *ipl, int ipCount, int* dpl, int dpCount)
+Dm and Dp are the same as in Matlab. The function no longer accepts a single
+incidence matrix D. The variable-length vectors ipl and dpl in Matlab should
+be passed as a pointer to the integer array followed by the length of the
+array.
 
 Written by Marian V. Iordache, mar...@le...
 M. Iordache -- Sep. 4, 2000
@@ -441,6 +538,7 @@
 /*
 PN2EACPN - Transforms a Petri net to an extended asymmetric choice Petri net
 
+Matlab Usage:
 [Df, Dmf, Dpf] = pn2eacpn(D)
 
 [Df, Dmf, Dpf] = pn2eacpn(Dm, Dp)
@@ -466,6 +564,15 @@
 
 See MSPLIT.
 
+C Usage:
+pn2eacpn_r pn2eacpn(matrix* Dm, matrix* Dp, int* Mask, matrix* MX, matrix* L0, 
+matrix* L, int *ipl, int ipCount, int* dpl, int dpCount, int** TD, int* TDCount)
+Dm and Dp are the same as in Matlab. The function no longer accepts a single
+incidence matrix D. The variable-length vectors ipl and dpl in Matlab should
+be passed as a pointer to the integer array followed by the length of the
+array.
+
+
 Written for Matlab by Marian V. Iordache, mio...@nd...
 Original Matlab code extended the Matlab pn2acpn code written on
 M. Iordache -- Sep. 4, 2000
@@ -481,6 +588,7 @@
 
 chkcons_r chkcons(matrix* L0, int* B0, matrix* l0, int b0);
 /*
+Matlab Usage:
 res = chk_con2(L,B,l,b)
 
 Checks consistency of the set of constraints Lx >= B and lx< b, 
@@ -492,8 +600,15 @@
 that Lx >= B and lx < b. If res is empty, then the constraint 
 lx >= b is redundant for Lx >= B.
 
-The C implementation of chkcons currently is an implementation of CHK_CON2.M from the original Matlab package.
+C Usage:
+chkcons_r chkcons(matrix* L0, int* B0, matrix* l0, int b0)
+The parameters have the same names and meanings as in Matlab. Either the pair L0
+& l0 or the pair B0 and b0 is required. Both pairs can be given. If B0 is a null
+pointer, the value of b0 is ignored.
 
+The C implementation of chkcons currently is an implementation of CHK_CON2.M 
+from the original Matlab package.
+
 CHK_CON2 is the old version of CHK_CONS. It is expected to be
 slower than CHK_CONS. However, CHK_CON2 is simpler, and so it
 may be more reliable. 
@@ -506,6 +621,7 @@
 
 reduce_r reduce(matrix* L0, int* B0);
 /*
+Matlab usage:
 [Lf, Bf, ind, how] = reduce(L,B)
 
 This function removes redundant constraints of Lx>=B, where x 
@@ -515,6 +631,10 @@
 
 See also CHK_CONS, IP_SOLVE.
 
+C Usage:
+reduce_r reduce(matrix* L0, int* B0)
+L0 and B0 are L and B, respectively, from the Matlab version.
+
 Written for Matlab by Marian V. Iordache, mar...@le....
 Converted to C by Marian Iordache and Stephen Camp, ste...@le....
 */
@@ -522,7 +642,7 @@
 actn_r actn(matrix* Dm, matrix* Dp, int* X, int XCount, matrix *Dcm, matrix *Dcp, int update, int checkUnique);
 /*
 ACTN - The active subnet of a Petri net
-
+Matlab usage:
 [Dma, Dpa, Dmra, Dpra] = actn(Dm, Dp)
 
 [Dma, Dpa, Dmra, Dpra] = actn(Dm, Dp, X)
@@ -547,6 +667,15 @@
 
 See also NLTRANS. 
 
+C Usage:
+actn_r actn(matrix* Dm, matrix* Dp, int* X, int XCount, matrix *Dcm, matrix *Dcp, int update, int checkUnique)
+Parameters have the same names as in Matlab with a few exceptions. The variable-length
+vector X is passed as the pointer to the integer array (X) followed by the number of
+elements in the array (XCount). The additional parameter, checkUnique, should be
+nonzero if the user wants to run a uniqueness check. Note that the uniqueness check
+is time-consuming. If the check is not run, the value if "unique" in the result
+structure will be set to 0 regardless of the actual state of the result.
+
 Written for Matlab by Marian V. Iordache, mar...@le....
 Converted to C by Marian Iordache and Stephen Camp, ste...@le....
 */
@@ -555,6 +684,8 @@
 /*
 TACTN - Computes a T-minimal active subnet of a Petri net
 
+Matlab usage:
+
 [Dma, Dpa, Dmra, Dpra, TA] = tactn(Dm, Dp, T, Z)
 [Dma, Dpa, Dmra, Dpra, TA, unique] = tactn(Dm, Dp, T, Z)
 
@@ -603,6 +734,18 @@
 
 See also ACTN and NLTRANS. 
 
+C Usage:
+tactn_r tactn(matrix* Dm, matrix* Dp, int* IncludeT, int IncludeTCount, int* ExcludeT, int ExcludeTCount, matrix *Dcm, matrix *Dcp, int checkUnique)
+
+Parameters have the same names as in Matlab with a few exceptions. IncludeT and
+ExcludeT replace the variable-length vectors T and Z. They should be given as 
+the pointer to the integer array (IncludeT or ExcludeT) followed by the number of
+elements in the array (IncludeTCount or ExcludeTCount). The additional parameter,
+checkUnique, should be nonzero if the user wants to run a uniqueness check. Note 
+that the uniqueness check is time-consuming. If the check is not run, the value 
+of "unique" in the result structure will be set to 0 regardless of the actual 
+state of the result.
+
 Written for Matlab by Marian V. Iordache, mar...@le...
 
 Marian V. Iordache, Sep. 5, 2000.
@@ -626,6 +769,13 @@
 flag = (S == siphon)
 flx  = sum(flag == 0) (i.e. flx is nonzero if a column of S is not a siphon)
 
+C Usage:
+issiph_r issiph(matrix *Dm, matrix *Dp, void *PlaceSet, int MultiplePlaceSets)
+The parameter S in Matlab is equivalent to the parameter PlaceSet in C.
+If MultiplePlaceSets is nonzero, PlaceSet is interpreted as a pointer to a matrix
+formated as described above. Otherwise, PlaceSet is interpreted as a pointer
+to an integer array, where each integer is a flag as described above.
+
 Written for Matlab by Marian V. Iordache, mar...@le....
 Converted to C by Marian V. Iordache and Stephen Camp, ste...@le....
 */

Modified: spnbox/tests/StructuredIO.c
===================================================================
--- spnbox/tests/StructuredIO.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/StructuredIO.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -8,7 +8,7 @@
 name = any string without whitespace.
 TYPE = one of:
 	matrix				A matrix.
-	matrix*				A pointer to a matrix.	
+	indexarray		An array of indexes (treated like an integer array).
 	arrayi				An array of integers stored as a pointer.	
 	arrayd				An array of doubles stored as a pointer.
 	arraya				An array of arrays of integers.
@@ -35,7 +35,7 @@
 static double* ReadDblArray(FILE* file, int* length);
 static int* ReadIntArray(FILE* file, int* length);
 static void TrimWhitespace(char* string);
-
+static void Help(char* helpstring, Parameter* Param, int ParamCount);
 int ParseStructure(FILE *file, char* DataDescription, int** FilledMask, MemoryManager* Memory, ...)
 {
 	MemoryManager memory;
@@ -106,14 +106,21 @@
 		{
 			fgets(Line, 128, file);
 			LineStart = Line;
-			while (isspace(*LineStart) && *LineStart != '\0') LineStart++;			
-			printf("%s", LineStart);
+			TrimWhitespace(Line);
+			printf("%s\n", LineStart);
 		}
 		/*If it is a line comment read the remainder of the line and do nothing.*/
 		else if (! strcmp(Token, "rem"))
 		{
 			fgets(Line, 128, file);
 		}
+		/*If it is a request for help, read the rest of the line and show the help.*/
+		else if (! strcmp(Token, "help"))
+		{
+			fgets(Line, 128, file);
+			TrimWhitespace(Line);
+			Help(Line, Param, ParamCount);
+		}
 		/*Otherwise try to parse it as a user-defined token.*/
 		else
 		{
@@ -635,4 +642,154 @@
 		}
 	}
 	string[test + 1] = '\0';
-}
\ No newline at end of file
+}
+
+/*This is called when the user makes a help request.*/
+void Help(char* helpstring, Parameter* Param, int ParamCount)
+{
+	/*If the help string is empty or a null pointer, display the parameter help.*/
+	if ((! helpstring) || strlen(helpstring) == 0)
+	{
+		printf("This program uses the Structured IO routines. These routines allow a\n");
+		printf("test problem or other group of data to be entered in a human-readable\n");
+		printf("format. Data for each problem is entered as a series of keywords,\n");
+		printf("corresponding to variables used for the problem. Each keyword is followed\n");
+		printf("by the data that will fill that variable. There are also predefined\n");
+		printf("keywords that control the IO routines themselves.\n\n");
+		printf("Keywords and types used in this program are shown below. For information\n");
+		printf("about a specific data type, such as how to enter data of that type, enter\n");
+		printf("\"help typename\". For information about one of the predefined keywords,\n");
+		printf("enter \"help keyword\".\n");
+		printf("Predefined keywords: echo, rem, help, done, quit\n");
+		printf("Program-defined keywords:\n");
+		/*Print keywords and types.*/
+		int i;
+		char* typestring;
+		for (i = 0; i < ParamCount; i++)
+		{
+			if (! strcmp(Param[i].Type, "matrix")) typestring = "matrix";
+			if (! strcmp(Param[i].Type, "arrayi")) typestring = "integer array";
+			if (! strcmp(Param[i].Type, "arrayd")) typestring = "double array";
+			if (! strcmp(Param[i].Type, "arraya")) typestring = "array of arrays";
+			if (! strcmp(Param[i].Type, "indexarray")) typestring = "integer array";
+			if (! strcmp(Param[i].Type, "int")) typestring = "integer";
+			if (! strcmp(Param[i].Type, "double")) typestring = "double";
+			if (! strcmp(Param[i].Type, "string")) typestring = "string";
+			printf("\"%s\" of type \"%s\".\n", Param[i].Name, typestring);
+		}
+	}
+	else if (! strcmp(helpstring, "echo"))
+	{
+		printf("echo: Predefined keyword. Upon encountering an echo request, the program\n");
+		printf("reads the remainder of the line and prints it to the console output. Used\n");
+		printf("primarily with scripts.\n");
+	}
+	else if (! strcmp(helpstring, "rem"))
+	{
+		printf("rem: Predefined keyword. Any line beginning with the rem keyword is\n");
+		printf("ignored. Used for comments in scripts.\n");
+	}
+	else if (! strcmp(helpstring, "help"))
+	{
+		printf("help: Predefined keyword. The remainder of the line is read. If the line\n");
+		printf("is empty, displays the general help and list of keywords. If the line\n");
+		printf("contains a predefined keyword or a type name, help on that item is\n");
+		printf("displayed. Note there is no built-in help for program-defined keywords.\n");
+	}
+	else if (! strcmp(helpstring, "done"))
+	{
+		printf("done: Marks the end of a set of input data. The IO routines parse data\n");
+		printf("in sets, where each set is the data for a problem. When this keyword is\n");
+		printf("encountered, the IO routines return control to the main program so that\n");
+		printf("the data can be processed. Note that \"done\" must be used before any\n");
+		printf("data is processed. If the quit keyword or an error is encountered before\n");
+		printf("\"done\", none of that set of data will be processed.\n");
+	}
+	else if (! strcmp(helpstring, "quit"))
+	{
+		printf("quit: predefined kewyword. Marks the end of problems. The IO routines\n");
+		printf("return control to the main program and allow it to shut down when this\n");
+		printf("keyword is encountered. Note that any data that has not been marked for\n");
+		printf("processing via a \"done\" keyword at the time this keyword is encountered\n");
+		printf("will never be processed.\n");
+	}
+	else if (! strcmp(helpstring, "matrix"))
+	{
+		printf("matrix: data type. To enter data of type matrix, specify the keyword for the\n");
+		printf("data being entered, followed by the number of rows, followed by the number of\n");
+		printf("columns, followed by each element of the array.\n");
+		printf("All the values should be separated by whitespace (spaces, tabs, newlines, etc.)\n"); 
+		printf("The kind or amount of whitespace is irrelevant. This allows the user to enter\n");
+		printf("the data in a visually pleasing manner.\n");
+		printf("Example usage: Filling a matrix with keyword 'M' with a 3 x 3 identity:\n");
+		printf("M 3 3\n");
+		printf("1 0 0\n0 1 0\n0 0 1\n");
+	}
+	else if (! strcmp(helpstring, "integer array"))
+	{
+		printf("integer array: data type. An array of integers. To enter data, specify\n");
+		printf("the keyword for the data, followed by the number of elements in the\n");
+		printf("array, followed by each element of the array.\n");
+		printf("All the values should be separated by whitespace (spaces, tabs, newlines, etc.)\n"); 
+		printf("The kind or amount of whitespace is irrelevant. This allows the user to enter\n");
+		printf("the data in a visually pleasing manner.\n");
+		printf("Example usage: Filling an integer array with keyword 'A' with a sequence of 3:\n");
+		printf("A 3\n1 2 3\n");
+	}
+	else if (! strcmp(helpstring, "double array"))
+	{
+		printf("double array: data type. An array of doubles (floating-point or decimal\n");
+		printf("numbers. To enter, give the keyword followed by the number of elements in\n");
+		printf("the array followed by each element of the array.\n");
+		printf("All the values should be separated by whitespace (spaces, tabs, newlines, etc.)\n"); 
+		printf("The kind or amount of whitespace is irrelevant. This allows the user to enter\n");
+		printf("the data in a visually pleasing manner.\n");
+		printf("Example usage: Filling a double array with keyword 'A' with a sequence\n");
+		printf("of 4 elements counting by 0.25:\n");
+		printf("A 4\n0.25 0.5 0.75 1\n");
+	}
+	else if (! strcmp(helpstring, "array of arrays"))
+	{
+		printf("array of arrays: data type. An array each element of which is itself an\n");
+		printf("array. To enter, give the keyword followed by the number of arrays\n");
+		printf("followed by each array. Each array should be entered as the number of\n");
+		printf("elements in the array followed by the elements of the array. array of\n");
+		printf("arrays only accepts integral numbers, not floating-point (decimal).\n");
+		printf("All the values should be separated by whitespace (spaces, tabs, newlines, etc.)\n"); 
+		printf("The kind or amount of whitespace is irrelevant. This allows the user to enter\n");
+		printf("the data in a visually pleasing manner.\n");
+		printf("Example usage: Filling an array of arrays with keyword AROA with 3 arrays,\n");
+		printf("The first containing the elements [1, 2, 3], the second containing [4, 5],\n");
+		printf("and the third containing only one element, [6]:\n");
+		printf("AROA 3\n3 1 2 3\n2 4 5\n1 6\n");
+	}
+	else if (! strcmp(helpstring, "string"))
+	{
+		printf("string: data type. This is just a piece of text up to 127 characters long.\n");
+		printf("To enter, give the keyword followed by the text on the same line. The rest\n");
+		printf("of the line will be read, leading and trailing whitespace will be removed\n");
+		printf("and what is left is the text.\n");
+		printf("Example usage: Filling a string with keyword 's' with the text \"hello world\":\n");
+		printf("s hello world\n");
+	}
+	else if (! strcmp(helpstring, "integer"))
+	{
+		printf("integer: data type. A single integer. To enter, give the keyword followed by\n");
+		printf("the value.\n");
+		printf("Example usage: Filling an integer with keyword 'i' with the value 4:\n");
+		printf("i 4\n");
+	}
+	else if(! strcmp(helpstring, "double"))
+	{
+		printf("integer: data type. A single double (floating point or decimal number). To\n");
+		printf("enter, give the keyword followed by the value.\n");
+		printf("Example usage: Filling double with keyword 'd' with the value 3.14159:\n");
+		printf("d 3.14159\n");
+	}
+	else
+	{
+		printf("Unrecognized help request. Type \"help\" on a line by itself to see the\n");
+		printf("general help.\n");
+	}
+	printf("\n");
+}

Modified: spnbox/tests/StructuredIO.h
===================================================================
--- spnbox/tests/StructuredIO.h	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/StructuredIO.h	2009-07-14 21:32:17 UTC (rev 197)
@@ -2,6 +2,7 @@
 #define STRUCTUREDIO
 
 #include "../MemoryManager.h"
+
 int ParseStructure(FILE *file, char* DataDescription, int** FilledMask, MemoryManager* Memory, ...);
 /*ParseStructure fills the optional parameters with values read from file.
 Data types are described by the string DataDescription. If FilledMask is 
@@ -27,6 +28,7 @@
 			screen. This can be used for comments, problem numbers, and so forth.
 rem		rem is like echo except that no text is printed to the screen. Used for
 			comments.
+help	Displays a help message by calling ShowHelp.
 
 The syntax of DataDescription is as follows:
 TYPE NAME[,TYPE NAME...]

Modified: spnbox/tests/test-actn.c
===================================================================
--- spnbox/tests/test-actn.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-actn.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -13,7 +13,7 @@
 	char OutputDesc[] = "matrix Da, matrix Dma, matrix Dpa, matrix Dra, matrix Dmra, matrix Dpra, arrayi TA, int Unique";
 	
 	/*Get the input file.*/
-	if (! (input = GetInput(argc, argv))) return 0;	
+	if (! (input = ParseCmdLine(argc,argv))) return 0;	
 	
 	memory = CreateMemoryManager(10, 10, 0, 0);
 	while (ParseStructure(input, InputDesc, &InFilled, &memory, &D, &Dm, &Dp, &Dc, &Dcm, &Dcp, &X, &XCount, &update))

Modified: spnbox/tests/test-extendedmatrix.c
===================================================================
--- spnbox/tests/test-extendedmatrix.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-extendedmatrix.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -36,12 +36,6 @@
 int main(int argc, char* argv[])
 {
 	FILE* input;
-			
-	if (! (input = GetInput(argc, argv)))
-	{
-		return 1;
-	}
-	
 	char Desc[] = "string optimization, string operation, int mode, matrix A, matrix B, int row, int column, int rows, int columns, int repetitions, int size, string speedtest";
 	char Operation[128], optimization[128], speedtest[128];
 	matrix A, B;
@@ -49,6 +43,11 @@
 	int Mode, Row, Column, Rows, Columns, Reps, Size, Optimized, SpeedTest;
 	MemoryManager mem;
 	
+	if (! (input = ParseCmdLine(argc,argv)))
+	{
+		return 0;
+	}
+	
 	mem = CreateMemoryManager(5, 2, 0, 0);
 	SetDefaults(optimization, Operation, &Mode, &A, &B, &Row, &Column, &Rows, &Columns, &Reps, &Size, speedtest);
 	while (ParseStructure(input, Desc, &Filled, &mem, optimization, Operation, &Mode, &A, &B, &Row, &Column, &Rows, &Columns, &Reps, &Size))

Modified: spnbox/tests/test-ilpadm.c
===================================================================
--- spnbox/tests/test-ilpadm.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-ilpadm.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -21,9 +21,9 @@
   /*Set the verbosity level to maximum*/
 	setverbose(VRB_MAX);
 
-	if (! (input = GetInput(argc, argv)))
+	if (! (input = ParseCmdLine(argc, argv)))
 	{
-		return 1;
+		return 0;
 	}
 	
 	while (ParseStructure(input, InDesc, &InFilled, &mem, &D, &Tuc, &TucCount, &Tuo, &TuoCount, &L, &B, &BCount, &m0, &m0Count))

Modified: spnbox/tests/test-ipsolve.c
===================================================================
--- spnbox/tests/test-ipsolve.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-ipsolve.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -20,9 +20,9 @@
 	MemoryManager mem;
 	
 	/*Get the input file.*/
-	if (! (input = GetInput(argc, argv)))
+	if (! (input = ParseCmdLine(argc,argv)))
 	{
-		return 1;
+		return 0;
 	}
 	
 	mem = CreateMemoryManager(10, 10, 0, 0);

Modified: spnbox/tests/test-isadm.c
===================================================================
--- spnbox/tests/test-isadm.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-isadm.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -14,9 +14,9 @@
 	int bCount, m0Count, TucCount, TuoCount;
 	
 	/*Get a pointer to the input file.*/
-	if (! (input = GetInput(argc, argv)))
+	if (! (input = ParseCmdLine(argc,argv)))
 	{
-		return 1;
+		return 0;
 	}
 	
 	memory = CreateMemoryManager(5, 6, 0, 0);

Modified: spnbox/tests/test-issiph.c
===================================================================
--- spnbox/tests/test-issiph.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-issiph.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -14,9 +14,9 @@
 	matrix D, Dm, Dp, PlaceSet;
 	
 	/*Get a pointer to the input file.*/
-	if (! (input = GetInput(argc, argv)))
+	if (! (input = ParseCmdLine(argc,argv)))
 	{
-		return 1;
+		return 0;
 	}
 	
 	memory = CreateMemoryManager(5, 6, 0, 0);

Modified: spnbox/tests/test-linenf.c
===================================================================
--- spnbox/tests/test-linenf.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-linenf.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -18,9 +18,9 @@
 	int i, Constraints;
 	
 	/*Get the input file pointer.*/
-	if (! (input = GetInput(argc, argv)))
+	if (! (input = ParseCmdLine(argc,argv)))
 	{
-		return 1;
+		return 0;
 	}
 	memory = CreateMemoryManager(15, 15, 0, 0);
 	

Modified: spnbox/tests/test-matrixmath.c
===================================================================
--- spnbox/tests/test-matrixmath.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-matrixmath.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -26,9 +26,7 @@
 int main(int argc, char* argv[])
 {
 	FILE* input;
-			
-	input = GetInput(argc, argv);
-	
+		
 	char Desc[] = "string option, string operation, matrix A, matrix B, arrayi C, arrayi D, int row, int column";
 	char Operation[128], Option[128];
 	matrix A, B;
@@ -36,6 +34,7 @@
 	int CCount, DCount, Row, Column;
 	MemoryManager mem;
 	
+	if (! (input = ParseCmdLine(argc,argv))) return 0;
 	mem = CreateMemoryManager(5, 2, 0, 0);
 	
 	while (ParseStructure(input, Desc, &Filled, &mem, Option, Operation, &A, &B, &C, &CCount, &D, &DCount, &Row, &Column))

Modified: spnbox/tests/test-msplit.c
===================================================================
--- spnbox/tests/test-msplit.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-msplit.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -21,23 +21,7 @@
 	msplit_r Return;
 	
 	FILE* Input;
-	if (argc > 1)
-	{
-		if (Input = fopen(argv[1], "r"))
-		{
-			printf("Reading from file '%s'...\n", argv[1]);
-		}
-		else
-		{
-			printf("ERROR! Could not open file '%s' for read-only access.\n", argv[1]);
-			return 1;
-		}
-	}
-	else
-	{
-		Input = stdin;
-		printf("Reading from keyboard...\n");
-	}
+	if (! (Input = ParseCmdLine(argc,argv))) return 0;
 	
 	memory = CreateMemoryManager(10, 10, 0, 0);
 	

Modified: spnbox/tests/test-nltrans.c
===================================================================
--- spnbox/tests/test-nltrans.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-nltrans.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -9,23 +9,10 @@
 	MemoryManager mem;
 	nltrans_r solution;
 	
-	if (argc > 1)
+	if (! (input = ParseCmdLine(argc, argv)))
 	{
-		if (input = fopen(argv[1], "r"))
-		{
-			printf("Taking input from file '%s'...", argv[1]);
-		}
-		else
-		{
-			printf("Failed to open file '%s'! Terminating.", argv[1]);
-			return 1;
-		}
+		return 0;
 	}
-	else
-	{
-		input = stdin;
-		printf("Taking input from console...");
-	}
 	
 	mem = CreateMemoryManager(5, 5, 0, 0);
 	while (ParseStructure(input, "matrix D, arrayi URT", &Filled, &mem, &D, &URT, &urtCount))

Modified: spnbox/tests/test-pn2acpn.c
===================================================================
--- spnbox/tests/test-pn2acpn.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-pn2acpn.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -20,23 +20,10 @@
 	/*Get the input stream. If there was a command line argument, treat it as a 
 	filename and attempt to open it for read access, terminating on failure.
 	Otherwise set stdin as the input stream.*/
-	if (argc > 1)
+	if (! (input = ParseCmdLine(argc, argv)))
 	{
-		if (input = fopen(argv[1], "r"))
-		{
-			printf("Taking input from file '%s'...\n", argv[1]);
-		}
-		else
-		{
-			printf("Failed to open file '%s' for read access! Terminating.\n", argv[1]);
-			return 1;
-		}
+		return 0;
 	}
-	else
-	{
-		input = stdin;
-		printf("Taking input from console...\n");
-	}
 	
 	/*Initialize the memory manager. We don't know how many matrices and arrays
 	we'll need so just pick a nice round number as the initial address block size

Modified: spnbox/tests/test-pn2eacpn.c
===================================================================
--- spnbox/tests/test-pn2eacpn.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-pn2eacpn.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -21,23 +21,10 @@
 	/*Get the input stream. If there was a command line argument, treat it as a 
 	filename and attempt to open it for read access, terminating on failure.
 	Otherwise set stdin as the input stream.*/
-	if (argc > 1)
+	if (! (input = ParseCmdLine(argc, argv)))
 	{
-		if (input = fopen(argv[1], "r"))
-		{
-			printf("Taking input from file '%s'...\n", argv[1]);
-		}
-		else
-		{
-			printf("Failed to open file '%s' for read access! Terminating.\n", argv[1]);
-			return 1;
-		}
+		return 0;
 	}
-	else
-	{
-		input = stdin;
-		printf("Taking input from console...\n");
-	}
 	
 	/*Initialize the memory manager. We don't know how many matrices and arrays
 	we'll need so just pick a nice round number as the initial address block size

Modified: spnbox/tests/test-reduce.c
===================================================================
--- spnbox/tests/test-reduce.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-reduce.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -15,7 +15,10 @@
 	char OutputDesc[] = "matrix Lf, arrayi Bf, arrayi RowsKept, int How";
 	
 	/*Get the input file.*/
-	if (! (input = GetInput(argc, argv))) return 0;	
+	if (! (input = ParseCmdLine(argc, argv)))
+	{
+		return 0;
+	}
 	
 	memory = CreateMemoryManager(4, 1, 0, 0);
 	while (ParseStructure(input, InputDesc, &InFilled, &memory, &L, &B, &BCount))

Modified: spnbox/tests/test-supervis.c
===================================================================
--- spnbox/tests/test-supervis.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-supervis.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -13,9 +13,9 @@
 	matrix D, Dm, Dp, L, Df;
 		
 	/*Get the input file.*/
-	if (! (input = GetInput(argc, argv)))
+	if (! (input = ParseCmdLine(argc,argv)))
 	{
-		return 1;
+		return 0;
 	}
 	
 	mem = CreateMemoryManager(1, 5, 0, 0);

Modified: spnbox/tests/test-tactn.c
===================================================================
--- spnbox/tests/test-tactn.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test-tactn.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -13,7 +13,7 @@
 	char OutputDesc[] = "matrix Da, matrix Dma, matrix Dpa, matrix Dra, matrix Dmra, matrix Dpra, arrayi TA, int Unique";
 	
 	/*Get the input file.*/
-	if (! (input = GetInput(argc, argv))) return 0;	
+	if (! (input = ParseCmdLine(argc,argv))) return 0;	
 	
 	memory = CreateMemoryManager(10, 10, 0, 0);
 	while (ParseStructure(input, InputDesc, &InFilled, &memory, &D, &Dm, &Dp, &Dc, &Dcm, &Dcp, &ExcludeT, &ExcludeTCount, &IncludeT, &IncludeTCount))

Modified: spnbox/tests/test.c
===================================================================
--- spnbox/tests/test.c	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test.c	2009-07-14 21:32:17 UTC (rev 197)
@@ -14,7 +14,7 @@
 	verbose = vrb;
 }
 
-FILE* GetInput(int argc, char* argv[])
+FILE* ParseCmdLine(int argc, char* argv[])
 {
 	FILE* file;
 	if (argc > 1)
@@ -32,10 +32,11 @@
 	}
 	else
 	{
-		printf("Taking input from console...\n");
+		printf("Taking input from console. Type \"help\" to see a description of\n");
+		printf("the input format.\n");
 		return stdin;
 	}
-}
+}	
 
 int HasSelfLoops(matrix* Dm, matrix* Dp)
 {

Modified: spnbox/tests/test.h
===================================================================
--- spnbox/tests/test.h	2009-07-14 15:31:42 UTC (rev 196)
+++ spnbox/tests/test.h	2009-07-14 21:32:17 UTC (rev 197)
@@ -16,8 +16,10 @@
 in test.c*/
 void setverbose(int vrb);
 
-/*Get the file pointer that input will be taken from.*/
-FILE* GetInput(int argc, char* argv[]);
+/*If the command line argument is the word "help", show the program help. If
+the argument is a filename, open it for read and return a pointer. If there is
+no command line argument return a pointer to stdin.*/
+FILE* ParseCmdLine(int argc, char* argv[]);
 
 /*Determine if the given i/o matrices have self-loops.*/
 int HasSelfLoops(matrix* Dm, matrix* Dp);


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.