[GRASS-SVN] r38394 - grass/trunk/general/g.parser

svn_grass at osgeo.org svn_grass at osgeo.org
Mon Jul 13 11:03:45 EDT 2009


Author: martinl
Date: 2009-07-13 11:03:45 -0400 (Mon, 13 Jul 2009)
New Revision: 38394

Modified:
   grass/trunk/general/g.parser/g.parser.html
Log:
manual page updated


Modified: grass/trunk/general/g.parser/g.parser.html
===================================================================
--- grass/trunk/general/g.parser/g.parser.html	2009-07-13 15:00:42 UTC (rev 38393)
+++ grass/trunk/general/g.parser/g.parser.html	2009-07-13 15:03:45 UTC (rev 38394)
@@ -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_&lt;NAME&gt;" for flags and
-"GIS_OPT_&lt;NAME&gt;" 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_&lt;NAME&gt;"
+for flags and "GIS_OPT_&lt;NAME&gt;" 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,70 +76,61 @@
 <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>TRANSLATION</h2>
 
-The flag <em>--tcltk</em> added to a GRASS command, generates a
-a XML description of the GUI interface. Example
+<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>
-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
-
-<div class="code"><pre>
 g.parser -t somescriptfile
 </pre></div>
 
@@ -144,9 +138,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 +147,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 +207,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 +242,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 &gt;&gt; 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 +299,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 +360,21 @@
 
 </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="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