Command Line Parsing

Table of Contents

• Introduction
• Description
• Parser interface
  • Option structure
  • Flag structure
  • Running Parser
  • Additional checks of command line parameters
  • Multiple answer default values
  • Disabling interactive mode
• Parser Programming Examples
  • Step by Step Use of the Parser
    • Allocate memory for Flags and Options
    • Define members of Flag and Option structures
    • Call the parser
    • Extracting information from the parser structures
    • Running the example program
  • Full Module Example
• Complete Structure Members Table
  • struct Flag
  • struct Option
• Description of Complex Structure Members
  • Answer member of the Flag and Option structures
  • Multiple and Answers Members
  • key_desc Member
  • gisprompt Member
• Standard options and flags
• Command line parsing FAQ

Introduction

This section describes a standard mechanism for command line parsing in GRASS. The system is usually referred as parser, G_parser() or g.parser (because of the related g.parser module). Use of the provided set of functions will standardize GRASS modules that expect command line arguments, creating a family of GRASS modules that is easy for users to learn.

The standardization is important because as soon as a GRASS user familiarizes himself with the general form of command line input as defined by the parser, it will greatly simplify the necessity of remembering or at least guessing the required command line arguments for any GRASS command. It is strongly recommended, almost mandatory, that GRASS programmers use this set of functions for all command line parsing. With their use, the programmer is freed from the burden of generating user interface code for every command. The parser will limit the programmer to a pre-defined look and feel, but limiting the interface is well worth the shortened user learning curve. Moreover, system enables to generate module interface descriptions which can be used by GUI to generate a graphical interface for a module.

Note

There are also standard options and flags, which ensure even better standardization of names, values and descriptions.

Description

The GRASS parser is the collection of functions and structures defined in the GRASS gis.h header file. These structures and functions allow the programmer to define the options and flags that make up the valid command line input of a GRASS command.

The parser functions behave in one of three ways:

• If no command line arguments are entered by the user, the parser searches for a completely interactive version of the command. If the interactive version is found, control is passed over to that version.

• If command line arguments are entered but they are a subset of the options and flags that the programmer has defined as required arguments, three things happen. The parser will pass an error message to the user indicating which required options and/or flags were missing from the command line, the parser will then display a complete usage message for that command, and finally the parser will terminate the command.

• If all necessary options and flags are entered on the command line by the user, the parser executes the command with the given options and flags.

Note

Python modules uses the same system but instead of functions and structures, comments in files are used to define options and flags.

Parser interface

The parser functions described below use two structures as defined in the GRASS gis.h header file.

This is a basic list of members of the Option and Flag structures. A comprehensive description of all elements of these two structures and their possible values can be found in Complete Structure Members Table.

Option structure

The basic usage of the Option structure is as follows. You declare a pointer to the Option structure.

struct Option *opt;

And then you call G_define_option() function, which allocates memory for the Option structure and returns a pointer to it.

opt = G_define_option();

Then you set the structure members, basic members are:

• key - The option name on the command line.
• description - The option description to display to the user.
• type - Variable type of the user's answer to the option.
• required - Whether this option is mandatory or not.

For the full list of members see the Option structure documentation.

Flag structure

The basic usage of the Flag structure is as follows. You declare a pointer to the Flag structure.

struct Flag *flag;

And then you call G_define_flag() function, which allocates memory for the Flag structure and returns a pointer to it.

flag = G_define_flag()

Then you set the structure members, basic members are:

• key - A single letter flag name on the command line.
• description - The flag description to display to the user.

For the full list of members see the Flag structure documentation.

Running Parser

To process and check the command line parameters of your module, you need to call the G_parser() function.

The command line parameters argv and the number of parameters argc from the main() routine should be passed directly to the G_parser() function. The function accepts the command line input entered by the user, and parses this input according to the input options and/or flags that were defined by the programmer.

G_parser() returns 0 if successful. If not successful, it displays a usage statement, which describes the expected and/or required options and flags, and returns a non-zero value.

Additional checks of command line parameters

When the G_parser() function is not sufficient to check all the details about the options and flags and their combinations, the code has to implement the required logic through custom additional checks. The code will typically call the G_usage() function if these checks are not successful.

G_usage() prints a usage message, which explains the allowed and the required command line input to the user. This description is given according to the programmer's definitions for options and flags. This function becomes useful when the user enters options and/or flags on the command line that are syntactically valid to the parser, but functionally invalid for the command (e.g. an invalid file name).

For example, the parser logic doesn't directly support grouping options. If two options must be specified together or not at all, the parser must be told that these options are not required and the programmer must check that if one option is specified the other is as well. If this additional check fails after G_parser() has succeeded, the programmer can then call G_usage() to print the standard usage message and then would separately need to print the additional information on how the two options work together.

Multiple answer default values

Providing multiple default values (answers) for an option that allows multiple values is possible using:

char *def[] = {"One", "Two", "Last", NULL};

opt->multiple = YES;
opt->answers  = def;

The programmer must not forget the last NULL value.

New in GRASS 5.

Disabling interactive mode

This is mainly historical feature which enables to disable interactive prompting in command line.

When a user runs a command with no arguments on the command line, the parser will enter its own standardized interactive session and prompt the user for all flags and options interactively. A call to G_disable_interactive() disables this feature.

Parser Programming Examples

The use of the parser in the programming process is demonstrated here. Both a basic step by step example and a full code example are presented.

Step by Step Use of the Parser

Below are four basic steps to use the GRASS parser in a GRASS command:

Allocate memory for Flags and Options

Options and flags are pointers to structures (Option and Flag structures) allocated through the parser functions G_define_option() and G_define_flag() as described in Parser interface.

#include <grass/gis.h>;   /* The standard GRASS include file */

/* ... */

struct Option *opt;       /* Establish an Option pointer for each option */
struct Flag *flag;        /* Establish a Flag pointer for each option */

opt = G_define_option();  /* Request a pointer to memory for each option */

flag = G_define_flag();   /* Request a pointer to memory for each flag */

Define members of Flag and Option structures

Define the characteristics of each required option and flag, for example:

opt->key = "option";                 /* The name of this option is "option". */
opt->description = _("Option test"); /* The option description is "Option test" */
opt->type = TYPE_STRING;             /* The data type of the answer to the option */
opt->required = YES;                 /* This option *is* required from the user */

flag->key = "t";                     /* Single letter name for flag */
flag->description = _("Flag test");  /* The flag description is "Flag test" */

Note

There are more options defined in Complete Structure Members Table. You should for sure explore the label, the options and the multiple structure members.

Call the parser

int main(int argc, char *argv[]); /* command line args passed into main() */

/* ... options and flags definitions */

if (G_parser(argc, argv))    /* Returns 0 if successful, non-zero otherwise */
      exit(EXIT_FAILURE);

/* ... additional checks */

/* ... module code */

Extracting information from the parser structures

The following code extracts the information about an option and a flag and prints it to the standard output.

fprintf(stdout, "For the option "%s" you chose: <%s>\n", opt->description, opt->answer);
fprintf(stdout, "The flag "-%s" is %s.\n", flag->key, flag->answer ? "set" : "not set");

Running the example program

Once such a module has been compiled (see Compiling and Installing GRASS Modules), execution will result in the following user interface scenarios. Lines that begin with '$' (dollar sign) indicate a command line session with user commands.

$ r.mysample --help

This is a standard user request for basic help information on the module. The command line options (in this case, –help) are sent to the parser via G_parser(). The parser recognizes the –help command line option and returns the list of options and/or flags that are applicable for the specific command. Note how the option and the flag information specified above appears in the output.

r.mysample [-t] option=name

Flags:
-t Flag test

Parameters:
option Option test

Now consider the following command:

$ r.mysample -t

This command does not contain the required option. Note that the output provides this information along with the standard usage message (as already shown above):

Required parameter <option> not set (Option test).

Usage:

r.mysample [-t] option=name


Flags:
-t Flag test

Parameters:
option Option test

The following commands are correct and equivalent:

$ r.mysample option=Hello -t
$ r.mysample -t option=Hello

The parser provides no error messages and the module executes normally:

For the option "Option test" you chose: Hello
The flag "-t" is set.

Full Module Example

The following code demonstrates some of the basic capabilities of the parser. To compile this code, create this Makefile and run the make command (see Compiling and Installing GRASS Modules).

MODULE_TOPDIR = ../..

PGM = r.mysample

LIBES = $(GISLIB)
DEPENDENCIES = $(GISDEP)

include $(MODULE_TOPDIR)/include/Make/Module.make

default: cmd

The sample C code follows (the usual name of the file with the main function is main.c). You can experiment with this code to familiarize yourself with the parser.

Note

This example includes some of the advanced structure members described in Complete Structure Members Table.

#include <stdlib.h>
#include <string.h>
#include <grass/gis.h>
#include <grass/glocale.h>

int main(int argc, char *argv[])
{
    struct Option *opt, *coor;
    struct Flag *flag;
    double X, Y;
    int n;

    opt = G_define_option();
    opt->key = "debug";
    opt->type = TYPE_STRING;
    opt->required = NO;
    opt->answer = "0";
    opt->description = _("Debug level");

    coor = G_define_option();
    coor->key = "coordinate";
    coor->key_desc = "x,y";
    coor->type = TYPE_STRING;
    coor->required = YES;
    coor->multiple = YES;
    coor->description = _("One or more coordinate(s)");

    /* Note that coor->answer is not given a default value. */
    flag = G_define_flag();
    flag->key = 'v';
    flag->description = _("Verbose execution");

    /* Note that flag->answer is not given a default value. */

    if (G_parser(argc, argv))
        exit (EXIT_FAILURE);

    G_message("For the option <%s> you chose: <%s>",
              opt->description, opt->answer);
    G_message("The flag <%s> is: %s", flag->key,
              flag->answer ? "set" : "not set");
    G_message("You specified the following coordinates:");

    for (n=0; coor->answers[n] != NULL; n+=2) {
        G_scan_easting(coor->answers[n], &X , G_projection());
        G_scan_northing(coor->answers[n+1], &Y , G_projection());
        fprintf(stdout, "%.15g,%.15g", X, Y);
    }
}

Note

This example defines the option for coordinates in its own way to demonstrate usage of particular parser features. However, it must be noted that there is a standardized G_OPT_M_COORDS option, which should be used for coordinates.

Complete Structure Members Table

struct Flag

structure member	C type	required	default	description and example
key	char	YES	none	Key char used on command line. flag->key = 'f' ;
Description	char *	YES	none	A string describing the flag meaning. flag->description = _("run in fast mode") ;
answer	char	NO	NULL	Default and parser-returned flag states.

struct Option

structure member	C type	required	default	description and example
key	char *	YES	none	Key word used on command line. opt->key = "map" ;
type	int	YES	none	Option type: TYPE_STRING TYPE_INTEGER TYPE_DOUBLE opt->type = TYPE_STRING ;
Description	char *	YES	none	A string describing the option along with the gettext macro for internationalization. opt->description = _("Map name") ;
answer	char *	NO	NULL	The default and the parser-returned answer to the option. opt->answer = "defaultmap" ;
key_desc	char *	NO	NULL	Single word describing the key. Commas in this string denote to the parser that several comma-separated arguments are expected from the user as one answer. For example, if a pair of coordinates is desired, this element should be defined as follows. opt->key_desc = "x,y" ;
structure member	C type	required	default	description and example
multiple	int	NO	NO	Indicates whether the user can provide multiple answers or not. YES and NO are defined in "gis.h" and should be used (NO is the default.) multiple is used in conjunction with the answers structure member below. opt->multiple = NO ;
answers		NO	NULL	Multiple parser-returned answers to an option. N/A
required	int	NO	NO	Indicates whether the user MUST provide the option on the command line. YES and NO are defined in "gis.h" and should be used (NO is the default). opt->required = YES ;
options	char *	NO	NULL	Approved values or range of values. opt->options = "red,blue,white" ; For integers and doubles, the following format is available: opt->options = "0-1000" ;
gisprompt	char *	NO	NULL	Interactive prompt guidance. There are three comma-separated parts to this argument, which guide the standard GRASS file name prompting routines. opt->gisprompt = "old,cell,raster" ;
checker	char *()	NO	NULL	A routine to check an answer to the option. opt->checker = my_routine() ;

Description of Complex Structure Members

What follows are explanations of possibly confusing structure members. They are intended to clarify and supplement the structures table above.

Answer member of the Flag and Option structures

The answer structure member serves two functions for GRASS commands that use the parser.

(1) To set the default answer to an option:

If a default state is desired for a programmer-defined option, the programmer may define the Option structure member answer before calling G_parser() in his module. After the G_parser() call, the answer member will hold this preset default value if the user did not enter an option that has the default answer member value.

(2) To obtain the command-line answer to an option or a flag:

After a call to G_parser(), the answer member will contain one of the two values:

• (a) If the user provided an option and answered this option on the command line, the user's input will replace the default value of the answer member as described above.
• (b) If the user provided an option, but did not answer this option on the command line, the default is not used. The user may use the default answer to an option by withholding mention of the option on the command line. But if the user enters an option without an answer, G_parser() will replace the default answer member value with NULL.

As an example, please review the use of answer members in the structures implemented in Full Module Example.

Multiple and Answers Members

The functionality of the answers structure member is reliant on the programmer's definition of the multiple structure member. If the multiple member is set to NO, the answer member is used to obtain the answer to an option as described above.

If the multiple structure member is set to YES, it tells G_parser() to capture multiple answers. Multiple answers are separated by commas on the command line after an option.

Note: G_parser() does not recognize any character other than a comma to delimit multiple answers.

After the programmer has set up an option to receive multiple answers, these answers are stored in the answers member of the Option structure. The answers member is an array that contains each individual user-entered answer. The elements of this array are the type specified by the programmer using the type member. The answers array contains however many comma-delimited answers the user entered, followed (terminated) by a NULL array element.

Below is an example definition of an Option using the multiple and the answers structure members:

opt->key = "option";
opt->description = _("option example");
opt->type = TYPE_INTEGER;
opt->required = NO;
opt->multiple = YES;

The above definition would ask the user for multiple integer answers to the option. If in response the user entered "option=1,3,8,15" on the command line, the answers array would contain the following values:

answers[0] == "1"
answers[1] == "3"
answers[2] == "8"
answers[3] == "15"
answers[4] == NULL

key_desc Member

The key_desc structure member is used to define the format of a single command line answer to an option. A programmer may wish to ask for one answer to an option, but this answer may not be a single argument of a type set by the type structure member. If the programmer wants the user to enter a coordinate, for example, the programmer might define an Option as follows:

opt->key ="coordinate";
opt->description = _("Specified Coordinate");
opt->type = TYPE_INTEGER;
opt->required = NO;
opt->key_desc = "x,y"
opt->multiple = NO;

The answer to this option would not be stored in the answer member, but in the answers member. If the user entered "coordinate=112,225" on the command line in response to a routine that contains the above option definition, the answers array would have the following values after the call to G_parser():

answers[0] == "112"
answers[1] == "225"
answers[2] == NULL

Note that "coordinate=112" would not be valid, as it does not contain both components of an answer as defined by the key_desc structure member.

If the multiple structure member was set to YES instead of NO in the example above, the answers would be stored sequentially in the answers member. For example, if the user wanted to enter the coordinates (112,225), (142,155), and (43,201), his response on the command line would be "coordinate=112,225,142,155,43,201". Note that G_parser() recognizes only a comma for both the key_desc member, and multiple answers.

The answers array would have the following values after a call to G_parser():

answers[0] == "112" answers[1] == "225"
answers[2] == "142" answers[3] == "155"
answers[4] == "43" answers[5] == "201"
answers[6] == NULL

Note. In this case as well, neither "coordinate=112" nor "coordinate=112,225,142" would be valid command line arguments, as they do not contain even pairs of coordinates. Each answer's format (as described by the key_desc member) must be fulfilled completely.

The overall function of the key_desc and the multiple structure members is very similar. The key_desc member is used to specify the number of required components of a single option answer (e.g. a multi-valued coordinate.) The multiple member tells G_parser() to ask the user for multiple instances of the compound answer as defined by the format in the key_desc structure member.

Another function of the key_desc structure member is to explain to the user the type of information expected as an answer. The coordinate example is explained above.

The usage message that is displayed by G_parser() in case of an error, or by G_usage() on programmer demand, is shown below. The Option "option" for the command a.out does not have its key_desc structure member defined.

Usage:

a.out option=name

The use of "name" is a G_parser() standard. If the programmer defines the key_desc structure member before a call to G_parser(), the value of the key_desc member replaces "name". Thus, if the key_desc member is set to "x,y" as was used in an example above, the following usage message would be displayed:

Usage:

a.out option=x,y

The key_desc structure member can be used by the programmer to clarify the usage message as well as to specify single or multiple required components of a single option answer.

gisprompt Member

The gisprompt Option structure member requires a bit more description. The three comma-separated (no spaces allowed) sub-arguments are defined as follows:

• The first argument: "old" results in a call to the GRASS library subroutine G_open_old(), "new" to G_open_new(), otherwise "any" or "mapset".
  • If any option has "new" as the first component, the –o (overwrite) flag will be listed in the module's interface (–help output, manual page, GUI dialog, etc).
  • If an option that has "new" as the first component is given, the parser checks whether the entity (map, etc.) already exists.
• The second argument: this is identical to the "element" argument in the above subroutine calls. It specifies a directory inside the mapset that may contain the user's response. In other words, the second field is used to determine where to look for the file (i.e. if the option has "new,cell,...", it will look in the "cell" directory). The second field should be the name of one of the standard subdirectories of the mapset, as listed in $GISBASE/etc/element_list.
• The third argument: identical to the "prompt" argument in the above subroutine calls. This is a string presented to the user that describes the type of data element being requested.

Here are two examples:

"new,cell,raster"   G_open_new("cell", "map")
"old,vector,vector" G_open_old("vector", "map")

The gisprompt values are passed to any GUI code, both self-contained dialogs generated by the parser for the –ui option, and stand-alone GUIs (wxGUI) which use the –xml-description flags to obtain a machine-readable description of the module's interface. How the GUI interprets this is up to the GUI.

Standard options and flags

There are standard options and standard flags, they ensure consistency in names and values.

Standard options are defined by the G_define_standard_option() function and standard flags are defined by the G_define_standard_flag() function. Both the options and the flags are defined dynamically, so to see the values of all members you need to open the file parser_standard_options.c.

The function G_define_standard_option() accepts one value of the STD_OPT enum defined in the gis.h file. The G_define_standard_option() function calls the G_define_option() function, so there is no need to call the latter separately. The same convention applies to standard flags too, which use the G_define_standard_flag() function and the STD_OPT enum.

Besides a name and a value, standard options also define a label, a description, allowed values, their descriptions etc. Standard flags use a similar approach. After defining a standard option or a standard flag you can still assign custom values to individual structure members as required instead of the default values.

Command line parsing FAQ

Can the user mix options and flags?

Yes. Options and flags can be given in any order.

In what order does the parser present options and flags?

Flags and options appear in the usage message according to the order of the G_define_option() and the G_define_flag() function calls.

Is the user required to use full option names?

No. Users are required to type in only as many characters of an option name as is necessary to make the option choice unambiguous. If, for example, there are two options, "input=" and "output=", the following would be valid command line arguments:

$ command i=map1 o=map2

$ command in=map1 out=map2

Are options standardized at all?

Yes. There are a few conventions. Options that identify a single input map are usually "map=", not "raster=" or "vector=". In the case of an input and an output map the convention is "input=xx output=yy". By passing the '–help' flag to existing GRASS commands, it is likely that you will find other conventions. The intent is to make it as easy as possible for the user to remember (or to guess correctly) what the command line syntax is for a given command.

To ensure maximal consistency, the most common options such as the options named above are defined as standard options and are available through G_define_standard_option() function. For flags you can use the G_define_standard_flag() function.

How does a programmer query for coordinates?

There is the standardized G_OPT_M_COORDS option, which should be used for coordinates.

See the source code for the GRASS commands r.drain or r.cost for examples.

How does a programmer define that the option is a set of values?

For any user input that requires a tuple of values (like a pair of map coordinates) the programmer specifies the number of arguments in the key_desc member of the Option structure. For example, if key_desc was set to "x,y", the parser would require that the user enters a pair of arguments separated only with a comma.

Note

There is the standardized G_OPT_M_COORDS option, which should be used for coordinates.

How is automatic prompting turned off?

GRASS 4.0 introduced a new method for driving GRASS interactive and non-interactive modules as described in Compiling and Installing GRASS Modules. Here is a short overview.

For most modules a user runs a front-end module out of the GRASS bin directory, which in turn looks for the existence of interactive and non-interactive versions of the module. If an interactive version exists and the user provided no command line arguments, then that version is executed.

In such a situation, the parser's default interaction will never be seen by the user. A programmer using the parser is able to avoid the front-end's default search for a fully interactive version of the command by placing a call to G_disable_interactive() before calling G_parser() (see Parser interface for details).