|
|
@@ -5,6 +5,12 @@
|
|
|
|
|
|
by GRASS Development Team (http://grass.osgeo.org)
|
|
|
|
|
|
+\tableofcontents
|
|
|
+
|
|
|
+
|
|
|
+\par Subpages:
|
|
|
+- \subpage Command_Line_Parsing
|
|
|
+
|
|
|
This chapter is divided as follows:
|
|
|
|
|
|
- \subpage gislibintro
|
|
|
@@ -40,23 +46,6 @@ This chapter is divided as follows:
|
|
|
|
|
|
- \subpage Temporary_Files
|
|
|
|
|
|
-- \subpage Command_Line_Parsing
|
|
|
- - \subpage Description
|
|
|
- - \subpage Structures
|
|
|
- - \subpage Option_structure
|
|
|
- - \subpage Flag_structure
|
|
|
- - \subpage Parser_Routines
|
|
|
- - \subpage Parser_Programming_Examples
|
|
|
- - \subpage Step_by_Step_Use_of_the_Parser
|
|
|
- - \subpage Full_Module_Example
|
|
|
- - \subpage Complete_Structure_Members_Table
|
|
|
- - \subpage Description_of_Complex_Structure_Members
|
|
|
- - \subpage Answer_member_of_the_Flag_and_Option_structures
|
|
|
- - \subpage Multiple_and_Answers_Members
|
|
|
- - \subpage key_desc_Member
|
|
|
- - \subpage gisprompt_Member
|
|
|
- - \subpage Common_Questions
|
|
|
-
|
|
|
- \subpage String_Manipulation_Functions
|
|
|
|
|
|
- \subpage Enhanced_UNIX_Routines
|
|
|
@@ -1116,807 +1105,6 @@ and then exits, the child may find that GRASS has removed the
|
|
|
temporary file since the process which created it is no longer
|
|
|
running.
|
|
|
|
|
|
-\section Command_Line_Parsing Command Line Parsing
|
|
|
-
|
|
|
-
|
|
|
-The following routines provide a standard mechanism for command line
|
|
|
-parsing. Use of the provided set of routines will standardize GRASS
|
|
|
-commands that expect command line arguments, creating a family of
|
|
|
-GRASS modules that is easy for users to learn. 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 that GRASS
|
|
|
-programmers use this set of routines 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.
|
|
|
-
|
|
|
-\subsection Description Description
|
|
|
-
|
|
|
-
|
|
|
-The GRASS parser is a collection of five subroutines which use two
|
|
|
-structures that are defined in the GRASS "gis.h" header file. These
|
|
|
-structures allow the programmer to define the options and flags that
|
|
|
-make up the valid command line input of a GRASS command.
|
|
|
-
|
|
|
-The parser routines behave in one of three ways:
|
|
|
-
|
|
|
-<ul>
|
|
|
-<li> 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 this
|
|
|
-version.
|
|
|
-
|
|
|
-<li> 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 cancels
|
|
|
-execution of the command.
|
|
|
-
|
|
|
-<li> 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.
|
|
|
-</ul>
|
|
|
-
|
|
|
-\subsection Structures Structures
|
|
|
-
|
|
|
-The parser routines described below use two structures as defined in
|
|
|
-the GRASS "gis.h" header file.
|
|
|
-
|
|
|
-This is a basic list of members of the <b>Option</b> and <b>Flag</b>
|
|
|
-structures. A comprehensive description of all elements of these two
|
|
|
-structures and their possible values can be found in
|
|
|
-\ref Full_Structure_Members_Description.
|
|
|
-
|
|
|
-\subsection Option_structure Option structure
|
|
|
-
|
|
|
-
|
|
|
-These are the basic members of the <em>Option</em> structure.
|
|
|
-
|
|
|
-\code
|
|
|
-struct Option *opt; /* to declare a command line option */
|
|
|
-\endcode
|
|
|
-
|
|
|
-Structure Member Description of Member:
|
|
|
-
|
|
|
- - <i>opt->key</i> - Option name that user will use
|
|
|
- - <i>opt->description</i> - Option description that is shown to the user
|
|
|
- - <i>opt->type</i> - Variable type of the user's answer to the option
|
|
|
- - <i>opt->required</i> - Is this option required on the command line? (Boolean)
|
|
|
-
|
|
|
-\subsection Flag_structure Flag structure
|
|
|
-
|
|
|
-These are the basic members of the Flag structure.
|
|
|
-
|
|
|
-\code
|
|
|
-struct Flag *flag; /* to declare a command line flag */
|
|
|
-\endcode
|
|
|
-
|
|
|
-Structure Member Description of Member:
|
|
|
-
|
|
|
- - <i>flag->key</i> - Single letter used for flag name
|
|
|
- - <i>flag->description</i> - Flag description that is shown to the user
|
|
|
-
|
|
|
-
|
|
|
-\subsection Parser_Routines Parser Routines
|
|
|
-
|
|
|
-Associated with the parser are five routines that are automatically
|
|
|
-included in the GRASS Makefile process. The Makefile process is
|
|
|
-documented in \ref Compiling_and_Installing_GRASS_Modules.
|
|
|
-
|
|
|
- - G_define_option()
|
|
|
-
|
|
|
-Returns <i>Option</i> structure. Allocates memory for the Option structure
|
|
|
-and returns a pointer to this memory.
|
|
|
-
|
|
|
- - G_define_flag()
|
|
|
-
|
|
|
-Allocates memory for the <i>Flag</i> structure and returns a pointer
|
|
|
-to this memory.
|
|
|
-
|
|
|
- - G_parser()
|
|
|
-
|
|
|
-The command line parameters <i>argv</i> and the number of parameters
|
|
|
-<i>argc</i> from the main() routine are passed directly to
|
|
|
-G_parser(). G_parser() 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, a usage
|
|
|
-statement is displayed that describes the expected and/or required
|
|
|
-options and flags and a non-zero value is returned.
|
|
|
-
|
|
|
- - G_usage()
|
|
|
-
|
|
|
-Calls to G_usage() allow the programmer to print the usage message at
|
|
|
-any time. This will explain the allowed and 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 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 is specified the other must be as
|
|
|
-well. If this additional check fails, then G_parser() will
|
|
|
-succeed, but the programmer can then call G_usage() to print
|
|
|
-the standard usage message and print additional information about how
|
|
|
-the two options work together.
|
|
|
-
|
|
|
- - G_disable_interactive()
|
|
|
-
|
|
|
-When a user calls a command with no arguments on the command line, the
|
|
|
-parser will enter its own standardized interactive session in which
|
|
|
-all flags and options are presented to the user for input. A call to
|
|
|
-G_disable_interactive() disables the parser's interactive prompting.
|
|
|
-
|
|
|
-<b>Note:</b> Displaying multiple answers default values (new in GRASS
|
|
|
-5, see d.zoom for example).
|
|
|
-
|
|
|
-\code
|
|
|
-char *def[] = {"One", "Two", "Last", NULL};
|
|
|
-
|
|
|
-opt->multiple = YES;
|
|
|
-opt->answers = def;
|
|
|
-if (G_parser(argc, argv))
|
|
|
- exit(EXIT_FAILURE);
|
|
|
-\endcode
|
|
|
-
|
|
|
-The programmer may not forget last NULL value.
|
|
|
-
|
|
|
-
|
|
|
-\subsection Parser_Programming_Examples Parser Programming Examples
|
|
|
-
|
|
|
-The use of the parser in the programming process is demonstrated
|
|
|
-here. Both a basic step by step example and full code example are
|
|
|
-presented.
|
|
|
-
|
|
|
-\subsection Step_by_Step_Use_of_the_Parser Step by Step Use of the Parser
|
|
|
-
|
|
|
-
|
|
|
-These are the four basic steps to follow to implement the use of the
|
|
|
-GRASS parser in a GRASS command:
|
|
|
-
|
|
|
-<b>(1) Allocate memory for Flags and Options:</b>
|
|
|
-
|
|
|
-Flags and Options are pointers to structures allocated through the
|
|
|
-parser routines G_define_option() and G_define_flag() as
|
|
|
-defined in \ref Parser_Routines.
|
|
|
-
|
|
|
-\code
|
|
|
-#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 */
|
|
|
-\endcode
|
|
|
-
|
|
|
-<b>(2) Define members of Flag and Option structures:</b>
|
|
|
-
|
|
|
-The programmer should define the characteristics of each option and
|
|
|
-flag desired as outlined by the following example:
|
|
|
-
|
|
|
-\code
|
|
|
-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" */
|
|
|
-\endcode
|
|
|
-
|
|
|
-<b>Note:</b> There are more options defined later in \ref
|
|
|
-Complete_Structure_Members_Table.
|
|
|
-
|
|
|
-<b>(3) Call the parser:</b>
|
|
|
-
|
|
|
-\code
|
|
|
-int main(int argc, char *argv[]); /* command line args passed into main() */
|
|
|
-
|
|
|
-if (G_parser(argc, argv)) /* Returns 0 if successful, non-zero otherwise */
|
|
|
- exit(EXIT_FAILURE);
|
|
|
-\endcode
|
|
|
-
|
|
|
-<b>(4) Extracting information from the parser structures:</b>
|
|
|
-
|
|
|
-\code
|
|
|
-fprintf(stdout, "For the option "%s" you chose: <%s>\n", opt->description, opt->answer);
|
|
|
-fprintf(stdout, "The flag "-%s" is %s set.\n", flag->key, flag->answer ? "" : "not");
|
|
|
-\endcode
|
|
|
-
|
|
|
-<b>(5) Running the example program</b>
|
|
|
-
|
|
|
-Once such a module has been compiled (for example to the default
|
|
|
-executable file <tt>a.out</tt> , execution will result in the following
|
|
|
-user interface scenarios. Lines that begin with '$' imply user entered
|
|
|
-commands on the command line.
|
|
|
-
|
|
|
-\verbatim
|
|
|
-$ a.out help
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-This is a standard user call 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 a list of options and/or flags that
|
|
|
-are applicable for the specific command. Note how the programmer
|
|
|
-provided option and flag information is captured in the output.
|
|
|
-
|
|
|
-\verbatim
|
|
|
-a.out [-t] option=name
|
|
|
-
|
|
|
-Flags:
|
|
|
--t Flag test
|
|
|
-
|
|
|
-Parameters:
|
|
|
-option Option test
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-Now the following command is executed:
|
|
|
-
|
|
|
-\verbatim
|
|
|
-# a.out -t
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-This command line does not contain the required option. Note that the
|
|
|
-output provides this information along with the standard usage message
|
|
|
-(as already shown above):
|
|
|
-
|
|
|
-\verbatim
|
|
|
-Required parameter <option> not set (Option test).
|
|
|
-
|
|
|
-Usage:
|
|
|
-
|
|
|
-a.out[-t] option=name
|
|
|
-
|
|
|
-
|
|
|
-Flags:
|
|
|
--t Flag test
|
|
|
-
|
|
|
-Parameters:
|
|
|
-option Option test
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-The following commands are correct and equivalent. The parser provides no
|
|
|
-error messages and the module executes normally:
|
|
|
-
|
|
|
-\verbatim
|
|
|
-# a.out option=Hello -t
|
|
|
-
|
|
|
-# a.out -t option=Hello
|
|
|
-
|
|
|
-For the option "Option test" you chose: Hello
|
|
|
-The flag "-t" is set.
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-\subsection Full_Module_Example 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
|
|
|
-<tt>make</tt> command (see \ref Compiling_and_Installing_GRASS_Modules).
|
|
|
-
|
|
|
-\code
|
|
|
-MODULE_TOPDIR = ../..
|
|
|
-
|
|
|
-PGM = r.mysample
|
|
|
-
|
|
|
-LIBES = $(GISLIB)
|
|
|
-DEPENDENCIES = $(GISDEP)
|
|
|
-
|
|
|
-include $(MODULE_TOPDIR)/include/Make/Module.make
|
|
|
-
|
|
|
-default: cmd
|
|
|
-\endcode
|
|
|
-
|
|
|
-The <tt>sample.c</tt> code follows. You might experiment with this code to
|
|
|
-familiarize yourself with the parser.
|
|
|
-
|
|
|
-<b>Note:</b> This example includes some of the advanced structure
|
|
|
-members described in \ref Complete_Structure_Members_Table.
|
|
|
-
|
|
|
-\code
|
|
|
-#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 set", flag->key,
|
|
|
- flag->answer ? "" : "not");
|
|
|
- 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);
|
|
|
- }
|
|
|
-}
|
|
|
-\endcode
|
|
|
-
|
|
|
-\subsection Complete_Structure_Members_Table Complete Structure Members Table
|
|
|
-
|
|
|
-\subsubsection memtabFlag struct Flag
|
|
|
-
|
|
|
-<table>
|
|
|
-<tr>
|
|
|
- <td>structure member</td>
|
|
|
- <td>C type</td>
|
|
|
- <td>required</td>
|
|
|
- <td>default</td>
|
|
|
- <td> description and example</td>
|
|
|
-</tr><tr>
|
|
|
- <td>key</td>
|
|
|
- <td> char</td>
|
|
|
- <td> YES</td>
|
|
|
- <td> none</td>
|
|
|
- <td> Key char used on command line<br>
|
|
|
- flag->key = 'f' ;</td>
|
|
|
-</tr><tr>
|
|
|
- <td>Description</td>
|
|
|
- <td> char *</td>
|
|
|
- <td> YES</td>
|
|
|
- <td> none</td>
|
|
|
- <td> String describing flag meaning<br>
|
|
|
- flag->description = _("run in fast mode") ;</td>
|
|
|
-</tr><tr>
|
|
|
- <td>answer</td>
|
|
|
- <td> char</td>
|
|
|
- <td> NO</td>
|
|
|
- <td> NULL</td>
|
|
|
- <td> Default and parser-returned
|
|
|
- flag states.</td>
|
|
|
-</tr>
|
|
|
-</table>
|
|
|
-
|
|
|
-\subsubsection memtabOption struct Option
|
|
|
-
|
|
|
-<table>
|
|
|
-<tr>
|
|
|
- <td>structure member</td>
|
|
|
- <td>C type </td>
|
|
|
- <td>required </td>
|
|
|
- <td>default </td>
|
|
|
- <td>description and example</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>key </td>
|
|
|
- <td>char * </td>
|
|
|
- <td>YES </td>
|
|
|
- <td>none </td>
|
|
|
- <td>Key word used on command line.<br>
|
|
|
- opt->key = "map" ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>type </td>
|
|
|
- <td>int </td>
|
|
|
- <td>YES </td>
|
|
|
- <td>none </td>
|
|
|
- <td>%Option type: <br>
|
|
|
- TYPE_STRING <br>
|
|
|
- TYPE_INTEGER <br>
|
|
|
- TYPE_DOUBLE <br>
|
|
|
- opt->type = TYPE_STRING ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>Description </td>
|
|
|
- <td>char * </td>
|
|
|
- <td>YES </td>
|
|
|
- <td>none </td>
|
|
|
- <td>String describing option along with gettext macro for internationalization
|
|
|
- opt->description = _("Map name") ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>answer </td>
|
|
|
- <td>char * </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>NULL </td>
|
|
|
- <td>Default and parser-returned answer to an option.<br>
|
|
|
- opt->answer = "defaultmap" ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>key_desc </td>
|
|
|
- <td>char * </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>NULL </td>
|
|
|
- <td>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 might be defined as follows.<br>
|
|
|
- opt->key_desc = "x,y" ; </td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>structure member</td>
|
|
|
- <td>C type </td>
|
|
|
- <td>required </td>
|
|
|
- <td>default </td>
|
|
|
- <td>description and example</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>multiple </td>
|
|
|
- <td>int </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>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 ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>answers </td>
|
|
|
- <td> </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>NULL </td>
|
|
|
- <td>Multiple parser-returned answers to an option. N/A</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>required </td>
|
|
|
- <td>int </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>Indicates whether 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 ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>options </td>
|
|
|
- <td>char * </td>
|
|
|
- <td>NO </td>
|
|
|
- <td>NULL </td>
|
|
|
- <td>Approved values or range of values. <br>
|
|
|
- opt->options = "red,blue,white" ;<br>
|
|
|
- For integers and doubles, the following format is available: <br>
|
|
|
- opt->options = "0-1000" ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>gisprompt</td>
|
|
|
- <td>char *</td>
|
|
|
- <td>NO</td>
|
|
|
- <td>NULL</td>
|
|
|
- <td>Interactive prompt guidance. There are three comma separated
|
|
|
- parts to this argument which guide the use of the standard GRASS
|
|
|
- file name prompting routines.<br>
|
|
|
- opt->gisprompt = "old,cell,raster" ;</td>
|
|
|
-</tr>
|
|
|
-<tr>
|
|
|
- <td>checker</td>
|
|
|
- <td>char *()</td>
|
|
|
- <td>NO</td>
|
|
|
- <td>NULL</td>
|
|
|
- <td>Routine to check the answer to an option<br>
|
|
|
- m opt->checker = my_routine() ;</td>
|
|
|
-</tr>
|
|
|
-</table>
|
|
|
-
|
|
|
-\subsection Description_of_Complex_Structure_Members Description of Complex Structure Members
|
|
|
-
|
|
|
-
|
|
|
-What follows are explanations of possibly confusing structure
|
|
|
-members. It is intended to clarify and supplement the structures table
|
|
|
-above.
|
|
|
-
|
|
|
-\subsection Answer_member_of_the_Flag_and_Option_structures Answer member of the Flag and Option structures
|
|
|
-
|
|
|
-The answer structure member serves two functions for GRASS commands
|
|
|
-that use the parser.
|
|
|
-
|
|
|
-<b>(1) To set the default answer to an option:</b>
|
|
|
-
|
|
|
-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
|
|
|
-<i>not</i> enter an option that has the default answer member value.
|
|
|
-
|
|
|
-<b>(2) To obtain the command-line answer to an option or flag:</b>
|
|
|
-
|
|
|
-After a call to G_parser(), the answer member will contain one of two
|
|
|
-values:
|
|
|
-
|
|
|
- - (a) If the user provided an option, and answered this option on the
|
|
|
-command line, the default value of the answer member (as described
|
|
|
-above) is replaced by the user's input.
|
|
|
-
|
|
|
- - (b) If the user provided an option, but did <i>not</i> 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, the default answer member value will be replaced and set to a
|
|
|
-NULL value by G_parser().
|
|
|
-
|
|
|
-As an example, please review the use of answer members in the structures
|
|
|
-implemented in \ref Full_Module_Example.
|
|
|
-
|
|
|
-\subsection Multiple_and_Answers_Members 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, the programmer has
|
|
|
-told G_parser() to capture multiple answers. Multiple answers are
|
|
|
-separated by <em>commas</em> on the command line after an option.
|
|
|
-
|
|
|
-<b>Note:</b> 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 the 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.
|
|
|
-
|
|
|
-For example, here is a sample definition of an Option using multiple
|
|
|
-and answers structure members:
|
|
|
-
|
|
|
-\code
|
|
|
-opt->key ="option";
|
|
|
-opt->description = _("option example");
|
|
|
-opt->type = TYPE_INTEGER;
|
|
|
-opt->required = NO;
|
|
|
-opt->multiple = YES;
|
|
|
-\endcode
|
|
|
-
|
|
|
-The above definition would ask the user for multiple integer answers
|
|
|
-to the option. If in response to a routine that contained the above
|
|
|
-code, the user entered "option=1,3,8,15" on the command line, the
|
|
|
-answers array would contain the following values:
|
|
|
-
|
|
|
-\code
|
|
|
-answers[0] == 1
|
|
|
-answers[1] == 3
|
|
|
-answers[2] == 8
|
|
|
-answers[3] == 15
|
|
|
-answers[4] == NULL
|
|
|
-\endcode
|
|
|
-
|
|
|
-
|
|
|
-\subsection key_desc_Member key_desc Member
|
|
|
-
|
|
|
-The <b>key_desc</b> 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:
|
|
|
-
|
|
|
-\code
|
|
|
-opt->key ="coordinate";
|
|
|
-opt->description = _("Specified Coordinate");
|
|
|
-opt->type = TYPE_INTEGER;
|
|
|
-opt->required = NO;
|
|
|
-opt->key_desc = "x,y"
|
|
|
-opt->multiple = NO;
|
|
|
-\endcode
|
|
|
-
|
|
|
-The answer to this option would <i>not</i> 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():
|
|
|
-
|
|
|
-\code
|
|
|
-answers[0] == 112
|
|
|
-answers[1] == 225
|
|
|
-answers[2] == NULL
|
|
|
-\endcode
|
|
|
-
|
|
|
-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 were set to YES instead of NO in the
|
|
|
-example above, the answers are 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 for multiple
|
|
|
-answers.
|
|
|
-
|
|
|
-The answers array would have the following values after a call to
|
|
|
-G_parser():
|
|
|
-
|
|
|
-\code
|
|
|
-answers[0] == 112 answers[1] == 225
|
|
|
-answers[2] == 142 answers[3] == 155
|
|
|
-answers[4] == 43 answers[5] == 201
|
|
|
-answers[6] == NULL
|
|
|
-\endcode
|
|
|
-
|
|
|
-<B>Note.</B> 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 multiple structure members is
|
|
|
-very similar. The key_desc member is used to specify the number of
|
|
|
-<i>required</i> 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 <tt>a.out</tt> does not have its key_desc
|
|
|
-structure member defined.
|
|
|
-
|
|
|
-\verbatim
|
|
|
-Usage:
|
|
|
-
|
|
|
-a.out option=name
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-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:
|
|
|
-
|
|
|
-\verbatim
|
|
|
-Usage:
|
|
|
-
|
|
|
-a.out option=x,y
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-The key_desc structure member can be used by the programmer to clarify
|
|
|
-the usage message as well as specify single or multiple required
|
|
|
-components of a single option answer.
|
|
|
-
|
|
|
-\subsection gisprompt_Member gisprompt Member
|
|
|
-
|
|
|
-The <em>gisprompt</em> Option structure item requires a bit more
|
|
|
-description. The three comma-separated (no spaces allowed)
|
|
|
-sub-arguments are defined as follows:
|
|
|
-
|
|
|
- - 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 <tt>--o</tt>
|
|
|
-(overwrite) flag will be listed in the module's interface
|
|
|
-(<tt>--help</tt> output, manual page, GUI dialog, etc).
|
|
|
-
|
|
|
- - If an option which has "new" as the first component is given, the
|
|
|
-parser checks whether the entity (map, etc.) already exists.
|
|
|
-
|
|
|
- - 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.
|
|
|
-
|
|
|
- - 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:
|
|
|
-
|
|
|
-\verbatim
|
|
|
-"new,cell,raster" G_open_new("cell", "map")
|
|
|
-"old,vector,vector" G_open_old("vector", "map")
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-The gisprompt values are passed to any GUI code, both self-contained
|
|
|
-dialogs generated by the parser for the <tt>--ui</tt> option, and
|
|
|
-stand-alone GUIs (wxGUI) which use the <tt>--xml-description</tt>
|
|
|
-flags to obtain a machine-readable description of the module's
|
|
|
-interface. How the GUI interprets this is up to the GUI.
|
|
|
-
|
|
|
-
|
|
|
-\subsection Common_Questions Common Questions
|
|
|
-
|
|
|
-
|
|
|
- - "How is automatic prompting turned off?"
|
|
|
-
|
|
|
-GRASS 4.0 introduced a new method for driving GRASS interactive and
|
|
|
-non-interactive modules as described in \ref
|
|
|
-Compiling_and_Installing_GRASS_Programs. 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 \ref Parser_Routines for details).
|
|
|
-
|
|
|
- - "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 are presented by the usage message in the order that
|
|
|
-the programmer defines them using calls to G_define_option()
|
|
|
-and G_define_flag().
|
|
|
-
|
|
|
- - "How does a programmer query for coordinates?"
|
|
|
-
|
|
|
-For any user input that requires a set of arguments (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
|
|
|
-opt->key_desc was set to "x,y", the parser will require that the
|
|
|
-user enter a pair of arguments separated only by a comma. See the
|
|
|
-source code for the GRASS commands <tt>r.drain</tt> or <tt>r.cost</tt>
|
|
|
-for examples.
|
|
|
-
|
|
|
- - "Is a 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:
|
|
|
-
|
|
|
-\verbatim
|
|
|
-# command i=map1 o=map2
|
|
|
-
|
|
|
-# command in=map1 out=map2
|
|
|
-\endverbatim
|
|
|
-
|
|
|
- - "Are options standardized at all?"
|
|
|
-
|
|
|
-Yes. There are a few conventions. Options which identify a single input map
|
|
|
-are usually "map=", not "raster=" or "vector=". In the case of an
|
|
|
-input and output map the convention is: "input=xx output=yy". By passing
|
|
|
-the 'help' option to existing GRASS commands, it is likely that you will
|
|
|
-find other conventions. The desire is to make it as easy as possible for the
|
|
|
-user to remember (or guess correctly) what the command line syntax is for a
|
|
|
-given command.
|
|
|
|
|
|
\section String_Manipulation_Functions String Manipulation Functions
|
|
|
|
Vaclav Petras