1g.parser(1) Grass User's Manual g.parser(1)
2
6 g.parser - Provides full parser support for GRASS scripts.
7
9 general, support, scripts
10
12 g.parser --help
13 g.parser [-s] [-t] [-n] filename [argument,...]
14 Flags:
16 -t
17 Print strings for translation
18 -s
20 Write option values to standard output instead of reinvoking script
21 -n
23 Write option values to standard output separated by null character
24
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
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 For flags, the value will be "1" if the flag was given, and "0" other‐
41 wise.
42 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 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 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
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 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 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 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
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 For C, the relevant functions are those in lib/gis/parser_dependen‐
148 cies.c.
149 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 · exclusive: at most one of the options may be given
159 · required: at least one of the options must be given
161 · requires: if the first option is given, at least one of the
163 subsequent options must also be given
164 · requires_all: if the first option is given, all of the subse‐
166 quent options must also be given
167 · excludes: if the first option is given, none of the subsequent
169 options may be given
170 · collective: all or nothing; if any option is given, all must be
172 given
173
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
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
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
191 The flag --wps-process-description added to a GRASS command generates a
192 Web Processing Service process description. Example:
193 v.in.db --wps-process-description
194
196 The flag --rst-description added to a GRASS command generates module
197 interface description in reStructuredText, a lightweight markup lan‐
198 guage. Example:
199 v.in.db --rst-description
200 reStructuredText is sometimes abbreviated as reST, ReST, or RST. The
201 commonly used file extension is .rst. Don’t be confused with Represen‐
202 tational State Transfer (REST) technology.
203
205 g.parser provides some support for translating the options of scripts.
206 If called with the -t switch before the script filename like this
207 g.parser -t somescriptfile
208 g.parser will print the text of the translatable options to standard
209 output, one per line, and exit. This is for internal use within the
210 build system to prepare GRASS scripts for translation.
211
213 All examples below autogenerate the graphical user interface when
214 invoked without parameters of flags:
215 To run properly, the script needs to be copied into a directory listed
217 in $GRASS_ADDON_PATH environmental variable with the executable flag
218 being set.
219 The script will provide a GUI (as above) and the following usage help
221 text:
222 test.py|sh|pl --help
223 Description:
224 g.parser test script (python)
225 Usage:
226 test.sh [-f] raster=string vector=string [option1=string]
227 [--verbose] [--quiet]
228 Flags:
229 -f A flag
230 --v Verbose module output
231 --q Quiet module output
232 Parameters:
233 raster Raster input map
234 vector Vector input map
235 option1 An option
236 Example code for Python
238 #!/usr/bin/python2
239 # g.parser demo script for python programming
240 #%module
241 #% description: g.parser test script (python)
242 #% keyword: keyword1
243 #% keyword: keyword2
244 #%end
245 #%flag
246 #% key: f
247 #% description: A flag
248 #%end
249 #%option G_OPT_R_MAP
250 #% key: raster
251 #% required: yes
252 #%end
253 #%option G_OPT_V_MAP
254 #% key: vector
255 #%end
256 #%option
257 #% key: option1
258 #% type: string
259 #% description: An option
260 #% required: no
261 #%end
262 import os
263 import sys
264 import grass.script as grass
265 def main():
266 flag_f = flags[’f’]
267 option1 = options[’option1’]
268 raster = options[’raster’]
269 vector = options[’vector’]
270 #### add your code here ####
271 if flag_f:
272 print "Flag -f set"
273 else:
274 print "Flag -f not set"
275 # test if parameter present:
276 if option1:
277 print "Value of option1 option: ’%s’" % option1
278 print "Value of raster option: ’%s’" % raster
279 print "Value of vector option: ’%s’" % vector
280 #### end of your code ####
281 return 0
282 if __name__ == "__main__":
283 options, flags = grass.parser()
284 sys.exit(main())
285 Example code for SHELL
287 #!/bin/sh
288 # g.parser demo script for shell programming
289 #%module
290 #% description: g.parser test script (shell)
291 #%end
292 #%flag
293 #% key: f
294 #% description: A flag
295 #%end
296 #%option G_OPT_R_MAP
297 #% key: raster
298 #% required: yes
299 #%end
300 #%option G_OPT_V_MAP
301 #% key: vector
302 #%end
303 #%option
304 #% key: option1
305 #% type: string
306 #% description: An option
307 #% required: no
308 #%end
309 if [ -z "$GISBASE" ] ; then
310 echo "You must be in GRASS GIS to run this program." 1>&2
311 exit 1
312 fi
313 if [ "$1" != "@ARGS_PARSED@" ] ; then
314 exec g.parser "$0" "$@"
315 fi
316 #### add your code below ####
317 echo ""
318 if [ $GIS_FLAG_F -eq 1 ] ; then
319 g.message message="Flag -f set"
320 else
321 g.message message="Flag -f not set"
322 fi
323 # test if parameter present:
324 if [ -n "$GIS_OPT_OPTION1" ] ; then
325 echo "Value of GIS_OPT_OPTION1: ’$GIS_OPT_OPTION1’"
326 fi
327 g.message message="Value of GIS_OPT_option1: ’$GIS_OPT_option1’"
328 g.message message="Value of GIS_OPT_raster: ’$GIS_OPT_raster’"
329 g.message message="Value of GIS_OPT_vect: ’$GIS_OPT_vector’"
330 #### end of your code ####
331 Example code for Perl
333 #!/usr/bin/perl -w
334 use strict;
335 # g.parser demo script
336 #%module
337 #% description: g.parser test script (perl)
338 #% keyword: keyword1
339 #% keyword: keyword2
340 #%end
341 #%flag
342 #% key: f
343 #% description: A flag
344 #%end
345 #%option G_OPT_R_MAP
346 #% key: raster
347 #% required: yes
348 #%end
349 #%option G_OPT_V_MAP
350 #% key: vector
351 #%end
352 #%option
353 #% key: option1
354 #% type: string
355 #% description: An option
356 #% required: no
357 #%end
358 if ( !$ENV{’GISBASE’} ) {
359 printf(STDERR "You must be in GRASS GIS to run this program.\n");
360 exit 1;
361 }
362 if( $ARGV[0] ne ’@ARGS_PARSED@’ ){
363 my $arg = "";
364 for (my $i=0; $i < @ARGV;$i++) {
365 $arg .= " $ARGV[$i] ";
366 }
367 system("$ENV{GISBASE}/bin/g.parser $0 $arg");
368 exit;
369 }
370 #### add your code here ####
371 print "\n";
372 if ( $ENV{’GIS_FLAG_F’} eq "1" ){
373 print "Flag -f set\n"
374 }
375 else {
376 print "Flag -f not set\n"
377 }
378 printf ("Value of GIS_OPT_option1: ’%s’\n", $ENV{’GIS_OPT_OPTION1’});
379 printf ("Value of GIS_OPT_raster: ’%s’\n", $ENV{’GIS_OPT_RASTER’});
380 printf ("Value of GIS_OPT_vect: ’%s’\n", $ENV{’GIS_OPT_VECTOR’});
381 #### end of your code ####
382 Easy creation of a script
384 By using the --script flag with any GRASS GIS module (must be run in a
385 GRASS GIS session) header, description, keywords, parameters, flags and
386 a template main Python script section will be printed in the terminal
387 which can be saved to a file and used for further script programming.
388 In this example, the module v.what.rast is used as an example. The
390 output is shown below:
391 v.what.rast --script
392 #!/usr/bin/python2
393 ############################################################################
394 #
395 # MODULE: v.what.rast_wrapper
396 # AUTHOR(S): username
397 # PURPOSE: Wrapper for v.what.rast
398 # COPYRIGHT: (C) 2017 by username, and the GRASS Development Team
399 #
400 # This program is free software; you can redistribute it and/or modify
401 # it under the terms of the GNU General Public License as published by
402 # the Free Software Foundation; either version 2 of the License, or
403 # (at your option) any later version.
404 #
405 # This program is distributed in the hope that it will be useful,
406 # but WITHOUT ANY WARRANTY; without even the implied warranty of
407 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
408 # GNU General Public License for more details.
409 #
410 ############################################################################
411 #%module
412 #% description: Uploads raster values at positions of vector points to the table.
413 #% keyword: vector, sampling, raster, position, querying, attribute table, surface information
414 #%end
415 #%flag
416 #% key: i
417 #% description: Interpolate values from the nearest four cells
418 #%end
419 #%flag
420 #% key: p
421 #% description: Print categories and values instead of updating the database
422 #%end
423 #%option
424 #% key: map
425 #% type: string
426 #% required: yes
427 #% multiple: no
428 #% key_desc: name
429 #% label: Name of vector points map for which to edit attributes
430 #% description: Or data source for direct OGR access
431 #% gisprompt: old,vector,vector
432 #%end
433 #%option
434 #% key: layer
435 #% type: string
436 #% required: no
437 #% multiple: no
438 #% label: Layer number or name
439 #% 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.
440 #% answer: 1
441 #% gisprompt: old,layer,layer
442 #%end
443 #%option
444 #% key: type
445 #% type: string
446 #% required: no
447 #% multiple: yes
448 #% options: point,centroid
449 #% description: Input feature type
450 #% answer: point
451 #%end
452 #%option
453 #% key: raster
454 #% type: string
455 #% required: yes
456 #% multiple: no
457 #% key_desc: name
458 #% description: Name of existing raster map to be queried
459 #% gisprompt: old,cell,raster
460 #%end
461 #%option
462 #% key: column
463 #% type: string
464 #% required: no
465 #% multiple: no
466 #% key_desc: name
467 #% description: Name of attribute column to be updated with the query result
468 #% gisprompt: old,dbcolumn,dbcolumn
469 #%end
470 #%option
471 #% key: where
472 #% type: string
473 #% required: no
474 #% multiple: no
475 #% key_desc: sql_query
476 #% label: WHERE conditions of SQL statement without ’where’ keyword
477 #% description: Example: income < 1000 and population >= 10000
478 #%end
479 import sys
480 import grass.script as grass
481 def main():
482 # put code here
483 return 0
484 if __name__ == "__main__":
485 options, flags = grass.parser()
486 sys.exit(main())
487
489 g.filename, g.findfile, g.tempfile
490 Overview table: Parser standard options
492 Submitting rules for Python
494 Related Wiki pages: Using GRASS GIS with other programming languages
496
498 Glynn Clements
499 Last changed: $Date: 2017-04-22 21:39:11 +0200 (Sat, 22 Apr 2017) $
501
503 Available at: g.parser source code (history)
504 Main index | General index | Topics index | Keywords index | Graphical
506 index | Full index
507 © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual
509GRASS 7.6.0 g.parser(1)