← Back to branch summary

~ubuntu-branches/ubuntu/vivid/grass/vivid-proposed

« back to all changes in this revision

Viewing changes to general/g.parser/g.parser.html

  • Committer: Package Import Robot
  • Author(s): Bas Couwenberg
  • Date: 2015-02-20 23:12:08 UTC
  • mfrom: (8.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20150220231208-1u6qvqm84v430b10
Tags: 7.0.0-1~exp1
* New upstream release.
* Update python-ctypes-ternary.patch to use if/else instead of and/or.
* Drop check4dev patch, rely on upstream check.
* Add build dependency on libpq-dev to grass-dev for libpq-fe.h.
* Drop patches applied upstream, refresh remaining patches.
* Update symlinks for images switched from jpg to png.

Show diffs side-by-side

added added

removed removed

Lines of Context:
general/g.parser/g.parser.html
 
1
<!-- meta page name: g.parser -->
 
2
<!-- meta page name description: Provides full parser support for GRASS scripts. -->
 
3
 
 
4
<h2>KEYWORDS</h2>
 
5
<a href="general.html">general</a>, <a href="topic_support.html">support</a>, <a href="keywords.html#scripts">scripts</a>
 
6
 
 
7
<h2>SYNOPSIS</h2>
 
8
<b>g.parser --help</b><br>
 
9
<b>g.parser</b> [-<b>s</b>] [-<b>t</b>]  [-<b>n</b>] <em>filename</em> [<em>argument</em>,...]
 
10
 
 
11
<h3>Flags:</h3>
 
12
<dl>
 
13
<dt><b>-t</b></dt>
 
14
<dd>Print strings for translation</dd>
 
15
<dt><b>-s</b></dt>
 
16
<dd>Write option values to standard output instead of reinvoking script</dd>
 
17
<dt><b>-n</b></dt>
 
18
<dd>Write option values to standard output separated by null character</dd>
 
19
</dl>
 
20
 
 
21
<h2>DESCRIPTION</h2>
 
22
 
 
23
The <em>g.parser</em> module provides full parser support for GRASS
 
24
scripts, including an auto-generated GUI interface, help page
 
25
template, and command line option checking. In this way a simple
 
26
script can very quickly be made into a full-fledged GRASS module.
 
27
 
 
28
 
 
29
<h2>OPTIONS</h2>
 
30
 
 
31
Unless the <b>-s</b> or <b>-n</b> switch is used, the arguments are stored in
 
32
environment variables for use in your scripts. These variables are
 
33
named "GIS_FLAG_&lt;NAME&gt;" for flags and "GIS_OPT_&lt;NAME&gt;" for
 
34
options. The names of variables are converted to upper case. For
 
35
example if an option with key <b>input</b> was defined in the script
 
36
header, the value will be available in variable <b>GIS_OPT_INPUT</b>
 
37
and the value of flag with key <b>f</b> will be available in variable
 
38
<b>GIS_FLAG_F</b>.
 
39
 
 
40
<p>
 
41
For flags, the value will be "1" if the flag was given, and "0" otherwise.
 
42
 
 
43
<p>
 
44
If the <b>-s</b> or <b>-n</b> switch is used, the options and flags are written to
 
45
standard output in the form <em>opt_&lt;name&gt;=&lt;value&gt;</em> and
 
46
<em>flag_&lt;name&gt;=&lt;value&gt;</em>, preceded by the string
 
47
<b>@ARGS_PARSED@</b>. If this string doesn't appear as the first line
 
48
of standard output, it indicates that the script was invoked with a switch such
 
49
as <b>--html-description</b>. In this case, the data written by
 
50
<em>g.parser</em> to standard output should be copied to the script's standard output
 
51
verbatim.
 
52
 
 
53
If the <b>-s</b> switch is used, the options and flags are separated
 
54
by newlines. If the <b>-n</b> switch is used, the options and flags
 
55
are separated by null characters.
 
56
 
 
57
<p>
 
58
Typical header definitions are as follows:
 
59
 
 
60
<div class="code"><pre>
 
61
#%module
 
62
#% description: g.parser test script   
 
63
#%end
 
64
#%flag
 
65
#% key: f
 
66
#% description: A flag
 
67
#%end
 
68
#%option
 
69
#% key: raster
 
70
#% type: string
 
71
#% gisprompt: old,cell,raster
 
72
#% description: Raster input map
 
73
#% required: yes
 
74
#%end
 
75
</pre></div>
 
76
 
 
77
With <tt>{NULL}</tt> it is possible to suppress a predefined <tt>description</tt>
 
78
or <tt>label</tt>.
 
79
 
 
80
<p>
 
81
The parsers allows using predefined <em>standardized options and
 
82
flags</em>, see the list
 
83
of <a href="http://grass.osgeo.org/programming7/parser__standard__options_8c.html#a1a5da9db1229a9bbc59d16ae84540bb8">options</a> and <a href="http://grass.osgeo.org/programming7/parser__standard__options_8c.html#ad081e95e5d4dc3daab9c820d962e6902">flags</a>
 
84
in the programmer manual. Eg. the option
 
85
 
 
86
<div class="code"><pre>
 
87
#%option
 
88
#% key: raster
 
89
#% type: string
 
90
#% gisprompt: old,cell,raster
 
91
#% description: Raster input map
 
92
#% required: yes
 
93
#%end
 
94
</pre></div>
 
95
 
 
96
can be easily defined as
 
97
 
 
98
<div class="code"><pre>
 
99
#%option G_OPT_R_MAP
 
100
#% key: raster
 
101
#%end
 
102
</pre></div>
 
103
 
 
104
The parser allows defining predefined <em>rules</em>
 
105
for used options.
 
106
 
 
107
The syntax of the rules section is following:
 
108
 
 
109
<div class="code"><pre>
 
110
#%rules
 
111
#% exclusive: capfile_output, capfile
 
112
#%end
 
113
</pre></div>
 
114
 
 
115
The parser also allows defining "OR" conditions, e.g. requiring raster
 
116
OR vector (for details, see below), e.g.for options:
 
117
 
 
118
<div class="code"><pre>
 
119
#%rules
 
120
#% required: raster, vector
 
121
#%end
 
122
</pre></div>
 
123
 
 
124
and e.g., for flags:
 
125
 
 
126
<div class="code"><pre>
 
127
#%rules
 
128
#% required: -i,-d,-c
 
129
#%end
 
130
</pre></div>
 
131
 
 
132
<h2>NOTES</h2>
 
133
 
 
134
An option can be instructed to allow multiple inputs by adding the
 
135
following line:
 
136
<div class="code"><pre>
 
137
#% multiple: yes
 
138
</pre></div>
 
139
 
 
140
While this will only directly change the <i>Usage</i> section of the help
 
141
screen, the option's environmental string may be easily parsed from within
 
142
a script. For example, individual comma separated identities for an option 
 
143
named "input" can be parsed with the following Bash shell code:
 
144
 
 
145
<div class="code"><pre>IFS=,
 
146
for opt in $GIS_OPT_INPUT ; do
 
147
    ... "$opt"
 
148
done
 
149
</pre></div>
 
150
 
 
151
<p>
 
152
A "<tt>guisection</tt>" field may be added to each option and flag to
 
153
specify that the options should appear in multiple tabs in the
 
154
auto-generated GUI.  Any options without a <tt>guisection</tt> field
 
155
go into the "Required" or "Options" tab.  For example:
 
156
<div class="code"><pre>
 
157
#% guisection: tabname
 
158
</pre></div>
 
159
would put that option in a tab named <i>tabname</i>.
 
160
 
 
161
<p>
 
162
A "<tt>key_desc</tt>" field may be added to each option to specify the text that
 
163
appears in the module's usage help section. For example:
 
164
<div class="code"><pre>
 
165
#% key_desc: filename
 
166
</pre></div>
 
167
added to an <b>input</b> option would create the usage summary
 
168
<tt>[input=filename]</tt>.
 
169
 
 
170
<p>
 
171
If a script is run with <b>--o</b>, the parser will
 
172
set <tt>GRASS_OVERWRITE=1</tt>, which has the same effect as passing
 
173
<b>--o</b> to every module which is run from the script. Similarly, passing
 
174
<b>--q</b> or <b>--v</b> will set <tt>GRASS_VERBOSE</tt> to 0 or 3 respectively,
 
175
which has the same effect as passing <b>--q</b> or <b>--v</b> to every module which
 
176
is run from the script.  Rather than checking whether <b>--o</b>, <b>--q</b> or <b>--v</b>
 
177
were used, you should be checking <tt>GRASS_OVERWRITE</tt> and/or
 
178
<tt>GRASS_VERBOSE</tt> instead. If those variables are set, the script
 
179
should behave the same way regardless of whether they were set
 
180
by <b>--o</b>, <b>--q</b> or <b>--v</b> being passed to the script or
 
181
set by other means.
 
182
 
 
183
<h2>Conditional parameters</h2>
 
184
 
 
185
Marking an option as "required" will result in the parser raising a
 
186
fatal error if the option is not given, with one exception: if a flag
 
187
has the <tt>suppress_required</tt> option, and that flag is given, all
 
188
requirements are ignored. This feature is intended for flags which
 
189
abandon "normal operation" for the module; e.g. <em>r.in.gdal</em>'s
 
190
<b>-f</b> flag (list supported formats) uses it.
 
191
<br>
 
192
But in general, an option cannot be marked as required if it is
 
193
optional except for the special case of a <tt>suppress_required</tt> flag.
 
194
The parser has the ability to specify option relationships.
 
195
 
 
196
<p>
 
197
For C, the relevant functions are those in
 
198
<a href="http://grass.osgeo.org/programming7/parser__dependencies_8c.html">lib/gis/parser_dependencies.c</a>.
 
199
 
 
200
<p>
 
201
For scripts, relationships are specified using a "rules" section, e.g.
 
202
 
 
203
<div class="code"><pre>
 
204
#%rules
 
205
#% required: altitude,elevation
 
206
#%end
 
207
</pre></div>
 
208
 
 
209
specifies that at least one of those options must be given. Both
 
210
options and flags can be specified (a leading "<b>-</b>" denotes a flag).
 
211
 
 
212
The available rule types are:
 
213
 
 
214
<ul>
 
215
<li> <tt>exclusive</tt>: at most one of the options may be given</li>
 
216
<li> <tt>required</tt>: at least one of the options must be given</li>
 
217
<li> <tt>requires</tt>: if the first option is given, at least one of the
 
218
      subsequent options must also be given</li>
 
219
<li> <tt>requires_all</tt>: if the first option is given, all of the
 
220
      subsequent options must also be given</li>
 
221
<li> <tt>excludes</tt>: if the first option is given, none of the
 
222
      subsequent options may be given</li>
 
223
<li> <tt>collective</tt>: all or nothing; if any option is given, all
 
224
      must be given</li>
 
225
</ul>
 
226
 
 
227
<h2>AUTOMATED SCRIPT CREATION</h2>
 
228
 
 
229
The flag <b>--script</b> added to a GRASS command, generates shell
 
230
output. To write out a <em>g.parser</em> boilerplate for easy
 
231
prototyping of shell scripts, the flag <b>--script</b> can be added
 
232
to any GRASS command. Example:
 
233
 
 
234
<div class="code"><pre>
 
235
v.in.db --script
 
236
</pre></div>
 
237
 
 
238
 
 
239
<h2>Help page template (HTML)</h2>
 
240
 
 
241
The flag <b>--html-description</b> added to a GRASS command
 
242
generates a related help page template in HTML. Example:
 
243
 
 
244
<div class="code"><pre>
 
245
v.in.db --html-description
 
246
</pre></div>
 
247
 
 
248
 
 
249
<h2>GUI window parser (XML)</h2>
 
250
 
 
251
The flag <b>--interface-description</b> added to a GRASS command
 
252
generates a related help page template in XML. Example:
 
253
 
 
254
<div class="code"><pre>
 
255
v.in.db --interface-description
 
256
</pre></div>
 
257
 
 
258
<h2>Web Processing Service (WPS)</h2>
 
259
 
 
260
The flag <b>--wps-process-description</b> added to a GRASS command
 
261
generates a Web Processing Service process description. Example:
 
262
 
 
263
<div class="code"><pre>
 
264
v.in.db --wps-process-description
 
265
</pre></div>
 
266
 
 
267
<h2>reStructuredText</h2>
 
268
 
 
269
The flag <b>--rst-description</b> added to a GRASS command
 
270
generates module interface description in reStructuredText, a lightweight
 
271
markup language. Example:
 
272
 
 
273
<div class="code"><pre>
 
274
v.in.db --rst-description
 
275
</pre></div>
 
276
 
 
277
reStructuredText is sometimes abbreviated as reST, ReST, or RST.
 
278
The commonly used file extension is <tt>.rst</tt>.
 
279
Don't be confused with Representational State Transfer (REST) technology.
 
280
 
 
281
<h2>TRANSLATION</h2>
 
282
 
 
283
<em>g.parser</em> provides some support for translating the options of
 
284
scripts. If called with the -t switch before the script filename like
 
285
this
 
286
 
 
287
<div class="code"><pre>
 
288
g.parser -t somescriptfile
 
289
</pre></div>
 
290
 
 
291
<em>g.parser</em> will print the text of the translatable options to
 
292
standard output, one per line, and exit. This is for internal use within
 
293
the build system to prepare GRASS scripts for translation.
 
294
 
 
295
 
 
296
<h2>EXAMPLES</h2>
 
297
 
 
298
All examples below autogenerate the graphical user interface when invoked
 
299
without parameters of flags:
 
300
 
 
301
<p>
 
302
<center>
 
303
<img src="g_parser_test.png" alt="Autogenerated GUI window">
 
304
</center>
 
305
 
 
306
<p>
 
307
To run properly, the script needs to be copied into a directory listed
 
308
in <tt>$GRASS_ADDON_PATH</tt> environmental variable with the
 
309
executable flag being set. 
 
310
 
 
311
<p>
 
312
The script will provide a GUI (as above) and the following usage help
 
313
text:
 
314
 
 
315
<div class="code"><pre>
 
316
test.py|sh|pl --help
 
317
 
 
318
Description:
 
319
 g.parser test script (python)
 
320
 
 
321
Usage:
 
322
 test.sh [-f] raster=string vector=string [option1=string]
 
323
   [--verbose] [--quiet]
 
324
 
 
325
Flags:
 
326
  -f   A flag
 
327
 --v   Verbose module output
 
328
 --q   Quiet module output
 
329
 
 
330
Parameters:
 
331
   raster   Raster input map
 
332
   vector   Vector input map
 
333
  option1   An option
 
334
</pre></div>
 
335
 
 
336
<h3>Example code for Python</h3>
 
337
 
 
338
<div class="code"><pre>
 
339
#!/usr/bin/env python
 
340
 
 
341
# g.parser demo script for python programing
 
342
 
 
343
#%module
 
344
#% description: g.parser test script (python)
 
345
#% keyword: keyword1
 
346
#% keyword: keyword2
 
347
#%end
 
348
#%flag
 
349
#% key: f
 
350
#% description: A flag
 
351
#%end
 
352
#%option G_OPT_R_MAP
 
353
#% key: raster
 
354
#% required: yes
 
355
#%end
 
356
#%option G_OPT_V_MAP
 
357
#% key: vector
 
358
#%end
 
359
#%option
 
360
#% key: option1
 
361
#% type: string
 
362
#% description: An option
 
363
#% required: no
 
364
#%end
 
365
 
 
366
import os
 
367
import sys
 
368
 
 
369
import grass.script as grass
 
370
 
 
371
def main():
 
372
    flag_f = flags['f']
 
373
    option1 = options['option1']
 
374
    raster = options['raster']
 
375
    vector = options['vector']
 
376
 
 
377
    #### add your code here ####
 
378
 
 
379
    if flag_f:
 
380
        print "Flag -f set"
 
381
    else:
 
382
        print "Flag -f not set"
 
383
 
 
384
    # test if parameter present:
 
385
    if option1:
 
386
        print "Value of option1 option: '%s'" % option1
 
387
 
 
388
    print "Value of raster option: '%s'" % raster
 
389
    print "Value of vector option: '%s'" % vector
 
390
 
 
391
    #### end of your code ####
 
392
 
 
393
    return 0
 
394
 
 
395
if __name__ == "__main__":
 
396
    options, flags = grass.parser()
 
397
    sys.exit(main())
 
398
</pre></div>
 
399
 
 
400
<h3>Example code for SHELL</h3>
 
401
 
 
402
<div class="code"><pre>
 
403
#!/bin/sh
 
404
 
 
405
# g.parser demo script for shell programing
 
406
 
 
407
#%module
 
408
#% description: g.parser test script (shell) 
 
409
#%end
 
410
#%flag
 
411
#% key: f
 
412
#% description: A flag
 
413
#%end
 
414
#%option G_OPT_R_MAP
 
415
#% key: raster
 
416
#% required: yes
 
417
#%end
 
418
#%option G_OPT_V_MAP
 
419
#% key: vector
 
420
#%end
 
421
#%option
 
422
#% key: option1
 
423
#% type: string
 
424
#% description: An option
 
425
#% required: no
 
426
#%end
 
427
 
 
428
if [ -z "$GISBASE" ] ; then
 
429
    echo "You must be in GRASS GIS to run this program." 1&gt;&amp;2
 
430
    exit 1
 
431
fi
 
432
 
 
433
if [ "$1" != "@ARGS_PARSED@" ] ; then
 
434
    exec g.parser "$0" "$@"
 
435
fi
 
436
 
 
437
#### add your code below ####
 
438
 
 
439
echo ""
 
440
 
 
441
if [ $GIS_FLAG_F -eq 1 ] ; then
 
442
  g.message message="Flag -f set"
 
443
else
 
444
  g.message message="Flag -f not set"
 
445
fi
 
446
 
 
447
# test if parameter present:
 
448
if [ -n "$GIS_OPT_OPTION1" ] ; then
 
449
    echo "Value of GIS_OPT_OPTION1: '$GIS_OPT_OPTION1'"
 
450
fi
 
451
 
 
452
g.message message="Value of GIS_OPT_option1: '$GIS_OPT_option1'"
 
453
g.message message="Value of GIS_OPT_raster: '$GIS_OPT_raster'"
 
454
g.message message="Value of GIS_OPT_vect: '$GIS_OPT_vector'"
 
455
 
 
456
#### end of your code ####
 
457
</pre></div>
 
458
 
 
459
<h3>Example code for Perl</h3>
 
460
 
 
461
<div class="code"><pre>
 
462
#!/usr/bin/perl -w
 
463
use strict;
 
464
 
 
465
# g.parser demo script
 
466
 
 
467
#%module
 
468
#%  description: g.parser test script (perl) 
 
469
#%  keyword: keyword1
 
470
#%  keyword: keyword2
 
471
#%end
 
472
#%flag
 
473
#%  key: f
 
474
#%  description: A flag
 
475
#%end
 
476
#%option G_OPT_R_MAP
 
477
#% key: raster
 
478
#% required: yes
 
479
#%end
 
480
#%option G_OPT_V_MAP
 
481
#% key: vector
 
482
#%end
 
483
#%option
 
484
#% key: option1
 
485
#% type: string
 
486
#% description: An option
 
487
#% required: no
 
488
#%end
 
489
 
 
490
if ( !$ENV{'GISBASE'} ) {
 
491
    printf(STDERR  "You must be in GRASS GIS to run this program.\n");
 
492
    exit 1;
 
493
}
 
494
 
 
495
if( $ARGV[0] ne '@ARGS_PARSED@' ){
 
496
    my $arg = "";
 
497
    for (my $i=0; $i < @ARGV;$i++) {
 
498
        $arg .= " $ARGV[$i] ";
 
499
    }
 
500
    system("$ENV{GISBASE}/bin/g.parser $0 $arg");
 
501
    exit;
 
502
}
 
503
 
 
504
#### add your code here ####
 
505
print  "\n";
 
506
if ( $ENV{'GIS_FLAG_F'} eq "1" ){
 
507
   print "Flag -f set\n"
 
508
}
 
509
else {
 
510
   print "Flag -f not set\n"
 
511
}
 
512
 
 
513
printf ("Value of GIS_OPT_option1: '%s'\n", $ENV{'GIS_OPT_OPTION1'});
 
514
printf ("Value of GIS_OPT_raster: '%s'\n", $ENV{'GIS_OPT_RASTER'});
 
515
printf ("Value of GIS_OPT_vect: '%s'\n", $ENV{'GIS_OPT_VECTOR'});
 
516
 
 
517
#### end of your code ####
 
518
 
 
519
</pre></div>
 
520
 
 
521
<h2>SEE ALSO</h2>
 
522
 
 
523
<em>
 
524
<a href="g.filename.html">g.filename</a>,
 
525
<a href="g.findfile.html">g.findfile</a>,
 
526
<a href="g.tempfile.html">g.tempfile</a>
 
527
</em>
 
528
 
 
529
<p>
 
530
<a href="http://trac.osgeo.org/grass/wiki/Submitting/Python">Submitting rules for Python</a>
 
531
 
 
532
<p>
 
533
Related Wiki pages:
 
534
<a href="http://grasswiki.osgeo.org/wiki/Category:Linking_to_other_languages">Using GRASS GIS with other programming languages</a>
 
535
 
 
536
<h2>AUTHOR</h2>
 
537
 
 
538
Glynn Clements
 
539
 
 
540
<p>
 
541
<i>Last changed: $Date: 2015-01-25 18:56:33 +0100 (Sun, 25 Jan 2015) $</i>