1g.parser(1)                 GRASS GIS User's Manual                g.parser(1)
2
3
4

NAME

6       g.parser - Provides full parser support for GRASS scripts.
7

KEYWORDS

9       general, support, scripts
10

SYNOPSIS

12       g.parser --help
13       g.parser [-s] [-t]  [-n] filename [argument,...]
14
15   Flags:
16       -t
17           Print strings for translation
18
19       -s
20           Write option values to standard output instead of reinvoking script
21
22       -n
23           Write option values to standard output separated by null character
24

DESCRIPTION

26       The  g.parser  module  provides  full parser support for GRASS scripts,
27       including an auto-generated GUI interface, help page template, and com‐
28       mand line option checking. In this way a simple script can very quickly
29       be made into a full-fledged GRASS module.
30

OPTIONS

32       Unless the -s or -n switch is used, the arguments are stored  in  envi‐
33       ronment  variables  for  use in your scripts. These variables are named
34       "GIS_FLAG_<NAME>" for flags and "GIS_OPT_<NAME>" for options. The names
35       of variables are converted to upper case. For example if an option with
36       key input was defined in the script header, the value will be available
37       in  variable  GIS_OPT_INPUT  and  the  value of flag with key f will be
38       available in variable GIS_FLAG_F.
39
40       For flags, the value will be "1" if the flag was given, and "0"  other‐
41       wise.
42
43       If  the  -s  or -n switch is used, the options and flags are written to
44       standard output in the form opt_<name>=<value> and flag_<name>=<value>,
45       preceded  by the string @ARGS_PARSED@. If this string doesn’t appear as
46       the first line of standard output, it indicates  that  the  script  was
47       invoked  with  a  switch  such as --html-description. In this case, the
48       data written by g.parser to standard output should  be  copied  to  the
49       script’s  standard  output  verbatim.   If  the  -s switch is used, the
50       options and flags are separated by newlines. If the -n switch is  used,
51       the options and flags are separated by null characters.
52
53       Typical header definitions are as follows:
54       #%module
55       #% description: g.parser test script
56       #%end
57       #%flag
58       #% key: f
59       #% description: A flag
60       #%end
61       #%option
62       #% key: raster
63       #% type: string
64       #% gisprompt: old,cell,raster
65       #% description: Raster input map
66       #% required: yes
67       #%end
68       With  {NULL}  it  is  possible  to suppress a predefined description or
69       label.
70
71       The parsers allows using predefined standardized options and flags, see
72       the list of options and flags in the programmer manual. Eg. the option
73       #%option
74       #% key: raster
75       #% type: string
76       #% gisprompt: old,cell,raster
77       #% description: Raster input map
78       #% required: yes
79       #%end
80       can be easily defined as
81       #%option G_OPT_R_MAP
82       #% key: raster
83       #%end
84       The parser allows defining predefined rules for used options.  The syn‐
85       tax of the rules section is following:
86       #%rules
87       #% exclusive: capfile_output, capfile
88       #%end
89       The parser also allows defining "OR" conditions, e.g. requiring  raster
90       OR vector (for details, see below), e.g.for options:
91       #%rules
92       #% required: raster, vector
93       #%end
94       and e.g., for flags:
95       #%rules
96       #% required: -i,-d,-c
97       #%end
98

NOTES

100       An option can be instructed to allow multiple inputs by adding the fol‐
101       lowing line:
102       #% multiple: yes
103       While this will only directly change the  Usage  section  of  the  help
104       screen,  the  option’s  environmental  string may be easily parsed from
105       within a script. For example, individual comma separated identities for
106       an  option  named  "input"  can be parsed with the following Bash shell
107       code:
108       IFS=,
109       for opt in $GIS_OPT_INPUT ; do
110           ... "$opt"
111       done
112
113       A "guisection" field may be added to each option and  flag  to  specify
114       that  the  options should appear in multiple tabs in the auto-generated
115       GUI.  Any options without a guisection field go into the "Required"  or
116       "Options" tab.  For example:
117       #% guisection: tabname
118       would put that option in a tab named tabname.
119
120       A "key_desc" field may be added to each option to specify the text that
121       appears in the module’s usage help section. For example:
122       #% key_desc: filename
123       added to an input option would create the  usage  summary  [input=file‐
124       name].
125
126       If  a  script  is  run with --o, the parser will set GRASS_OVERWRITE=1,
127       which has the same effect as passing --o to every module which  is  run
128       from  the  script. Similarly, passing --q or --v will set GRASS_VERBOSE
129       to 0 or 3 respectively, which has the same effect as passing --q or --v
130       to  every  module  which  is run from the script.  Rather than checking
131       whether --o, --q or --v were used, you should be  checking  GRASS_OVER‐
132       WRITE  and/or  GRASS_VERBOSE  instead.  If those variables are set, the
133       script should behave the same way regardless of whether they  were  set
134       by --o, --q or --v being passed to the script or set by other means.
135

Conditional parameters

137       Marking  an  option  as  "required" will result in the parser raising a
138       fatal error if the option is not given, with one exception: if  a  flag
139       has  the suppress_required option, and that flag is given, all require‐
140       ments are ignored. This feature is intended  for  flags  which  abandon
141       "normal  operation" for the module; e.g. r.in.gdal’s -f flag (list sup‐
142       ported formats) uses it.
143       But in general, an option  cannot  be  marked  as  required  if  it  is
144       optional  except for the special case of a suppress_required flag.  The
145       parser has the ability to specify option relationships.
146
147       For C, the relevant functions  are  those  in  lib/gis/parser_dependen‐
148       cies.c.
149
150       For scripts, relationships are specified using a "rules" section, e.g.
151       #%rules
152       #% required: altitude,elevation
153       #%end
154       specifies  that  at  least  one  of  those  options must be given. Both
155       options and flags can be specified (a leading "-" denotes a flag).  The
156       available rule types are:
157
158           ·   exclusive: at most one of the options may be given
159
160           ·   required: at least one of the options must be given
161
162           ·   requires:  if  the  first  option is given, at least one of the
163               subsequent options must also be given
164
165           ·   requires_all: if the first option is given, all of  the  subse‐
166               quent options must also be given
167
168           ·   excludes:  if the first option is given, none of the subsequent
169               options may be given
170
171           ·   collective: all or nothing; if any option is given, all must be
172               given
173

AUTOMATED SCRIPT CREATION

175       The  flag --script added to a GRASS command, generates shell output. To
176       write out  a  g.parser  boilerplate  for  easy  prototyping  of  Python
177       scripts, the flag --script can be added to any GRASS command. Example:
178       v.in.db --script
179

Help page template (HTML)

181       The  flag  --html-description  added  to  a  GRASS  command generates a
182       related help page template in HTML. Example:
183       v.in.db --html-description
184

GUI window parser (XML)

186       The flag --interface-description added to a GRASS command  generates  a
187       related help page template in XML. Example:
188       v.in.db --interface-description
189

JSON

191       The flag --json added to a GRASS command with parameters mandatorily to
192       be specified generates a module interface description in JSON. Example:
193       v.in.db driver=sqlite database=mysqlite.db table=pointsfile x=x y=y z=z key=idcol out=dtmpoints --json
194       {
195         "module": "v.in.db",
196         "id": "v.in.db_1804289383",
197         "inputs":[
198            {"param": "table", "value": "pointsfile"},
199            {"param": "driver", "value": "sqlite"},
200            {"param": "database", "value": "mysqlite.db"},
201            {"param": "x", "value": "x"},
202            {"param": "y", "value": "y"},
203            {"param": "z", "value": "z"},
204            {"param": "key", "value": "idcol"}
205          ],
206         "outputs":[
207            {"param": "output", "value": "dtmpoints"}
208          ]
209       }
210

Web Processing Service (WPS)

212       The flag --wps-process-description added to a GRASS command generates a
213       Web Processing Service process description. Example:
214       v.in.db --wps-process-description
215

reStructuredText

217       The  flag  --rst-description  added to a GRASS command generates module
218       interface description in reStructuredText, a  lightweight  markup  lan‐
219       guage. Example:
220       v.in.db --rst-description
221       reStructuredText  is  sometimes abbreviated as reST, ReST, or RST.  The
222       commonly used file extension is .rst.  Don’t be confused with Represen‐
223       tational State Transfer (REST) technology.
224

TRANSLATION

226       g.parser  provides some support for translating the options of scripts.
227       If called with the -t switch before the script filename like this
228       g.parser -t somescriptfile
229       g.parser will print the text of the translatable  options  to  standard
230       output,  one  per  line,  and exit. This is for internal use within the
231       build system to prepare GRASS scripts for translation.
232

EXAMPLES

234       All examples below  autogenerate  the  graphical  user  interface  when
235       invoked without parameters of flags:
236
237       To  run properly, the script needs to be copied into a directory listed
238       in $GRASS_ADDON_PATH environmental variable with  the  executable  flag
239       being set.
240
241       The  script  will provide a GUI (as above) and the following usage help
242       text:
243       test.py|sh|pl --help
244       Description:
245        g.parser test script (python)
246       Usage:
247        test.sh [-f] raster=string vector=string [option1=string]
248          [--verbose] [--quiet]
249       Flags:
250         -f   A flag
251        --v   Verbose module output
252        --q   Quiet module output
253       Parameters:
254          raster   Raster input map
255          vector   Vector input map
256         option1   An option
257
258   Example code for Python
259       #!/usr/bin/env python3
260       # g.parser demo script for python programming
261       #%module
262       #% description: g.parser test script (python)
263       #% keyword: keyword1
264       #% keyword: keyword2
265       #%end
266       #%flag
267       #% key: f
268       #% description: A flag
269       #%end
270       #%option G_OPT_R_MAP
271       #% key: raster
272       #% required: yes
273       #%end
274       #%option G_OPT_V_MAP
275       #% key: vector
276       #%end
277       #%option
278       #% key: option1
279       #% type: string
280       #% description: An option
281       #% required: no
282       #%end
283       import os
284       import sys
285       import grass.script as grass
286       def main():
287           flag_f = flags[’f’]
288           option1 = options[’option1’]
289           raster = options[’raster’]
290           vector = options[’vector’]
291           #### add your code here ####
292           if flag_f:
293               print "Flag -f set"
294           else:
295               print "Flag -f not set"
296           # test if parameter present:
297           if option1:
298               print "Value of option1 option: ’%s’" % option1
299           print "Value of raster option: ’%s’" % raster
300           print "Value of vector option: ’%s’" % vector
301           #### end of your code ####
302           return 0
303       if __name__ == "__main__":
304           options, flags = grass.parser()
305           sys.exit(main())
306
307   Example code for SHELL
308       #!/bin/sh
309       # g.parser demo script for shell programming
310       #%module
311       #% description: g.parser test script (shell)
312       #%end
313       #%flag
314       #% key: f
315       #% description: A flag
316       #%end
317       #%option G_OPT_R_MAP
318       #% key: raster
319       #% required: yes
320       #%end
321       #%option G_OPT_V_MAP
322       #% key: vector
323       #%end
324       #%option
325       #% key: option1
326       #% type: string
327       #% description: An option
328       #% required: no
329       #%end
330       if [ -z "$GISBASE" ] ; then
331           echo "You must be in GRASS GIS to run this program." 1>&2
332           exit 1
333       fi
334       if [ "$1" != "@ARGS_PARSED@" ] ; then
335           exec g.parser "$0" "$@"
336       fi
337       #### add your code below ####
338       echo ""
339       if [ $GIS_FLAG_F -eq 1 ] ; then
340         g.message message="Flag -f set"
341       else
342         g.message message="Flag -f not set"
343       fi
344       # test if parameter present:
345       if [ -n "$GIS_OPT_OPTION1" ] ; then
346           echo "Value of GIS_OPT_OPTION1: ’$GIS_OPT_OPTION1’"
347       fi
348       g.message message="Value of GIS_OPT_option1: ’$GIS_OPT_option1’"
349       g.message message="Value of GIS_OPT_raster: ’$GIS_OPT_raster’"
350       g.message message="Value of GIS_OPT_vect: ’$GIS_OPT_vector’"
351       #### end of your code ####
352
353   Example code for Perl
354       #!/usr/bin/perl -w
355       use strict;
356       # g.parser demo script
357       #%module
358       #%  description: g.parser test script (perl)
359       #%  keyword: keyword1
360       #%  keyword: keyword2
361       #%end
362       #%flag
363       #%  key: f
364       #%  description: A flag
365       #%end
366       #%option G_OPT_R_MAP
367       #% key: raster
368       #% required: yes
369       #%end
370       #%option G_OPT_V_MAP
371       #% key: vector
372       #%end
373       #%option
374       #% key: option1
375       #% type: string
376       #% description: An option
377       #% required: no
378       #%end
379       if ( !$ENV{’GISBASE’} ) {
380           printf(STDERR  "You must be in GRASS GIS to run this program.\n");
381           exit 1;
382       }
383       if( $ARGV[0] ne ’@ARGS_PARSED@’ ){
384           my $arg = "";
385           for (my $i=0; $i < @ARGV;$i++) {
386               $arg .= " $ARGV[$i] ";
387           }
388           system("$ENV{GISBASE}/bin/g.parser $0 $arg");
389           exit;
390       }
391       #### add your code here ####
392       print  "\n";
393       if ( $ENV{’GIS_FLAG_F’} eq "1" ){
394          print "Flag -f set\n"
395       }
396       else {
397          print "Flag -f not set\n"
398       }
399       printf ("Value of GIS_OPT_option1: ’%s’\n", $ENV{’GIS_OPT_OPTION1’});
400       printf ("Value of GIS_OPT_raster: ’%s’\n", $ENV{’GIS_OPT_RASTER’});
401       printf ("Value of GIS_OPT_vect: ’%s’\n", $ENV{’GIS_OPT_VECTOR’});
402       #### end of your code ####
403
404   Easy creation of a script
405       By using the --script flag with any GRASS GIS module (must be run in  a
406       GRASS GIS session) header, description, keywords, parameters, flags and
407       a template main Python script section will be printed in  the  terminal
408       which can be saved to a file and used for further script programming.
409
410       In  this  example,  the  module v.what.rast is used as an example.  The
411       output is shown below:
412       v.what.rast --script
413       #!/usr/bin/env python3
414       ############################################################################
415       #
416       # MODULE:       v.what.rast_wrapper
417       # AUTHOR(S):    username
418       # PURPOSE:      Wrapper for v.what.rast
419       # COPYRIGHT:    (C) 2017 by username, and the GRASS Development Team
420       #
421       #  This program is free software; you can redistribute it and/or modify
422       #  it under the terms of the GNU General Public License as published by
423       #  the Free Software Foundation; either version 2 of the License, or
424       #  (at your option) any later version.
425       #
426       #  This program is distributed in the hope that it will be useful,
427       #  but WITHOUT ANY WARRANTY; without even the implied warranty of
428       #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
429       #  GNU General Public License for more details.
430       #
431       ############################################################################
432       #%module
433       #% description: Uploads raster values at positions of vector points to the table.
434       #% keyword: vector, sampling, raster, position, querying, attribute table, surface information
435       #%end
436       #%flag
437       #% key: i
438       #% description: Interpolate values from the nearest four cells
439       #%end
440       #%flag
441       #% key: p
442       #% description: Print categories and values instead of updating the database
443       #%end
444       #%option
445       #% key: map
446       #% type: string
447       #% required: yes
448       #% multiple: no
449       #% key_desc: name
450       #% label: Name of vector points map for which to edit attributes
451       #% description: Or data source for direct OGR access
452       #% gisprompt: old,vector,vector
453       #%end
454       #%option
455       #% key: layer
456       #% type: string
457       #% required: no
458       #% multiple: no
459       #% label: Layer number or name
460       #% 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.
461       #% answer: 1
462       #% gisprompt: old,layer,layer
463       #%end
464       #%option
465       #% key: type
466       #% type: string
467       #% required: no
468       #% multiple: yes
469       #% options: point,centroid
470       #% description: Input feature type
471       #% answer: point
472       #%end
473       #%option
474       #% key: raster
475       #% type: string
476       #% required: yes
477       #% multiple: no
478       #% key_desc: name
479       #% description: Name of existing raster map to be queried
480       #% gisprompt: old,cell,raster
481       #%end
482       #%option
483       #% key: column
484       #% type: string
485       #% required: no
486       #% multiple: no
487       #% key_desc: name
488       #% description: Name of attribute column to be updated with the query result
489       #% gisprompt: old,dbcolumn,dbcolumn
490       #%end
491       #%option
492       #% key: where
493       #% type: string
494       #% required: no
495       #% multiple: no
496       #% key_desc: sql_query
497       #% label: WHERE conditions of SQL statement without ’where’ keyword
498       #% description: Example: income < 1000 and population >= 10000
499       #%end
500       import sys
501       import grass.script as grass
502       def main():
503           # put code here
504           return 0
505       if __name__ == "__main__":
506           options, flags = grass.parser()
507           sys.exit(main())
508

SEE ALSO

510        g.filename, g.findfile, g.tempfile
511
512       Overview table: Parser standard options
513
514       Submitting rules for Python
515
516       Related Wiki pages: Using GRASS GIS with other programming languages
517

AUTHOR

519       Glynn Clements
520

SOURCE CODE

522       Available at: g.parser source code (history)
523
524       Main index | General index | Topics index | Keywords index |  Graphical
525       index | Full index
526
527       © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
528
529
530
531GRASS 7.8.5                                                        g.parser(1)
Impressum