1g.parser(1) Grass User's Manual g.parser(1)
2
3
4
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
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
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
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
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
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
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 --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
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
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
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
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
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
519 Glynn Clements
520
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-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
528
529
530
531GRASS 7.8.2 g.parser(1)