g.parser

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

If the -s switch is used, the options and flags are written to stdout in the form opt_<name>=<value> and flag_<name>=<value>, 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:

    #% 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, 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:

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

### 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: 2013-02-15 14:04:18 -0800 (Fri, 15 Feb 2013) $