NAME¶
g.parser - Provides full parser support for GRASS scripts.
SYNOPSIS¶
g.parser help
g.parser [-
s] [-
t]
filename [
argument,...]
Flags:¶
- -t
-
Print strings for translation
- -s
-
Write option values to standard output instead of reinvoking script
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¶
Unless the
-s switch is used, the arguments are stored in environment
variables for use in your scripts. These variables are named
"GIS_FLAG_" for flags and "GIS_OPT_" 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.
If the
-s switch is used, the options and flags are written to standard
output in the form
opt_= and
flag_=, preceded by the string
@ARGS_PARSED@. If this string doesn't appear as the first line of
standard output, it indicates that the script was invoked with a switch such
as
--html-description. In this case, the data written by
g.parser to standard output should be copied to the script's standard
output verbatim.
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:
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:
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:
would put that option in a tab named
tabname.
A "<tt>key_desc" field may be added to each option to specify
the text that
appears in the module's usage help section. For example:
added to an
input option would create the usage summary
<tt>[input=filename].
If a script is run with
--o, G_parser() will
set <tt>GRASS_OVERWRITE=1, which has the same effect as passing
--o to every module which is run from the script. Similarly, passing
--q or
--v will set <tt>GRASS_VERBOSE to 0 or 3
respectively,
which has the same effect as passing
--q or
--v to every module
which
is run from the script. Rather than checking whether
--o,
--q or
--v
were used, you should be checking <tt>GRASS_OVERWRITE and/or
<tt>GRASS_VERBOSE instead. If those variables are set, the
script should behave the same way regardless of whether they were set
by
--o,
--q or
--v being passed to the script or set by
other means.
AUTOMATED SCRIPT CREATION¶
The flag
--script added to a GRASS command, generates shell
output. To write out a
g.parser boilerplate for easy
prototyping of shell scripts, the flag
--script can be added
to any GRASS command. Example:
v.in.db --script
Help page template (HTML)¶
The flag
--html-description added to a GRASS command generates a related
help page template in HTML. Example:
v.in.db --html-description
GUI window parser (XML)¶
The flag
--interface-description added to a GRASS command generates a
related help page template in XML. Example:
v.in.db --interface-description
GUI window parser (Tcl/Tk)¶
The flag
--tcltk added to a GRASS command generates Tcl/Tk code suitable
for building the GUI interface. Example:
v.in.db --tcltk
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 standard
output, one per line, and exit. This is for internal use within the build
system to prepare GRASS scripts for translation.
EXAMPLES¶
All examples below autogenerate the graphical user interface when invoked
without parameters of flags:
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 below ####
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'"
To run properly, the script needs to be copied into $GISBASE/scripts/ with the
executable flag being set. The script will provide a GUI (as above) and the
following usage help text:
test.sh --help
Description:
g.parser test script (python)
Usage:
test.sh [-f] raster=string vector=string [option1=string]
[--verbose] [--quiet]
Flags:
-f A flag
--v Verbose module output
--q Quiet module output
Parameters:
raster Raster input map
vector Vector input map
option1 An option
Example code for Python¶
#!/usr/bin/env python
# g.parser demo script for python programing
#%module
#% description: g.parser test script (python)
#%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
import os
import sys
import grass.script as grass
def main():
flag_f = flags['f']
option1 = options['option1']
raster = options['raster']
vector = options['vector']
#### add your code here ####
if flag_f:
print "Flag -f set"
else:
print "Flag -f not set"
# test if parameter present:
if option1:
print "Value of option1 option: '%s'" % option1
print "Value of raster option: '%s'" % raster
print "Value of vector option: '%s'" % vector
#### end of your code ####
return 0
if __name__ == "__main__":
options, flags = grass.parser()
main()
The test.py script will provide a GUI (as above) and the following usage help
text:
Description:
g.parser test script (python)
Usage:
test1.py [-f] raster=string vector=string [option1=string]
[--verbose] [--quiet]
Flags:
-f A flag
--v Verbose module output
--q Quiet module output
Parameters:
raster Raster input map
vector Vector input map
option1 An option
Example code for Perl¶
#!/usr/bin/perl -w
use strict;
# g.parser demo script
#%module
#% description: g.parser test script (perl)
#% keywords: keyword1, keyword2
#%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 ( !$ENV{'GISBASE'} ) {
printf(STDERR "You must be in GRASS GIS to run this program.\n");
exit 1;
}
if( $ARGV[0] ne '@ARGS_PARSED@' ){
my $arg = "";
for (my $i=0; $i < @ARGV;$i++) {
$arg .= " $ARGV[$i] ";
}
system("$ENV{GISBASE}/bin/g.parser $0 $arg");
exit;
}
#### add your code here ####
print "\n";
if ( $ENV{'GIS_FLAG_F'} eq "1" ){
print "Flag -f set\n"
}
else {
print "Flag -f not set\n"
}
printf ("Value of GIS_OPT_option1: '%s'\n", $ENV{'GIS_OPT_OPTION1'});
printf ("Value of GIS_OPT_raster: '%s'\n", $ENV{'GIS_OPT_RASTER'});
printf ("Value of GIS_OPT_vect: '%s'\n", $ENV{'GIS_OPT_VECTOR'});
#### end of your code ####
The test.pl script will provide a GUI and usage help text similar to the other
examples above.
SEE ALSO¶
d.ask, d.menu, g.ask, g.filename,
g.findfile, g.tempfile and SUBMITTING_PYTHON file in the
GRASS source code.
Related Wiki pages: Using GRASS with other programming languages
AUTHOR¶
Glynn Clements
Last changed: $Date: 2014-01-25 20:03:32 +0100 (Sat, 25 Jan 2014) $
Full index
© 2003-2014 GRASS Development Team