[GRASS5] proposal for a grass command interface description for automatic GUI building

[Jan-Oliver Wagner]

Dear GRASS developers,

I am developing a bridge between GRASS commands and OSSIM together with
Frank Warmerdam and Bernhard Reiter.

I am currently working on GRASS forms descriptions that 
define command options and arguments of GRASS commands
with associated information. These forms can be used
to automatically build simple GUIs for entering values
and launching the GRASS commands.

My main ideas for the way to go are

	* GRASS programs can be asked for the parameter description
	* parameter description is based on XML. 




Why XML?

I don't like the idea to develop just another text based format
for a specific task. A simple XML approach will do it as well
and opens up further opportunities.

We don't need a comprehensive XML parser in a first approach.
Producing XML is easy. Writing simple parsers should be of reasonable effort.
So linking against a xml library is not required though IMO any
large software package will do this sooner or later at least for some
import/export functionality.

One idea I like very much:
There are several projects starting to describe user interfaces based
on XML. So, if we have a parameter description based on xml, a simple
xsl transform can be developed and would lead to nice dialogs for any
widget toolkits (static or on the fly!).





Thats the future. What can we achieve right now?

With the Option and Key structures we have a base to produce the forms.
I have modified parser.c to accept a special parameter for generating
xml specification:

GRASS:~ > r.basins.fill --task-description
<task name="r.basins.fill">
	<parameter-group>
		<parameter name="number" type="integer" required="yes">
			<description>
				Number of passes through the dataset
			</description>
		</parameter>
		<parameter name="c_map" type="string" required="yes">
			<description>
				Coded stream network file name
			</description>
		</parameter>
		<parameter name="t_map" type="string" required="yes">
			<description>
				Thinned ridge network file name
			</description>
		</parameter>
		<parameter name="result" type="string" required="yes">
			<description>
				Name for the resultant watershed partition file
			</description>
		</parameter>
	</parameter-group>
</task>

Option lists are not implemented yet. I am thinking on a tag
(of <parameter>) as such:
<values>
	<value>option 1</value>
	<value>option 2</value>
</values>
or
<values>
	<range min="0.5" max="1.5"/>
	<range min="2.5" max="3.5"/>
</values>

Already implemented is:
<default>
	3.4
</default>

What would also be nice for <task> is:
<version>1.12</version>
and
<authors>
	<author>Gary Grassdeveloper</author>
</authors>

So there are many ideas ... :-)




What do you think about this approach? Comments?
Have I missed something?

The plans for the GRASS bridge to OSSIM include a parsing of the
GRASS command forms for wxWindows. It should be fairly easy for 
tcltkgrass as well since there is already a parser currently based
on tcl list structure.

Attached is my patch for parser.c.

Cheers

	Jan
-- 
Jan-Oliver Wagner               http://intevation.de/~jan/

Intevation GmbH	              	     http://intevation.de/
FreeGIS	                               http://freegis.org/
-------------- next part --------------
Index: parser.c
===================================================================
RCS file: /grassrepository/grass/src/libes/gis/parser.c,v
retrieving revision 1.1.1.1
diff -r1.1.1.1 parser.c
306a307,314
> 		/* If first arg is "--task-description" then print out
> 		 * a xml description of the task */
> 		if (strcmp(argv[1],"--task-description") == 0)
> 		{
> 			G_usage_xml();
> 			return -1;
> 		}
> 
473a482,569
> }
> 
> int G_usage_xml (void)
> {
> 	struct Option *opt ;
> 	struct Flag *flag ;
> 	char *type;
> 
> 	if (!pgm_name)		/* v.dave && r.michael */
> 	    pgm_name = G_program_name ();
> 	if (!pgm_name)
> 	    pgm_name = "??";
> 
> 	fprintf(stdout, "<task name=\"%s\">\n", pgm_name);  
> 
> 	fprintf(stdout, "\t<parameter-group>\n");
> 	if(n_opts)
> 	{
> 		opt= &first_option;
> 		while(opt != NULL)
> 		{
> 			/* TODO: make this a enumeration type? */
> 			switch (opt->type) {
> 				case TYPE_INTEGER:
> 					type = "integer";
> 					break ;
> 				case TYPE_DOUBLE:
> 					type = "float";
> 					break ;
> 				case TYPE_STRING:
> 					type = "string";
> 					break ;
> 				default:
> 					type = "unknown";
> 					break;
> 			}
> 			fprintf (stdout, "\t\t<parameter "
> 				"name=\"%s\" "
> 				"type=\"%s\" "
> 				"required=\"%s\">\n",
> 				opt->key,
> 				type,
> 				opt->required == YES ? "yes" : "no");
> 
> 			if (opt->description)
> 				fprintf(stdout, "\t\t\t<description>\n\t\t\t\t%s\n\t\t\t</description>\n",
> 					opt->description);
> 			if(opt->def)
> 				fprintf(stdout, "\t\t\t<default>\n\t\t\t\t%s\n\t\t\t</default>\n", opt->def);
> 
> 			if(opt->options)
> 				fprintf(stdout, "\t\t\t<values>\n\t\t\t\t%s\n\t\t\t</values>\n", opt->options);
> 
> 			/* TODO:
> 			 * - options needs to be refined, roughly this way:
> 			 * 	<values>
> 			 * 	 <value>xxx</value>
> 			 * 	 <range min="xxx" max="xxx"/>
> 			 * 	</values>
> 			 * - multiple
> 			 * - there surely are some more. which ones?
> 			 */
> 
> 			opt = opt->next_opt ;
> 			fprintf (stdout, "\t\t</parameter>\n");
> 		}
> 	}
> 
> 	
> 	if(n_flags)
> 	{
> 		flag= &first_flag;
> 		while(flag != NULL)
> 		{
> 			fprintf (stdout, "\t\t<parameter name=\"%c\" type=\"flag\">\n", flag->key);
> 
> 			if (flag->description)
> 				fprintf(stdout, "\t\t\t<description>\n\t\t\t\t%s\n\t\t\t</description>\n",
> 							flag->description);
> 			flag = flag->next_flag ;
> 			fprintf (stdout, "\t\t</parameter>\n");
> 		}
> 	}
> 
> 	fprintf(stdout, "\t</parameter-group>\n");
> 
> 	fprintf(stdout, "</task>\n");
>     return 0;