[GRASS-SVN] r38395 - grass/branches/develbranch_6/general/g.parser
svn_grass at osgeo.org
svn_grass at osgeo.org
Mon Jul 13 11:08:30 EDT 2009
Author: martinl
Date: 2009-07-13 11:08:30 -0400 (Mon, 13 Jul 2009)
New Revision: 38395
Modified:
grass/branches/develbranch_6/general/g.parser/description.html
Log:
manual page updated
Modified: grass/branches/develbranch_6/general/g.parser/description.html
===================================================================
--- grass/branches/develbranch_6/general/g.parser/description.html 2009-07-13 15:03:45 UTC (rev 38394)
+++ grass/branches/develbranch_6/general/g.parser/description.html 2009-07-13 15:08:30 UTC (rev 38395)
@@ -12,31 +12,33 @@
<h2>NAME</h2>
<em><b>g.parser</b></em>
-<H2>DESCRIPTION</H2>
+<h2>DESCRIPTION</h2>
-The <em>g.parser</em> module provides full parser support for GRASS scripts,
-including an auto-generated GUI interface, help page template, and command
-line option checking. In this way a simple script can very quickly be made
-into a full-fledged GRASS module.
-<P>
+The <em>g.parser</em> module provides full parser support for GRASS
+scripts, including an auto-generated GUI interface, help page
+template, and command line option checking. In this way a simple
+script can very quickly be made into a full-fledged GRASS module.
-<H2>OPTIONS</H2>
+<h2>OPTIONS</h2>
-After parsing the arguments are stored in environment variables for use in your
-scripts. These variables are named "GIS_FLAG_<NAME>" for flags and
-"GIS_OPT_<NAME>" for options.
-The names of variables are converted to upper case. For example if an option
-with key <b>input</b> was defined in the script header, the value will be
-available in variable <b>GIS_OPT_INPUT</b> and the value of flag with key <b>f</b>
-will be available in variable <b>GIS_FLAG_F</b>.
-<P>
+After parsing the arguments are stored in environment variables for
+use in your scripts. These variables are named "GIS_FLAG_<NAME>"
+for flags and "GIS_OPT_<NAME>" for options. The names of
+variables are converted to upper case. For example if an option with
+key <b>input</b> was defined in the script header, the value will be
+available in variable <b>GIS_OPT_INPUT</b> and the value of flag with
+key <b>f</b> will be available in variable <b>GIS_FLAG_F</b>.
+
+<p>
For flags, the value will be "1" if the flag was given, and "0" otherwise.
-<P>
+
+<p>
Typical header definitions are as follows:
+
<div class="code"><pre>
-#%Module
+#%module
#% description: g.parser test script
-#%End
+#%end
#%flag
#% key: f
#% description: A flag
@@ -50,9 +52,10 @@
#%end
</pre></div>
-<H2>NOTES</H2>
+<h2>NOTES</h2>
-An option can be instructed to allow multiple inputs by adding the following line:
+An option can be instructed to allow multiple inputs by adding the
+following line:
<pre>#% multiple : yes</pre>
While this will only directly change the <i>Usage</i> section of the help
screen, the option's environmental string may be easily parsed from within
@@ -65,7 +68,7 @@
done
</pre></div>
-<P>
+<p>
A "<tt>guisection</tt>" field may be added to each option and flag to specify
that the options should appear in multiple tabs in the auto-generated GUI.
Any options without a <tt>guisection</tt> field go into the "Options" tab.
@@ -73,69 +76,65 @@
<pre>#% guisection: tabname</pre>
would put that option in a tab named <i>tabname</i>.
-<P>
+<p>
A "<tt>key_desc</tt>" field may be added to each option to specify the text that
appears in the module's usage help section. For example:
<pre>#% key_desc: filename</pre>
added to an <b>input</b> option would create the usage summary
<tt>[input=filename]</tt>.
-<P>
-If a script is run with --o, G_parser() will set <tt>GRASS_OVERWRITE=1</tt>,
-which has the same effect as passing --o to every module which is run
-from the script.
-Similarly, passing --q or --v will set <tt>GRASS_VERBOSE</tt> to 0 or 3
-respectively, which has the same effect as passing --q or --v to every
-module which is run from the script.
-Rather than checking whether --o, --q or --v were used, you should be
-checking $GRASS_OVERWRITE and/or $GRASS_VERBOSE instead. If those
-variables are set, the script should behave the same way regardless of
-whether they were set by --o, --q or --v being passed to the script or
-set by other means.
+<p>
+If a script is run with --o, G_parser() will
+set <tt>GRASS_OVERWRITE=1</tt>, which has the same effect as passing
+--o to every module which is run from the script. Similarly, passing
+--q or --v will set <tt>GRASS_VERBOSE</tt> to 0 or 3 respectively,
+which has the same effect as passing --q or --v to every module which
+is run from the script. Rather than checking whether --o, --q or --v
+were used, you should be checking <tt>GRASS_OVERWRITE</tt> and/or
+<tt>GRASS_VERBOSE</tt> instead. If those variables are set, the
+script should behave the same way regardless of whether they were set
+by --o, --q or --v being passed to the script or set by other means.
-<H2>AUTOMATED SCRIPT CREATION</H2>
+<h2>AUTOMATED SCRIPT CREATION</h2>
-The flag <em>--script</em> added to a GRASS command, generates shell output.
-To write out a <em>g.parser</em> boilerplate for easy prototyping of shell
-scripts, the flag <em>--script</em> can be added to any GRASS command. Example:
+The flag <b>--script</b> added to a GRASS command, generates shell
+output. To write out a <em>g.parser</em> boilerplate for easy
+prototyping of shell scripts, the flag <b>--script</b> can be added
+to any GRASS command. Example:
<div class="code"><pre>
v.in.db --script
</pre></div>
-<H2>Help page template (HTML)</H2>
+<h2>Help page template (HTML)</h2>
-The flag <em>--html-description</em> added to a GRASS command, generates a
-related help page template in HTML. Example:
+The flag <b>--html-description</b> added to a GRASS command,
+generates a related help page template in HTML. Example:
<div class="code"><pre>
v.in.db --html-description
</pre></div>
-<H2>GUI window parser (XML)</H2>
+<h2>GUI window parser (XML)</h2>
-The flag <em>--interface-description</em> added to a GRASS command, generates a
-related help page template in XML. Example:
+The flag <b>--interface-description</b> added to a GRASS command,
+generates a related help page template in XML. Example:
<div class="code"><pre>
v.in.db --interface-description
</pre></div>
-<H2>GUI window parser (TclTk)</H2>
+-<h2>GUI window parser (TclTk)</h2>
-The flag <em>--tcltk</em> added to a GRASS command, generates a
-a XML description of the GUI interface. Example
+The flag <b>--tcltk</b> added to a GRASS command, generates a a XML
+description of the GUI interface. Example
-<div class="code"><pre>
-v.in.db --tcltk
-</pre></div>
+<h2>TRANSLATION</h2>
+<em>g.parser</em> provides some support for translating the options of
+scripts. If called with the -t switch before the script filename like
+this
-<H2>TRANSLATION</h2>
-
-<em>g.parser</em> provides some support for translating the options of scripts.
-If called with the -t switch before the script filename like this
-
<div class="code"><pre>
g.parser -t somescriptfile
</pre></div>
@@ -144,9 +143,8 @@
<tt>stdout</tt>, one per line, and exit. This is for internal use within
the build system to prepare GRASS scripts for translation.
+<h2>EXAMPLES</h2>
-<H2>EXAMPLES</H2>
-
<h3>Example code for SHELL</h3>
<div class="code"><pre>
@@ -154,13 +152,13 @@
# g.parser demo script for shell programing
-#%Module
+#%module
#% description: g.parser test script
-#%End
+#%end
#%flag
#% key: f
#% description: A flag
-#%END
+#%end
#%option
#% key: raster
#% type: string
@@ -214,17 +212,17 @@
<h3>Example code for Python</h3>
<div class="code"><pre>
-#!/usr/bin/python
+#!/usr/bin/env python
# g.parser demo script for python programing
-#%Module
+#%module
#% description: g.parser test script (python)
-#%End
+#%end
#%flag
#% key: f
#% description: A flag
-#%END
+#%end
#%option
#% key: raster
#% type: string
@@ -249,60 +247,55 @@
import os
import sys
-def main():
+import grass.script as grass
+def main():
#### add your code here ####
- print ""
-
- if ( os.getenv('GIS_FLAG_F') == "1" ):
+ if flags['f']:
print "Flag -f set"
else:
print "Flag -f not set"
# test if parameter present:
- if ( os.getenv("GIS_OPT_OPTION1") != "" ):
- print "Value of GIS_OPT_OPTION1: '%s'" % os.getenv('GIS_OPT_OPTION1')
+ if options['option1']:
+ print "Value of GIS_OPT_OPTION1: '%s'" % options['option1']
- print "Value of GIS_OPT_RASTER: '%s'" % os.getenv('GIS_OPT_RASTER')
- print "Value of GIS_OPT_VECTOR: '%s'" % os.getenv('GIS_OPT_VECTOR')
+ print "Value of GIS_OPT_RASTER: '%s'" % options['raster']
+ print "Value of GIS_OPT_VECTOR: '%s'" % options['vector']
#### end of your code ####
- return
-if __name__ == "__main__":
+ return 0
- if !os.getenv("GISBASE"):
- print >> sys.stderr, "You must be in GRASS GIS to run this program."
- sys.exit(0)
-
- if ( len(sys.argv) <= 1 or sys.argv[1] != "@ARGS_PARSED@" ):
- os.execvp("g.parser", [sys.argv[0]] + sys.argv)
- else:
- main();
-
+if __name__ == "__main__":
+ options, flags = grass.parser()
+ sys.exit(main())
</pre></div>
-<P>
The <tt>test.py</tt> script will provide following help text:
-<P>
+
<div class="code"><pre>
./test.py --help
Description:
g.parser test script (python)
-
+
Usage:
- test.sh [-f] option=name
-
+ test1.py [-f] raster=string vector=string [option1=string]
+ [--verbose] [--quiet]
+
Flags:
- -f a flag
-
+ -f A flag
+ --v Verbose module output
+ --q Quiet module output
+
Parameters:
- option an option
+ raster Raster input map
+ vector Vector input map
+ option1 An option
</pre></div>
-
<h3>Example code for Perl</h3>
<div class="code"><pre>
@@ -311,14 +304,14 @@
# g.parser demo script
-#%Module
+#%module
#% description: g.parser test script (perl)
#% keywords: keyword1, keyword2
-#%End
+#%end
#%flag
#% key: f
#% description: A flag
-#%END
+#%end
#%option
#% key: raster
#% type: string
@@ -372,45 +365,24 @@
</pre></div>
+<h2>SEE ALSO</h2>
-<P>
-The <tt>test.pl</tt> script will provide following help text:
-<P>
-<div class="code"><pre>
-./test.pl --help
+<em>
+ <a HREF="d.ask.html">d.ask</a>,
+ <a HREF="d.menu.html">d.menu</a>,
+ <a HREF="g.ask.html">g.ask</a>,
+ <a HREF="g.filename.html">g.filename</a>,
+ <a HREF="g.findfile.html">g.findfile</a>,
+ <a HREF="g.tempfile.html">g.tempfile</a>,
+</em>
-Description:
- g.parser test script (perl)
-
-Usage:
- test.sh [-f] option=name
-
-Flags:
- -f a flag
-
-Parameters:
- option an option
-</pre></div>
-
-
-<H2>SEE ALSO</H2>
-
-<EM>
-<A HREF="d.ask.html">d.ask</A>,
-<A HREF="d.menu.html">d.menu</A>,
-<A HREF="g.ask.html">g.ask</A>,
-<A HREF="g.filename.html">g.filename</A>,
-<A HREF="g.findfile.html">g.findfile</A>,
-<A HREF="g.tempfile.html">g.tempfile</A>,
-</EM>
and the <tt>SUBMITTING_SCRIPTS</tt> file in the GRASS source code.
+<h2>AUTHOR</h2>
-<H2>AUTHOR</H2>
-
Glynn Clements
+
<p>
<i>Last changed: $Date$</i>
-</p>
</body>
</html>
More information about the grass-commit
mailing list