Provided by: grass-doc_6.4.1-1ubuntu2_all bug

NAME

       g.parser

DESCRIPTION

       The  g.parser  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.

OPTIONS

       Unless the -s switch is used, the arguments are stored in environment variables for use in
       your scripts. These variables are named "GIS_FLAG_" for flags and "GIS_OPT_" for  options.
       The  names  of  variables  are  converted to upper case. For example if an option with key
       input was defined  in  the  script  header,  the  value  will  be  available  in  variable
       GIS_OPT_INPUT and the value of flag with key f will be available in variable GIS_FLAG_F.

       For flags, the value will be "1" if the flag was given, and "0" otherwise.

       If  the  -s  switch is used, the options and flags are written to stdout in the form opt_=
       and flag_=, preceded by the string @ARGS_PARSED@. If this string  doesn't  appear  as  the
       first  line  of  stdout,  it  indicates  that the script was invoked with a switch such as
       --html-description. In this case, the data written by g.parser to stdout should be  copied
       to the script's stdout verbatim.

       Typical header definitions are as follows:
       #%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

SYNOPSIS

       g.parser help
       g.parser [-s] [-t] filename [argument,...]

   Flags:
       -t
           Print strings for translation

       -s
           Write option values to stdout instead of reinvoking script

NOTES

       An option can be instructed to allow multiple inputs by adding the following line:
       While this will only directly change the Usage 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:

       for opt in $GIS_OPT_INPUT ; do
           ... "$opt"
       done

       A  "guisection"  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
       guisection field go into the "Options" tab.  For example:
       would put that option in a tab named tabname.

       A "<tt>key_desc" field may be added to each option to specify the text that
       appears in the module's usage help section. For example:

       added to an input option would create the usage summary
       <tt>[input=filename].

       If a script is run with --o, G_parser() will
       set <tt>GRASS_OVERWRITE=1, 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 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 and/or
       <tt>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.

AUTOMATED SCRIPT CREATION

       The flag --script added to a GRASS command, generates shell
       output. To write out a g.parser boilerplate for easy
       prototyping of shell scripts, the flag --script can be added
       to any GRASS command. Example:

       v.in.db --script

Help page template (HTML)

       The  flag  --html-description  added  to  a  GRASS  command  generates a related help page
       template in HTML. Example:
       v.in.db --html-description

GUI window parser (XML)

       The flag --interface-description added to a GRASS command generates a  related  help  page
       template in XML. Example:
       v.in.db --interface-description

GUI window parser (Tcl/Tk)

       The  flag --tcltk added to a GRASS command generates Tcl/Tk code suitable for building the
       GUI interface. Example:
       v.in.db --tcltk

TRANSLATION

       g.parser provides some support for translating the options of scripts. If called with  the
       -t switch before the script filename like this
       g.parser -t somescriptfile
         g.parser  will  print  the text of the translatable options to stdout, one per line, and
       exit. This is for internal use within the  build  system  to  prepare  GRASS  scripts  for
       translation.

EXAMPLES

   Example code for SHELL

       #!/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>&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'"

   Example code for Python

       #!/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()
        The test.py script will provide following help text:
       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

   Example code for Perl

       #!/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 ####
         The  test.pl script will provide a GUI and usage help text similar to the other examples
       above.

SEE ALSO

        d.ask, d.menu, g.ask, g.filename, g.findfile, g.tempfile, and the SUBMITTING_SCRIPTS file
       in the GRASS source code.

       Related Wiki pages: Using GRASS with other programming languages

AUTHOR

       Glynn Clements

       Last changed: $Date: 2010-09-18 21:41:19 +0200 (Sat, 18 Sep 2010) $