GRASS logo
     __________________________________________________________________

ÐÐÐÐÐÐÐÐ

   g.parser

ÐÐÐСÐÐÐÐ

   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.

ÐÐÐ ÐÐÐТРЫ

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

   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

ÐÐ ÐÐÐЧÐÐÐЯ

   An option can be instructed to allow multiple inputs by adding the
   following line:
#% multiple : yes

   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:

IFS=,
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:
#% guisection: tabname

   would put that option in a tab named tabname.

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

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

   If a script is run with --o, G_parser() will set 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 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
   $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.

AUTOMATED SCRIPT CREATION

   The flag --script added to a GRASS command, 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

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.

ÐÐ ÐÐÐРЫ

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

def main():

    #### add your code here ####

    print ""

    if ( os.getenv('GIS_FLAG_F') == "1" ):
        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')

    print "Value of GIS_OPT_RASTER: '%s'" % os.getenv('GIS_OPT_RASTER')
    print "Value of GIS_OPT_VECTOR: '%s'" % os.getenv('GIS_OPT_VECTOR')

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

if __name__ == "__main__":

    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();


   The test.py script will provide following help text:

./test.py --help

Description:
 g.parser test script (python)

Usage:
 test.sh [-f] option=name

Flags:
  -f   a flag

Parameters:
  option   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 following help text:

./test.pl --help

Description:
 g.parser test script (perl)

Usage:
 test.sh [-f] option=name

Flags:
  -f   a flag

Parameters:
  option   an option

СÐ. ТÐÐÐÐ

   [1]d.ask, [2]d.menu, [3]g.ask, [4]g.filename, [5]g.findfile,
   [6]g.tempfile, and the SUBMITTING_SCRIPTS file in the GRASS source
   code.

ÐÐТÐÐ

   Glynn Clements

   Last changed: $Date: 2007-07-16 04:19:50 -0500 (Ðн, 16 иÑл 2007) $

ÐвÑÐ¾Ñ Ð¿ÐµÑевода

References

   1. file://localhost/root/tmp/2/fin/d.ask.html
   2. file://localhost/root/tmp/2/fin/d.menu.html
   3. file://localhost/root/tmp/2/fin/g.ask.html
   4. file://localhost/root/tmp/2/fin/g.filename.html
   5. file://localhost/root/tmp/2/fin/g.findfile.html
   6. file://localhost/root/tmp/2/fin/g.tempfile.html