RONCC
/
Geografic-Information-System


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436
							<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>g.parser</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">

<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>


<h2>NAME</h2>
<em><b>g.parser</b></em>

<h2>SYNOPSIS</h2>
<b>g.parser help</b><br>
<b>g.parser</b> [-<b>s</b>] [-<b>t</b>] <em>filename</em> [<em>argument</em>,...]

<h3>Flags:</h3>
<dl>
<dt><b>-t</b></dt>
<dd>Print strings for translation</dd>
<dt><b>-s</b></dt>
<dd>Write option values to stdout instead of reinvoking script</dd>
</dl>

<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.


<h2>OPTIONS</h2>

Unless the <b>-s</b> switch is used, 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>If the <b>-s</b> switch is used, the options and flags are written to
stdout in the form <em>opt_&lt;name&gt;=&lt;value&gt;</em> and
<em>flag_&lt;name&gt;=&lt;value&gt;</em>, preceded by the string
<b>@ARGS_PARSED@</b>. If this string doesn't appear as the first line
of stdout, it indicates that the script was invoked with a switch such
as <b>--html-description</b>. In this case, the data written by
<em>g.parser</em> to stdout should be copied to the script's stdout
verbatim.

<p>Typical header definitions are as follows:

<div class="code"><pre>
#%module
#% description: g.parser test script   
#%end
#%flag
#% key: f
#% description: A flag
#%end
#%option
#% key: raster
#% type: string
#% gisprompt: old,cell,raster
#% description: Raster input map
#% required : yes
#%end
</pre></div>

With <tt>{NULL}</tt> it is possible to suppress a predefined <tt>description</tt>
or <tt>label</tt>.

<h2>NOTES</h2>

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
a script. For example, individual comma separated identities for an option 
named "input" can be parsed with the following Bash shell code:

<div class="code"><pre>IFS=,
for opt in $GIS_OPT_INPUT ; do
    ... "$opt"
done
</pre></div>

<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.
For example:
<pre>#% guisection: tabname</pre>
would put that option in a tab named <i>tabname</i>.

<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 <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>

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>

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>

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>Web Processing Service (WPS)</h2>

The flag <b>--wps-process-description</b> added to a GRASS command
generates a Web Processing Service process description. Example:

<div class="code"><pre>
v.in.db --wps-process-description
</pre></div>

<h2>reStructuredText (REST)</h2>

The flag <b>--rest-description</b> added to a GRASS command
generates a related help page template in reStructuredText. Example:

<div class="code"><pre>
v.in.db --rest-description
</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>

<em>g.parser</em> will print the text of the translatable options to
<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>

<h3>Example code for SHELL</h3>

<div class="code"><pre>
#!/bin/sh

# g.parser demo script for shell programing

#%module
#%  description: g.parser test script   
#%end
#%flag
#%  key: f
#%  description: A flag
#%end
#%option
#% key: raster
#% type: string
#% gisprompt: old,cell,raster
#% description: Raster input map
#% required : yes
#%end
#%option
#% key: vector
#% type: string
#% gisprompt: old,vector,vector
#% description: Vector input map
#% required : yes
#%end
#%option
#% key: option1
#% type: string
#% description: An option
#% required : no
#%end

if [ -z "$GISBASE" ] ; then
    echo "You must be in GRASS GIS to run this program." 1&gt;&amp;2
    exit 1
fi

if [ "$1" != "@ARGS_PARSED@" ] ; then
    exec g.parser "$0" "$@"
fi

#### add your code below ####
echo ""

if [ $GIS_FLAG_F -eq 1 ] ; then
    echo "Flag -f set"
else
    echo "Flag -f not set"
fi

# test if parameter present:
if [ -n "$GIS_OPT_OPTION1" ] ; then
    echo "Value of GIS_OPT_OPTION1: '$GIS_OPT_OPTION1'"
fi

echo "Value of GIS_OPT_RASTER: '$GIS_OPT_RASTER'"
echo "Value of GIS_OPT_VECTOR: '$GIS_OPT_VECTOR'"

</pre></div>


<h3>Example code for Python</h3>

<div class="code"><pre>
#!/usr/bin/env python

# g.parser demo script for python programing

#%module
#%  description: g.parser test script (python)
#%end
#%flag
#%  key: f
#%  description: A flag
#%end
#%option
#%  key: raster
#%  type: string
#%  gisprompt: old,cell,raster
#%  description: Raster input map
#%  required : yes
#%end
#%option
#%  key: vector
#%  type: string
#%  gisprompt: old,vector,vector
#%  description: Vector input map
#%  required : yes
#%end
#%option
#%  key: option1
#%  type: string
#%  description: An option
#%  required : no
#%end

import os
import sys

import grass.script as grass

def main():
    flag_f = flags['f']
    option1 = options['option1']
    raster = options['raster']
    vector = options['vector']
    #### add your code here ####

    if flag_f:
        print "Flag -f set"
    else:
        print "Flag -f not set"

    # test if parameter present:
    if option1:
        print "Value of option1= option: '%s'" % option1

    print "Value of raster= option: '%s'" % raster
    print "Value of vector= option: '%s'" % vector

    #### end of your code ####

    return 0

if __name__ == "__main__":
    options, flags = grass.parser()
    main()
</pre></div>

The <tt>test.py</tt> script will provide following help text:

<div class="code"><pre>
./test.py --help

Description:
 g.parser test script (python)

Usage:
 test1.py [-f] raster=string vector=string [option1=string]
   [--verbose] [--quiet]

Flags:
  -f   A flag
 --v   Verbose module output
 --q   Quiet module output

Parameters:
   raster   Raster input map
   vector   Vector input map
  option1   An option
</pre></div>


<h3>Example code for Perl</h3>

<div class="code"><pre>
#!/usr/bin/perl -w
use strict;

# g.parser demo script

#%module
#%  description: g.parser test script (perl) 
#%  keywords: keyword1, keyword2
#%end
#%flag
#%  key: f
#%  description: A flag
#%end
#%option
#% key: raster
#% type: string
#% gisprompt: old,cell,raster
#% description: Raster input map
#% required : yes
#%end
#%option
#% key: vector
#% type: string
#% gisprompt: old,vector,vector
#% description: Vector input map
#% required : yes
#%end
#%option
#% key: option1
#% type: string
#% description: An option
#% required : no
#%end

if ( !$ENV{'GISBASE'} ) {
    printf(STDERR  "You must be in GRASS GIS to run this program.\n");
    exit 1;
}

 
if( $ARGV[0] ne '@ARGS_PARSED@' ){
    my $arg = "";
    for (my $i=0; $i < @ARGV;$i++) {
        $arg .= " $ARGV[$i] ";
    }
    system("$ENV{GISBASE}/bin/g.parser $0 $arg");
    exit;
}

#### add your code here ####
print  "\n";
if ( $ENV{'GIS_FLAG_F'} eq "1" ){
   print "Flag -f set\n"
}
else {
   print "Flag -f not set\n"
}

printf ("Value of GIS_OPT_option1: '%s'\n", $ENV{'GIS_OPT_OPTION1'});
printf ("Value of GIS_OPT_raster: '%s'\n", $ENV{'GIS_OPT_RASTER'});
printf ("Value of GIS_OPT_vect: '%s'\n", $ENV{'GIS_OPT_VECTOR'});

#### end of your code ####

</pre></div>

The <tt>test.pl</tt> script will provide a GUI and usage help text similar
to the other examples above.


<h2>SEE ALSO</h2>

<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>

and the <tt>SUBMITTING_SCRIPTS</tt> file in the GRASS source code.
<p>Related Wiki pages: 
<a href="http://grasswiki.osgeo.org/wiki/Category:Linking_to_other_languages">Using GRASS with other programming languages</a>

<h2>AUTHOR</h2>

Glynn Clements

<p><i>Last changed: $Date$</i>
</body>
</html>