For flags, the value will be "1" if the flag was given, and "0" otherwise.
If the -s or -n switch is used, the options and flags are written to standard output in the form opt_<name>=<value> and flag_<name>=<value>, 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. If the -s switch is used, the options and flags are separated by newlines. If the -n switch is used, the options and flags are separated by null characters.
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
The parsers allows using predefined standardized options and flags, see the list of options and flags in the programmer manual. Eg. the option
#%option #% key: raster #% type: string #% gisprompt: old,cell,raster #% description: Raster input map #% required: yes #%end
#%option G_OPT_R_MAP #% key: raster #%end
#%rules #% exclusive: capfile_output, capfile #%end
#%rules #% required: raster, vector #%end
#%rules #% required: -i,-d,-c #%end
#% multiple: yes
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 "Required" or "Options" tab. For example:
#% guisection: 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
If a script is run with --o, the parser will set 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 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 GRASS_OVERWRITE and/or 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.
For C, the relevant functions are those in lib/gis/parser_dependencies.c.
For scripts, relationships are specified using a "rules" section, e.g.
#%rules #% required: altitude,elevation #%end
v.in.db --script
v.in.db --html-description
v.in.db --interface-description
v.in.db driver=sqlite database=mysqlite.db table=pointsfile x=x y=y z=z key=idcol out=dtmpoints --json
{
"module": "v.in.db",
"id": "v.in.db_1804289383",
"inputs":[
{"param": "table", "value": "pointsfile"},
{"param": "driver", "value": "sqlite"},
{"param": "database", "value": "mysqlite.db"},
{"param": "x", "value": "x"},
{"param": "y", "value": "y"},
{"param": "z", "value": "z"},
{"param": "key", "value": "idcol"}
],
"outputs":[
{"param": "output", "value": "dtmpoints"}
]
}
v.in.db --wps-process-description
v.in.db --rst-description
g.parser -t somescriptfile
To run properly, the script needs to be copied into a directory listed in $GRASS_ADDON_PATH environmental variable with the executable flag being set.
The script will provide a GUI (as above) and the following usage help text:
test.py|sh|pl --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
#!/usr/bin/env python3
# g.parser demo script for python programming
#%module
#% description: g.parser test script (python)
#% keyword: keyword1
#% keyword: keyword2
#%end
#%flag
#% key: f
#% description: A flag
#%end
#%option G_OPT_R_MAP
#% key: raster
#% required: yes
#%end
#%option G_OPT_V_MAP
#% key: vector
#%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()
sys.exit(main())
#!/bin/sh
# g.parser demo script for shell programming
#%module
#% description: g.parser test script (shell)
#%end
#%flag
#% key: f
#% description: A flag
#%end
#%option G_OPT_R_MAP
#% key: raster
#% required: yes
#%end
#%option G_OPT_V_MAP
#% key: vector
#%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
g.message message="Flag -f set"
else
g.message message="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
g.message message="Value of GIS_OPT_option1: '$GIS_OPT_option1'"
g.message message="Value of GIS_OPT_raster: '$GIS_OPT_raster'"
g.message message="Value of GIS_OPT_vect: '$GIS_OPT_vector'"
#### end of your code ####
#!/usr/bin/perl -w
use strict;
# g.parser demo script
#%module
#% description: g.parser test script (perl)
#% keyword: keyword1
#% keyword: keyword2
#%end
#%flag
#% key: f
#% description: A flag
#%end
#%option G_OPT_R_MAP
#% key: raster
#% required: yes
#%end
#%option G_OPT_V_MAP
#% key: vector
#%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 ####
In this example, the module v.what.rast is used as an example. The output is shown below:
v.what.rast --script
#!/usr/bin/env python3
############################################################################
#
# MODULE: v.what.rast_wrapper
# AUTHOR(S): username
# PURPOSE: Wrapper for v.what.rast
# COPYRIGHT: (C) 2017 by username, and the GRASS Development Team
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
############################################################################
#%module
#% description: Uploads raster values at positions of vector points to the table.
#% keyword: vector, sampling, raster, position, querying, attribute table, surface information
#%end
#%flag
#% key: i
#% description: Interpolate values from the nearest four cells
#%end
#%flag
#% key: p
#% description: Print categories and values instead of updating the database
#%end
#%option
#% key: map
#% type: string
#% required: yes
#% multiple: no
#% key_desc: name
#% label: Name of vector points map for which to edit attributes
#% description: Or data source for direct OGR access
#% gisprompt: old,vector,vector
#%end
#%option
#% key: layer
#% type: string
#% required: no
#% multiple: no
#% label: Layer number or name
#% description: Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
#% answer: 1
#% gisprompt: old,layer,layer
#%end
#%option
#% key: type
#% type: string
#% required: no
#% multiple: yes
#% options: point,centroid
#% description: Input feature type
#% answer: point
#%end
#%option
#% key: raster
#% type: string
#% required: yes
#% multiple: no
#% key_desc: name
#% description: Name of existing raster map to be queried
#% gisprompt: old,cell,raster
#%end
#%option
#% key: column
#% type: string
#% required: no
#% multiple: no
#% key_desc: name
#% description: Name of attribute column to be updated with the query result
#% gisprompt: old,dbcolumn,dbcolumn
#%end
#%option
#% key: where
#% type: string
#% required: no
#% multiple: no
#% key_desc: sql_query
#% label: WHERE conditions of SQL statement without 'where' keyword
#% description: Example: income < 1000 and population >= 10000
#%end
import sys
import grass.script as grass
def main():
# put code here
return 0
if __name__ == "__main__":
options, flags = grass.parser()
sys.exit(main())
Overview table: Parser standard options
Related Wiki pages: Using GRASS GIS with other programming languages
Available at: g.parser source code (history)
Accessed: Thursday Jun 12 04:29:03 2025
Main index | General index | Topics index | Keywords index | Graphical index | Full index
© 2003-2023 GRASS Development Team, GRASS GIS 7.8.8 Reference Manual