1g.parser(1) Grass User's Manual g.parser(1)
2
6 g.parser
7
9 The g.parser module provides full parser support for GRASS scripts,
10 including an auto-generated GUI interface, help page template, and com‐
11 mand line option checking. In this way a simple script can very quickly
12 be made into a full-fledged GRASS module.
13
15 After parsing the arguments are stored in environment variables for use
16 in your scripts. These variables are named "GIS_FLAG_" for flags and
17 "GIS_OPT_" for options. The names of variables are converted to upper
18 case. For example if an option with key input was defined in the script
19 header, the value will be available in variable GIS_OPT_INPUT and the
20 value of flag with key f will be available in variable GIS_FLAG_F.
21 For flags, the value will be "1" if the flag was given, and "0" other‐
23 wise.
24 Typical header definitions are as follows:
26 #%Module
27 #% description: g.parser test script
28 #%End
29 #%flag
30 #% key: f
31 #% description: A flag
32 #%end
33 #%option
34 #% key: raster
35 #% type: string
36 #% gisprompt: old,cell,raster
37 #% description: Raster input map
38 #% required : yes
39 #%end
40
43 An option can be instructed to allow multiple inputs by adding the fol‐
44 lowing line:
45 While this will only directly change the Usage section of the help
46 screen, the option's environmental string may be easily parsed from
47 within
48 a script. For example, individual comma separated identities for an
49 option
50 named "input" can be parsed with the following Bash shell code:
51 for opt in $GIS_OPT_INPUT ; do
53 ... "$opt"
54 done
55 A "guisection" field may be added to each option and flag to specify
58 that the options should appear in multiple tabs in the auto-generated
59 GUI. Any options without a guisection field go into the "Options" tab.
60 For example:
61 would put that option in a tab named tabname.
62 A "<tt>key_desc" field may be added to each option to specify the text
64 that
65 appears in the module's usage help section. For example:
66 added to an input option would create the usage summary
68 <tt>[input=filename].
69 If a script is run with --o, G_parser() will set <tt>GRASS_OVERWRITE=1,
71 which has the same effect as passing --o to every module which is run
72 from the script.
73 Similarly, passing --q or --v will set <tt>GRASS_VERBOSE to 0 or 3
74 respectively, which has the same effect as passing --q or --v to every
75 module which is run from the script.
76 Rather than checking whether --o, --q or --v were used, you should be
77 checking $GRASS_OVERWRITE and/or $GRASS_VERBOSE instead. If those
78 variables are set, the script should behave the same way regardless of
79 whether they were set by --o, --q or --v being passed to the script or
80 set by other means.
81
83 The flag --script added to a GRASS command,
84 To write out a g.parser boilerplate for easy prototyping of shell
85 scripts, the flag --script can be added to any GRASS command. Example:
86 v.in.db --script
88
91 g.parser provides some support for translating the options of scripts.
92 If called with the -t switch before the script filename like this
93 g.parser -t somescriptfile
94 g.parser will print the text of the translatable options to stdout,
95 one per line, and exit. This is for internal use within the build sys‐
96 tem to prepare GRASS scripts for translation.
97
99 Example code for SHELL
100 #!/bin/sh
102 # g.parser demo script for shell programing
103 #%Module
104 #% description: g.parser test script
105 #%End
106 #%flag
107 #% key: f
108 #% description: A flag
109 #%END
110 #%option
111 #% key: raster
112 #% type: string
113 #% gisprompt: old,cell,raster
114 #% description: Raster input map
115 #% required : yes
116 #%end
117 #%option
118 #% key: vector
119 #% type: string
120 #% gisprompt: old,vector,vector
121 #% description: Vector input map
122 #% required : yes
123 #%end
124 #%option
125 #% key: option1
126 #% type: string
127 #% description: An option
128 #% required : no
129 #%end
130 if [ -z "$GISBASE" ] ; then
131 echo "You must be in GRASS GIS to run this program." 1>&2
132 exit 1
133 fi
134 if [ "$1" != "@ARGS_PARSED@" ] ; then
135 exec g.parser "$0" "$@"
136 fi
137 #### add your code below ####
138 echo ""
139 if [ $GIS_FLAG_F -eq 1 ] ; then
140 echo "Flag -f set"
141 else
142 echo "Flag -f not set"
143 fi
144 # test if parameter present:
145 if [ -n "$GIS_OPT_OPTION1" ] ; then
146 echo "Value of GIS_OPT_OPTION1: '$GIS_OPT_OPTION1'"
147 fi
148 echo "Value of GIS_OPT_RASTER: '$GIS_OPT_RASTER'"
149 echo "Value of GIS_OPT_VECTOR: '$GIS_OPT_VECTOR'"
150 Example code for Python
153 #!/usr/bin/python
155 # g.parser demo script for python programing
156 #%Module
157 #% description: g.parser test script (python)
158 #%End
159 #%flag
160 #% key: f
161 #% description: A flag
162 #%END
163 #%option
164 #% key: raster
165 #% type: string
166 #% gisprompt: old,cell,raster
167 #% description: Raster input map
168 #% required : yes
169 #%end
170 #%option
171 #% key: vector
172 #% type: string
173 #% gisprompt: old,vector,vector
174 #% description: Vector input map
175 #% required : yes
176 #%end
177 #%option
178 #% key: option1
179 #% type: string
180 #% description: An option
181 #% required : no
182 #%end
183 import os
184 import sys
185 def main():
186 #### add your code here ####
187 print ""
188 if ( os.getenv('GIS_FLAG_F') == "1" ):
189 print "Flag -f set"
190 else:
191 print "Flag -f not set"
192 # test if parameter present:
193 if ( os.getenv("GIS_OPT_OPTION1") != "" ):
194 print "Value of GIS_OPT_OPTION1: '%s'" %
195 os.getenv('GIS_OPT_OPTION1')
196 print "Value of GIS_OPT_RASTER: '%s'" % os.getenv('GIS_OPT_RASTER')
197 print "Value of GIS_OPT_VECTOR: '%s'" % os.getenv('GIS_OPT_VECTOR')
198 #### end of your code ####
199 return
200 if __name__ == "__main__":
201 if !os.getenv("GISBASE"):
202 print >> sys.stderr, "You must be in GRASS GIS to run this pro‐
203 gram."
204 sys.exit(0)
205 if ( len(sys.argv) <= 1 or sys.argv[1] != "@ARGS_PARSED@" ):
206 os.execvp("g.parser", [sys.argv[0]] + sys.argv)
207 else:
208 main();
209 The test.py script will provide following help text:
212 Description:
215 g.parser test script (python)
216 Usage:
218 test.sh [-f] option=name
219 Flags:
221 -f a flag
222 Parameters:
224 option an option
225 Example code for Perl
228 #!/usr/bin/perl -w
230 use strict;
231 # g.parser demo script
232 #%Module
233 #% description: g.parser test script (perl)
234 #% keywords: keyword1, keyword2
235 #%End
236 #%flag
237 #% key: f
238 #% description: A flag
239 #%END
240 #%option
241 #% key: raster
242 #% type: string
243 #% gisprompt: old,cell,raster
244 #% description: Raster input map
245 #% required : yes
246 #%end
247 #%option
248 #% key: vector
249 #% type: string
250 #% gisprompt: old,vector,vector
251 #% description: Vector input map
252 #% required : yes
253 #%end
254 #%option
255 #% key: option1
256 #% type: string
257 #% description: An option
258 #% required : no
259 #%end
260 if ( !$ENV{'GISBASE'} ) {
261 printf(STDERR "You must be in GRASS GIS to run this program.\n");
262 exit 1;
263 }
264 if( $ARGV[0] ne '@ARGS_PARSED@' ){
266 my $arg = "";
267 for (my $i=0; $i < @ARGV;$i++) {
268 $arg .= " $ARGV[$i] ";
269 }
270 system("$ENV{GISBASE}/bin/g.parser $0 $arg");
271 exit;
272 }
273 #### add your code here ####
274 print "\n";
275 if ( $ENV{'GIS_FLAG_F'} eq "1" ){
276 print "Flag -f set\n"
277 }
278 else {
279 print "Flag -f not set\n"
280 }
281 printf ("Value of GIS_OPT_option1: '%s'\n", $ENV{'GIS_OPT_OPTION1'});
282 printf ("Value of GIS_OPT_raster: '%s'\n", $ENV{'GIS_OPT_RASTER'});
283 printf ("Value of GIS_OPT_vect: '%s'\n", $ENV{'GIS_OPT_VECTOR'});
284 #### end of your code ####
285 The test.pl script will provide following help text:
288 Description:
291 g.parser test script (perl)
292 Usage:
294 test.sh [-f] option=name
295 Flags:
297 -f a flag
298 Parameters:
300 option an option
301
304 d.ask, d.menu, g.ask, g.filename, g.findfile, g.tempfile, and the SUB‐
305 MITTING_SCRIPTS file in the GRASS source code.
306
308 Glynn Clements
309 Last changed: $Date: 2007-07-16 11:19:50 +0200 (Mon, 16 Jul 2007) $
311GRASS 6.3.0 g.parser(1)