← Back to branch summary

~ubuntu-branches/ubuntu/wily/grass/wily

« back to all changes in this revision

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

Tags: 7.0.0~rc1+ds1-1~exp1
http://bugs.debian.org/776349
* New upstream release candidate.
* Repack upstream tarball, remove precompiled Python objects.
* Add upstream metadata.
* Update gbp.conf and Vcs-Git URL to use the experimental branch.
* Update watch file for GRASS 7.0.
* Drop build dependencies for Tcl/Tk, add build dependencies:
  python-numpy, libnetcdf-dev, netcdf-bin, libblas-dev, liblapack-dev
* Update Vcs-Browser URL to use cgit instead of gitweb.
* Update paths to use grass70.
* Add configure options: --with-netcdf, --with-blas, --with-lapack,
  remove --with-tcltk-includes.
* Update patches for GRASS 7.
* Update copyright file, changes:
  - Update copyright years
  - Group files by license
  - Remove unused license sections
* Add patches for various typos.
* Fix desktop file with patch instead of d/rules.
* Use minimal dh rules.
* Bump Standards-Version to 3.9.6, no changes.
* Use dpkg-maintscript-helper to replace directories with symlinks.
  (closes: #776349)
* Update my email to use @debian.org address.

Show diffs side-by-side

added added

removed removed

Lines of Context:
general/g.parser/description.html
1
 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
 
<html>
3
 
<head>
4
 
<title>g.parser</title>
5
 
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6
 
<link rel="stylesheet" href="grassdocs.css" type="text/css">
7
 
</head>
8
 
<body bgcolor="white">
9
 
 
10
 
<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>
11
 
 
12
 
 
13
 
<h2>NAME</h2>
14
 
<em><b>g.parser</b></em>
15
 
 
16
 
<h2>SYNOPSIS</h2>
17
 
<b>g.parser help</b><br>
18
 
<b>g.parser</b> [-<b>s</b>] [-<b>t</b>] <em>filename</em> [<em>argument</em>,...]
19
 
 
20
 
<h3>Flags:</h3>
21
 
<DL>
22
 
<DT><b>-t</b></DT>
23
 
<DD>Print strings for translation</DD>
24
 
<DT><b>-s</b></DT>
25
 
<DD>Write option values to stdout instead of reinvoking script</DD>
26
 
</DL>
27
 
 
28
 
<h2>DESCRIPTION</h2>
29
 
 
30
 
The <em>g.parser</em> module provides full parser support for GRASS
31
 
scripts, including an auto-generated GUI interface, help page
32
 
template, and command line option checking. In this way a simple
33
 
script can very quickly be made into a full-fledged GRASS module.
34
 
 
35
 
 
36
 
<h2>OPTIONS</h2>
37
 
 
38
 
Unless the <b>-s</b> switch is used, the arguments are stored in
39
 
environment variables for use in your scripts. These variables are
40
 
named "GIS_FLAG_&lt;NAME&gt;" for flags and "GIS_OPT_&lt;NAME&gt;" for
41
 
options. The names of variables are converted to upper case. For
42
 
example if an option with key <b>input</b> was defined in the script
43
 
header, the value will be available in variable <b>GIS_OPT_INPUT</b>
44
 
and the value of flag with key <b>f</b> will be available in variable
45
 
<b>GIS_FLAG_F</b>.
46
 
 
47
 
<p>
48
 
For flags, the value will be "1" if the flag was given, and "0" otherwise.
49
 
 
50
 
<p>
51
 
If the <b>-s</b> switch is used, the options and flags are written to
52
 
stdout in the form <em>opt_&lt;name&gt;=&lt;value&gt;</em> and
53
 
<em>flag_&lt;name&gt;=&lt;value&gt;</em>, preceded by the string
54
 
<b>@ARGS_PARSED@</b>. If this string doesn't appear as the first line
55
 
of stdout, it indicates that the script was invoked with a switch such
56
 
as <b>--html-description</b>. In this case, the data written by
57
 
<em>g.parser</em> to stdout should be copied to the script's stdout
58
 
verbatim.
59
 
 
60
 
<p>
61
 
Typical header definitions are as follows:
62
 
 
63
 
<div class="code"><pre>
64
 
#%module
65
 
#%  description: g.parser test script   
66
 
#%end
67
 
#%flag
68
 
#%  key: f
69
 
#%  description: A flag
70
 
#%end
71
 
#%option
72
 
#%  key: raster
73
 
#%  type: string
74
 
#%  gisprompt: old,cell,raster
75
 
#%  description: Raster input map
76
 
#%  required : yes
77
 
#%end
78
 
</pre></div>
79
 
 
80
 
 
81
 
<h2>NOTES</h2>
82
 
 
83
 
An option can be instructed to allow multiple inputs by adding the
84
 
following line:
85
 
<pre>#% multiple : yes</pre>
86
 
While this will only directly change the <i>Usage</i> section of the help
87
 
screen, the option's environmental string may be easily parsed from within
88
 
a script. For example, individual comma separated identities for an option 
89
 
named "input" can be parsed with the following Bash shell code:
90
 
 
91
 
<div class="code"><pre>IFS=,
92
 
for opt in $GIS_OPT_INPUT ; do
93
 
    ... "$opt"
94
 
done
95
 
</pre></div>
96
 
 
97
 
<p>
98
 
A "<tt>guisection</tt>" field may be added to each option and flag to specify
99
 
that the options should appear in multiple tabs in the auto-generated GUI.
100
 
Any options without a <tt>guisection</tt> field go into the "Options" tab.
101
 
For example:
102
 
<pre>#% guisection: tabname</pre>
103
 
would put that option in a tab named <i>tabname</i>.
104
 
 
105
 
<p>
106
 
A "<tt>key_desc</tt>" field may be added to each option to specify the text that
107
 
appears in the module's usage help section. For example:
108
 
<pre>#% key_desc: filename</pre>
109
 
added to an <b>input</b> option would create the usage summary
110
 
<tt>[input=filename]</tt>.
111
 
 
112
 
<p>
113
 
If a script is run with --o, G_parser() will
114
 
set <tt>GRASS_OVERWRITE=1</tt>, which has the same effect as passing
115
 
--o to every module which is run from the script. Similarly, passing
116
 
--q or --v will set <tt>GRASS_VERBOSE</tt> to 0 or 3 respectively,
117
 
which has the same effect as passing --q or --v to every module which
118
 
is run from the script.  Rather than checking whether --o, --q or --v
119
 
were used, you should be checking <tt>GRASS_OVERWRITE</tt> and/or
120
 
<tt>GRASS_VERBOSE</tt> instead. If those variables are set, the
121
 
script should behave the same way regardless of whether they were set
122
 
by --o, --q or --v being passed to the script or set by other means.
123
 
 
124
 
 
125
 
<h2>AUTOMATED SCRIPT CREATION</h2>
126
 
 
127
 
The flag <b>--script</b> added to a GRASS command, generates shell
128
 
output. To write out a <em>g.parser</em> boilerplate for easy
129
 
prototyping of shell scripts, the flag <b>--script</b> can be added
130
 
to any GRASS command. Example:
131
 
 
132
 
<div class="code"><pre>
133
 
v.in.db --script
134
 
</pre></div>
135
 
 
136
 
 
137
 
<h2>Help page template (HTML)</h2>
138
 
 
139
 
The flag <b>--html-description</b> added to a GRASS command
140
 
generates a related help page template in HTML. Example:
141
 
 
142
 
<div class="code"><pre>
143
 
v.in.db --html-description
144
 
</pre></div>
145
 
 
146
 
 
147
 
<h2>GUI window parser (XML)</h2>
148
 
 
149
 
The flag <b>--interface-description</b> added to a GRASS command
150
 
generates a related help page template in XML. Example:
151
 
 
152
 
<div class="code"><pre>
153
 
v.in.db --interface-description
154
 
</pre></div>
155
 
 
156
 
<h2>GUI window parser (Tcl/Tk)</h2>
157
 
 
158
 
The flag <b>--tcltk</b> added to a GRASS command generates Tcl/Tk
159
 
code suitable for building the GUI interface. Example:
160
 
 
161
 
<div class="code"><pre>
162
 
v.in.db --tcltk
163
 
</pre></div>
164
 
 
165
 
 
166
 
<h2>TRANSLATION</h2>
167
 
 
168
 
<em>g.parser</em> provides some support for translating the options of
169
 
scripts. If called with the -t switch before the script filename like
170
 
this
171
 
 
172
 
<div class="code"><pre>
173
 
g.parser -t somescriptfile
174
 
</pre></div>
175
 
 
176
 
<em>g.parser</em> will print the text of the translatable options to
177
 
<tt>stdout</tt>, one per line, and exit. This is for internal use within
178
 
the build system to prepare GRASS scripts for translation.
179
 
 
180
 
 
181
 
<h2>EXAMPLES</h2>
182
 
 
183
 
<h3>Example code for SHELL</h3>
184
 
 
185
 
<div class="code"><pre>
186
 
#!/bin/sh
187
 
 
188
 
# g.parser demo script for shell programing
189
 
 
190
 
#%module
191
 
#%  description: g.parser test script   
192
 
#%end
193
 
#%flag
194
 
#%  key: f
195
 
#%  description: A flag
196
 
#%end
197
 
#%option
198
 
#% key: raster
199
 
#% type: string
200
 
#% gisprompt: old,cell,raster
201
 
#% description: Raster input map
202
 
#% required : yes
203
 
#%end
204
 
#%option
205
 
#% key: vector
206
 
#% type: string
207
 
#% gisprompt: old,vector,vector
208
 
#% description: Vector input map
209
 
#% required : yes
210
 
#%end
211
 
#%option
212
 
#% key: option1
213
 
#% type: string
214
 
#% description: An option
215
 
#% required : no
216
 
#%end
217
 
 
218
 
if [ -z "$GISBASE" ] ; then
219
 
    echo "You must be in GRASS GIS to run this program." 1&gt;&amp;2
220
 
    exit 1
221
 
fi
222
 
 
223
 
if [ "$1" != "@ARGS_PARSED@" ] ; then
224
 
    exec g.parser "$0" "$@"
225
 
fi
226
 
 
227
 
#### add your code below ####
228
 
echo ""
229
 
 
230
 
if [ $GIS_FLAG_F -eq 1 ] ; then
231
 
    echo "Flag -f set"
232
 
else
233
 
    echo "Flag -f not set"
234
 
fi
235
 
 
236
 
# test if parameter present:
237
 
if [ -n "$GIS_OPT_OPTION1" ] ; then
238
 
    echo "Value of GIS_OPT_OPTION1: '$GIS_OPT_OPTION1'"
239
 
fi
240
 
 
241
 
echo "Value of GIS_OPT_RASTER: '$GIS_OPT_RASTER'"
242
 
echo "Value of GIS_OPT_VECTOR: '$GIS_OPT_VECTOR'"
243
 
 
244
 
</pre></div>
245
 
 
246
 
 
247
 
<h3>Example code for Python</h3>
248
 
 
249
 
<div class="code"><pre>
250
 
#!/usr/bin/env python
251
 
 
252
 
# g.parser demo script for python programing
253
 
 
254
 
#%module
255
 
#%  description: g.parser test script (python)
256
 
#%end
257
 
#%flag
258
 
#%  key: f
259
 
#%  description: A flag
260
 
#%end
261
 
#%option
262
 
#%  key: raster
263
 
#%  type: string
264
 
#%  gisprompt: old,cell,raster
265
 
#%  description: Raster input map
266
 
#%  required : yes
267
 
#%end
268
 
#%option
269
 
#%  key: vector
270
 
#%  type: string
271
 
#%  gisprompt: old,vector,vector
272
 
#%  description: Vector input map
273
 
#%  required : yes
274
 
#%end
275
 
#%option
276
 
#%  key: option1
277
 
#%  type: string
278
 
#%  description: An option
279
 
#%  required : no
280
 
#%end
281
 
 
282
 
import os
283
 
import sys
284
 
 
285
 
import grass.script as grass
286
 
 
287
 
def main():
288
 
    flag_f = flags['f']
289
 
    option1 = options['option1']
290
 
    raster = options['raster']
291
 
    vector = options['vector']
292
 
    #### add your code here ####
293
 
 
294
 
    if flag_f:
295
 
        print "Flag -f set"
296
 
    else:
297
 
        print "Flag -f not set"
298
 
 
299
 
    # test if parameter present:
300
 
    if option1:
301
 
        print "Value of option1= option: '%s'" % option1
302
 
 
303
 
    print "Value of raster= option: '%s'" % raster
304
 
    print "Value of vector= option: '%s'" % vector
305
 
 
306
 
    #### end of your code ####
307
 
 
308
 
    return 0
309
 
 
310
 
if __name__ == "__main__":
311
 
    options, flags = grass.parser()
312
 
    main()
313
 
</pre></div>
314
 
 
315
 
The <tt>test.py</tt> script will provide following help text:
316
 
 
317
 
<div class="code"><pre>
318
 
./test.py --help
319
 
 
320
 
Description:
321
 
 g.parser test script (python)
322
 
 
323
 
Usage:
324
 
 test1.py [-f] raster=string vector=string [option1=string]
325
 
   [--verbose] [--quiet]
326
 
 
327
 
Flags:
328
 
  -f   A flag
329
 
 --v   Verbose module output
330
 
 --q   Quiet module output
331
 
 
332
 
Parameters:
333
 
   raster   Raster input map
334
 
   vector   Vector input map
335
 
  option1   An option
336
 
</pre></div>
337
 
 
338
 
 
339
 
<h3>Example code for Perl</h3>
340
 
 
341
 
<div class="code"><pre>
342
 
#!/usr/bin/perl -w
343
 
use strict;
344
 
 
345
 
# g.parser demo script
346
 
 
347
 
#%module
348
 
#%  description: g.parser test script (perl) 
349
 
#%  keywords: keyword1, keyword2
350
 
#%end
351
 
#%flag
352
 
#%  key: f
353
 
#%  description: A flag
354
 
#%end
355
 
#%option
356
 
#% key: raster
357
 
#% type: string
358
 
#% gisprompt: old,cell,raster
359
 
#% description: Raster input map
360
 
#% required : yes
361
 
#%end
362
 
#%option
363
 
#% key: vector
364
 
#% type: string
365
 
#% gisprompt: old,vector,vector
366
 
#% description: Vector input map
367
 
#% required : yes
368
 
#%end
369
 
#%option
370
 
#% key: option1
371
 
#% type: string
372
 
#% description: An option
373
 
#% required : no
374
 
#%end
375
 
 
376
 
if ( !$ENV{'GISBASE'} ) {
377
 
    printf(STDERR  "You must be in GRASS GIS to run this program.\n");
378
 
    exit 1;
379
 
}
380
 
 
381
 
 
382
 
if( $ARGV[0] ne '@ARGS_PARSED@' ){
383
 
    my $arg = "";
384
 
    for (my $i=0; $i < @ARGV;$i++) {
385
 
        $arg .= " $ARGV[$i] ";
386
 
    }
387
 
    system("$ENV{GISBASE}/bin/g.parser $0 $arg");
388
 
    exit;
389
 
}
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
 
 
400
 
printf ("Value of GIS_OPT_option1: '%s'\n", $ENV{'GIS_OPT_OPTION1'});
401
 
printf ("Value of GIS_OPT_raster: '%s'\n", $ENV{'GIS_OPT_RASTER'});
402
 
printf ("Value of GIS_OPT_vect: '%s'\n", $ENV{'GIS_OPT_VECTOR'});
403
 
 
404
 
#### end of your code ####
405
 
 
406
 
</pre></div>
407
 
 
408
 
The <tt>test.pl</tt> script will provide a GUI and usage help text similar
409
 
to the other examples above.
410
 
 
411
 
 
412
 
<h2>SEE ALSO</h2>
413
 
 
414
 
<em>
415
 
  <a HREF="d.ask.html">d.ask</a>,
416
 
  <a HREF="d.menu.html">d.menu</a>,
417
 
  <a HREF="g.ask.html">g.ask</a>,
418
 
  <a HREF="g.filename.html">g.filename</a>,
419
 
  <a HREF="g.findfile.html">g.findfile</a>,
420
 
  <a HREF="g.tempfile.html">g.tempfile</a>,
421
 
</em>
422
 
 
423
 
and the <tt>SUBMITTING_SCRIPTS</tt> file in the GRASS source code.
424
 
<p>
425
 
Related Wiki pages:
426
 
<a href="http://grass.osgeo.org/wiki/Category:Linking_to_other_languages">Using GRASS with other programming languages</a>
427
 
 
428
 
<h2>AUTHOR</h2>
429
 
 
430
 
Glynn Clements
431
 
 
432
 
<p>
433
 
<i>Last changed: $Date: 2010-03-21 15:26:08 +0100 (Sun, 21 Mar 2010) $</i>
434
 
</body>
435
 
</html>