g.parser - Provides full parser support for GRASS scripts.
general, support, scripts
g.parser --help g.parser [-s] [-t] [-n] filename [argument,...] Flags: -t Print strings for translation -s Write option values to standard output instead of reinvoking script -n Write option values to standard output separated by null character
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.
Unless the -s or -n switch is used, 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. 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 With {NULL} it is possible to suppress a predefined description or label. 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 can be easily defined as #%option G_OPT_R_MAP #% key: raster #%end The parser allows defining predefined rules for used options. The syntax of the rules section is following: #%rules #% exclusive: capfile_output, capfile #%end The parser also allows defining "OR" conditions, e.g. requiring raster OR vector (for details, see below), e.g.for options: #%rules #% required: raster, vector #%end and e.g., for flags: #%rules #% required: -i,-d,-c #%end
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 "Required" or "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]. 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.
Marking an option as "required" will result in the parser raising a fatal error if the option is not given, with one exception: if a flag has the suppress_required option, and that flag is given, all requirements are ignored. This feature is intended for flags which abandon "normal operation" for the module; e.g. r.in.gdal's -f flag (list supported formats) uses it. But in general, an option cannot be marked as required if it is optional except for the special case of a suppress_required flag. The parser has the ability to specify option relationships. 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 specifies that at least one of those options must be given. Both options and flags can be specified (a leading "-" denotes a flag). The available rule types are: * exclusive: at most one of the options may be given * required: at least one of the options must be given * requires: if the first option is given, at least one of the subsequent options must also be given * requires_all: if the first option is given, all of the subsequent options must also be given * excludes: if the first option is given, none of the subsequent options may be given * collective: all or nothing; if any option is given, all must be given
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
The flag --html-description added to a GRASS command generates a related help page template in HTML. Example: v.in.db --html-description
The flag --interface-description added to a GRASS command generates a related help page template in XML. Example: v.in.db --interface-description
The flag --wps-process-description added to a GRASS command generates a Web Processing Service process description. Example: v.in.db --wps-process-description
The flag --rst-description added to a GRASS command generates module interface description in reStructuredText, a lightweight markup language. Example: v.in.db --rst-description reStructuredText is sometimes abbreviated as reST, ReST, or RST. The commonly used file extension is .rst. Don't be confused with Representational State Transfer (REST) technology.
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.
All examples below autogenerate the graphical user interface when invoked without parameters of flags: 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 Example code for Python #!/usr/bin/env python # 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()) Example code for SHELL #!/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 #### Example code for Perl #!/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 ####
g.filename, g.findfile, g.tempfile Overview table: Parser standard options Submitting rules for Python Related Wiki pages: Using GRASS GIS with other programming languages
Glynn Clements Last changed: $Date: 2016-09-19 12:21:19 +0200 (Mon, 19 Sep 2016) $
Available at: g.parser source code (history) Main index | General index | Topics index | Keywords index | Graphical index | Full index 2003-2016 GRASS Development Team, GRASS GIS 7.2.0 Reference Manual
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.