.TH g.parser 1grass "" "GRASS 6.4.4" "Grass User's Manual"
.SH NAME
\fI\fBg.parser\fR\fR - Provides full parser support for GRASS
scripts.
.SH SYNOPSIS
\fBg.parser help\fR
.br
\fBg.parser\fR [\-\fBs\fR] [-\fBt\fR] \fIfilename\fR [\fIargument\fR,...]
.SS Flags:
.IP "\fB\-t\fR" 4m
.br
Print strings for translation
.IP "\fB\-s\fR" 4m
.br
Write option values to standard output instead of reinvoking script
.PP
.SH DESCRIPTION
The \fIg.parser\fR 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.
.SH OPTIONS
Unless the \fB-s\fR 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 \fBinput\fR was defined in the script
header, the value will be available in variable \fBGIS_OPT_INPUT\fR
and the value of flag with key \fBf\fR will be available in variable
\fBGIS_FLAG_F\fR.
.PP
For flags, the value will be "1" if the flag was given, and "0" otherwise.
.PP
If the \fB-s\fR switch is used, the options and flags are written to
standard output in the form \fIopt_=\fR and
\fIflag_=\fR, preceded by the string
\fB@ARGS_PARSED@\fR. 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 \fB--html-description\fR. In this case, the data written by
\fIg.parser\fR to standard output should be copied to the script's standard output
verbatim.
.PP
Typical header definitions are as follows:
\fC
.DS
.br
#%module
.br
#% description: g.parser test script   
.br
#%end
.br
#%flag
.br
#% key: f
.br
#% description: A flag
.br
#%end
.br
#%option
.br
#% key: raster
.br
#% type: string
.br
#% gisprompt: old,cell,raster
.br
#% description: Raster input map
.br
#% required : yes
.br
#%end
.br
.DE
\fR
.SH NOTES
An option can be instructed to allow multiple inputs by adding the
following line:
\fC
.DS#% multiple : yes
.DE
\fR
.br
While this will only directly change the \fIUsage\fR section of the help
.br
screen, the option's environmental string may be easily parsed from within
.br
a script. For example, individual comma separated identities for an option 
.br
named "input" can be parsed with the following Bash shell code:
.br
.br
\fC
.DSIFS=,
.br
for opt in $GIS_OPT_INPUT ; do
.br
    ... "$opt"
.br
done
.br
.DE
\fR
.PP
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:
\fC
.DS#% guisection: tabname
.DE
\fR
.br
would put that option in a tab named \fItabname\fR.
.br
.br
.PP
.br
A "<tt>key_desc" field may be added to each option to specify the text that
.br
appears in the module's usage help section. For example:
.br
\fC
.DS#% key_desc: filename
.DE
\fR
.br
added to an \fBinput\fR option would create the usage summary
.br
<tt>[input=filename].
.br
.br
.PP
.br
If a script is run with \fB--o\fR, G_parser() will
.br
set <tt>GRASS_OVERWRITE=1, which has the same effect as passing
.br
\fB--o\fR to every module which is run from the script. Similarly, passing
.br
\fB--q\fR or \fB--v\fR will set <tt>GRASS_VERBOSE to 0 or 3 respectively,
.br
which has the same effect as passing \fB--q\fR or \fB--v\fR to every module which
.br
is run from the script.  Rather than checking whether \fB--o\fR, \fB--q\fR or \fB--v\fR
.br
were used, you should be checking <tt>GRASS_OVERWRITE and/or
.br
<tt>GRASS_VERBOSE instead. If those variables are set, the
.br
script should behave the same way regardless of whether they were set
.br
by \fB--o\fR, \fB--q\fR or \fB--v\fR being passed to the script or set by other means.
.br
.br
.SH AUTOMATED SCRIPT CREATION
.br
.br
The flag \fB--script\fR added to a GRASS command, generates shell
.br
output. To write out a \fIg.parser\fR boilerplate for easy
.br
prototyping of shell scripts, the flag \fB--script\fR can be added
.br
to any GRASS command. Example:
.br
.br
\fC
.DS
.br
v.in.db \-\-script
.br
.DE
\fR
.SH Help page template (HTML)
The flag \fB--html-description\fR added to a GRASS command
generates a related help page template in HTML. Example:
\fC
.DS
.br
v.in.db \-\-html-description
.br
.DE
\fR
.SH GUI window parser (XML)
The flag \fB--interface-description\fR added to a GRASS command
generates a related help page template in XML. Example:
\fC
.DS
.br
v.in.db \-\-interface-description
.br
.DE
\fR
.SH GUI window parser (Tcl/Tk)
The flag \fB--tcltk\fR added to a GRASS command generates Tcl/Tk
code suitable for building the GUI interface. Example:
\fC
.DS
.br
v.in.db \-\-tcltk
.br
.DE
\fR
.SH TRANSLATION
\fIg.parser\fR provides some support for translating the options of
scripts. If called with the \-t switch before the script filename like
this
\fC
.DS
.br
g.parser \-t somescriptfile
.br
.DE
\fR
\fIg.parser\fR 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.
.SH EXAMPLES
All examples below autogenerate the graphical user interface when invoked
without parameters of flags:
.PP
.SS Example code for SHELL
\fC
.DS
.br
#!/bin/sh
.br
.br
# g.parser demo script for shell programing
.br
.br
#%module
.br
#%  description: g.parser test script   
.br
#%end
.br
#%flag
.br
#%  key: f
.br
#%  description: A flag
.br
#%end
.br
#%option
.br
#% key: raster
.br
#% type: string
.br
#% gisprompt: old,cell,raster
.br
#% description: Raster input map
.br
#% required : yes
.br
#%end
.br
#%option
.br
#% key: vector
.br
#% type: string
.br
#% gisprompt: old,vector,vector
.br
#% description: Vector input map
.br
#% required : yes
.br
#%end
.br
#%option
.br
#% key: option1
.br
#% type: string
.br
#% description: An option
.br
#% required : no
.br
#%end
.br
.br
if [ \-z "$GISBASE" ] ; then
.br
    echo "You must be in GRASS GIS to run this program." 1>&2
.br
    exit 1
.br
fi
.br
.br
if [ "$1" != "@ARGS_PARSED@" ] ; then
.br
    exec g.parser "$0" "$@"
.br
fi
.br
.br
#### add your code below ####
.br
echo ""
.br
.br
if [ $GIS_FLAG_F \-eq 1 ] ; then
.br
    echo "Flag \-f set"
.br
else
.br
    echo "Flag \-f not set"
.br
fi
.br
.br
# test if parameter present:
.br
if [ \-n "$GIS_OPT_OPTION1" ] ; then
.br
    echo "Value of GIS_OPT_OPTION1: '$GIS_OPT_OPTION1'"
.br
fi
.br
.br
echo "Value of GIS_OPT_RASTER: '$GIS_OPT_RASTER'"
.br
echo "Value of GIS_OPT_VECTOR: '$GIS_OPT_VECTOR'"
.br
.br
.DE
\fR
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:
\fC
.DS
.br
test.sh \-\-help
.br
.br
Description:
.br
 g.parser test script (python)
.br
.br
Usage:
.br
 test.sh [\-f] raster=string vector=string [option1=string]
.br
   [\-\-verbose] [\-\-quiet]
.br
.br
Flags:
.br
  \-f   A flag
.br
 \-\-v   Verbose module output
.br
 \-\-q   Quiet module output
.br
.br
Parameters:
.br
   raster   Raster input map
.br
   vector   Vector input map
.br
  option1   An option
.br
.DE
\fR
.SS Example code for Python
\fC
.DS
.br
#!/usr/bin/env python
.br
.br
# g.parser demo script for python programing
.br
.br
#%module
.br
#%  description: g.parser test script (python)
.br
#%end
.br
#%flag
.br
#%  key: f
.br
#%  description: A flag
.br
#%end
.br
#%option
.br
#%  key: raster
.br
#%  type: string
.br
#%  gisprompt: old,cell,raster
.br
#%  description: Raster input map
.br
#%  required : yes
.br
#%end
.br
#%option
.br
#%  key: vector
.br
#%  type: string
.br
#%  gisprompt: old,vector,vector
.br
#%  description: Vector input map
.br
#%  required : yes
.br
#%end
.br
#%option
.br
#%  key: option1
.br
#%  type: string
.br
#%  description: An option
.br
#%  required : no
.br
#%end
.br
.br
import os
.br
import sys
.br
.br
import grass.script as grass
.br
.br
def main():
.br
    flag_f = flags['f']
.br
    option1 = options['option1']
.br
    raster = options['raster']
.br
    vector = options['vector']
.br
.br
    #### add your code here ####
.br
.br
    if flag_f:
.br
        print "Flag \-f set"
.br
    else:
.br
        print "Flag \-f not set"
.br
.br
    # test if parameter present:
.br
    if option1:
.br
        print "Value of option1 option: '%s'" % option1
.br
.br
    print "Value of raster option: '%s'" % raster
.br
    print "Value of vector option: '%s'" % vector
.br
.br
    #### end of your code ####
.br
.br
    return 0
.br
.br
if __name__ == "__main__":
.br
    options, flags = grass.parser()
.br
    main()
.br
.DE
\fR
The test.py script will provide a GUI (as above) and the
following usage help text:
\fC
.DS
.br
./test.py \-\-help
.br
.br
Description:
.br
 g.parser test script (python)
.br
.br
Usage:
.br
 test1.py [\-f] raster=string vector=string [option1=string]
.br
   [\-\-verbose] [\-\-quiet]
.br
.br
Flags:
.br
  \-f   A flag
.br
 \-\-v   Verbose module output
.br
 \-\-q   Quiet module output
.br
.br
Parameters:
.br
   raster   Raster input map
.br
   vector   Vector input map
.br
  option1   An option
.br
.DE
\fR
.SS Example code for Perl
\fC
.DS
.br
#!/usr/bin/perl \-w
.br
use strict;
.br
.br
# g.parser demo script
.br
.br
#%module
.br
#%  description: g.parser test script (perl) 
.br
#%  keywords: keyword1, keyword2
.br
#%end
.br
#%flag
.br
#%  key: f
.br
#%  description: A flag
.br
#%end
.br
#%option
.br
#% key: raster
.br
#% type: string
.br
#% gisprompt: old,cell,raster
.br
#% description: Raster input map
.br
#% required : yes
.br
#%end
.br
#%option
.br
#% key: vector
.br
#% type: string
.br
#% gisprompt: old,vector,vector
.br
#% description: Vector input map
.br
#% required : yes
.br
#%end
.br
#%option
.br
#% key: option1
.br
#% type: string
.br
#% description: An option
.br
#% required : no
.br
#%end
.br
.br
if ( !$ENV{'GISBASE'} ) {
.br
    printf(STDERR  "You must be in GRASS GIS to run this program.\(rsn");
.br
    exit 1;
.br
}
.br
.br
if( $ARGV[0] ne '@ARGS_PARSED@' ){
.br
    my $arg = "";
.br
    for (my $i=0; $i < @ARGV;$i++) {
.br
        $arg .= " $ARGV[$i] ";
.br
    }
.br
    system("$ENV{GISBASE}/bin/g.parser $0 $arg");
.br
    exit;
.br
}
.br
.br
#### add your code here ####
.br
print  "\(rsn";
.br
if ( $ENV{'GIS_FLAG_F'} eq "1" ){
.br
   print "Flag \-f set\(rsn"
.br
}
.br
else {
.br
   print "Flag \-f not set\(rsn"
.br
}
.br
.br
printf ("Value of GIS_OPT_option1: '%s'\(rsn", $ENV{'GIS_OPT_OPTION1'});
.br
printf ("Value of GIS_OPT_raster: '%s'\(rsn", $ENV{'GIS_OPT_RASTER'});
.br
printf ("Value of GIS_OPT_vect: '%s'\(rsn", $ENV{'GIS_OPT_VECTOR'});
.br
.br
#### end of your code ####
.br
.br
.DE
\fR
The test.pl script will provide a GUI and usage help text similar
to the other examples above.
.SH SEE ALSO
\fI
d.ask,
d.menu,
g.ask,
g.filename,
g.findfile,
g.tempfile
\fR
and SUBMITTING_PYTHON
file in the GRASS source code.
.PP
Related Wiki pages:
Using GRASS with other programming languages
.SH AUTHOR
Glynn Clements
.PP
\fILast changed: $Date: 2014-01-25 20:03:32 +0100 (Sat, 25 Jan 2014) $\fR
.PP
Full index
.PP
© 2003-2014 GRASS Development Team