GRASS logo

NAME

g.parser

DESCRIPTION

The g.parser module provides full parser support for GRASS scripts, including an auto-generated GUI interface, help page template, and command line option checking. In this way a simple script can very quickly be made into a full-fledged GRASS module.

OPTIONS

After parsing the arguments are stored in environment variables for use in your scripts. These variables are named "GIS_FLAG_<NAME>" for flags and "GIS_OPT_<NAME>" for options. The names of variables are converted to upper case. For example if an option with key input was defined in the script header, the value will be available in variable GIS_OPT_INPUT and the value of flag with key f will be available in variable GIS_FLAG_F.

For flags, the value will be "1" if the flag was given, and "0" otherwise.

Typical header definitions are as follows: 

#%Module
#%  description: g.parser test script
#%End
#%flag
#%  key: f
#%  description: A flag
#%end
#%option
#%  key: raster
#%  type: string
#%  gisprompt: old,cell,raster
#%  description: Raster input map
#%  required : yes
#%end

NOTES

An option can be instructed to allow multiple inputs by adding the following line: 
#% multiple : yes
While this will only directly change the Usage section of the help screen, the option's environmental string may be easily parsed from within a script. For example, individual comma separated identities for an option named "input" can be parsed with the following Bash shell code: 
IFS=,
for opt in $GIS_OPT_INPUT ; do
    ... "$opt"
done

A "guisection" field may be added to each option and flag to specify that the options should appear in multiple tabs in the auto-generated GUI. Any options without a guisection field go into the "Options" tab. For example: 

#% guisection: tabname
would put that option in a tab named tabname.

A "key_desc" field may be added to each option to specify the text that appears in the module's usage help section. For example: 

#% key_desc: filename
added to an input option would create the usage summary [input=filename].

TRANSLATION

g.parser provides some support for translating the options of scripts. If called with the -t switch before the script filename like this 
g.parser -t somescriptfile
g.parser will print the text of the translatable options to stdout, one per line, and exit. This is for internal use within the build system to prepare GRASS scripts for translation.

EXAMPLES

Example code for SHELL

#!/bin/sh

# g.parser demo script for shell programing

#%Module
#%  description: g.parser test script   
#%End
#%flag
#%  key: f
#%  description: A flag
#%END
#%option
#% key: raster
#% type: string
#% gisprompt: old,cell,raster
#% description: Raster input map
#% required : yes
#%end
#%option
#% key: vector
#% type: string
#% gisprompt: old,vector,vector
#% description: Vector input map
#% required : yes
#%end
#%option
#% key: option1
#% type: string
#% description: An option
#% required : no
#%end

if [ -z "$GISBASE" ] ; then
    echo "You must be in GRASS GIS to run this program." 1>&2
    exit 1
fi

if [ "$1" != "@ARGS_PARSED@" ] ; then
  exec g.parser "$0" "$@"
fi

#add your code here
echo ""
if [ $GIS_FLAG_F -eq 1 ] ; then
  echo "Flag -f set"
else
  echo "Flag -f not set"
fi

#test if parameter present:
if [ -n "$GIS_OPT_OPTION1" ] ; then
  echo "Value of GIS_OPT_OPTION1: '$GIS_OPT_OPTION1'"
fi

echo "Value of GIS_OPT_RASTER: '$GIS_OPT_RASTER'"
echo "Value of GIS_OPT_VECTOR: '$GIS_OPT_VECTOR'"

#add your code here

The test.sh script will provide following help text: 

./test.sh --help

Description:
 g.parser test script
 
Usage:
 test.sh [-f] option=name
 
Flags:
  -f   A flag
 
Parameters:
  option   an option

SEE ALSO

d.ask, d.menu, g.ask, g.filename, g.findfile, g.tempfile, and the SUBMITTING_SCRIPTS file in the GRASS source code.

AUTHOR

Glynn Clements

Last changed: $Date$