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 backwards compatibility reasons, the header definitions can use
#%
instead of # %
as in
#% multiple: yes
. However, Python code should use
# %
in order to conform to PEP8.
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 gs 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 = gs.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 gs def main(): # put code here return 0 if __name__ == "__main__": options, flags = gs.parser() sys.exit(main())
Overview table: Parser standard options
Style Guide: Developing Python scripts
Related Wiki pages: Using GRASS GIS with other programming languages
Available at: g.parser source code (history)
Latest change: Wednesday Sep 18 00:50:13 2024 in commit: 973fcfbfc9388775eccb850dc5e1a420d05d467a
Main index | General index | Topics index | Keywords index | Graphical index | Full index
© 2003-2024 GRASS Development Team, GRASS GIS 8.4.1dev Reference Manual