[GRASS-SVN] r58036 - grass/trunk/lib/gis
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu Oct 17 21:00:09 PDT 2013
Author: wenzeslaus
Date: 2013-10-17 21:00:09 -0700 (Thu, 17 Oct 2013)
New Revision: 58036
Added:
grass/trunk/lib/gis/gislib_cmdline_parsing.dox
Modified:
grass/trunk/lib/gis/gislib.dox
Log:
gislib/dox: move cmd line parsing to separate file (incomplete change)
Modified: grass/trunk/lib/gis/gislib.dox
===================================================================
--- grass/trunk/lib/gis/gislib.dox 2013-10-18 02:49:06 UTC (rev 58035)
+++ grass/trunk/lib/gis/gislib.dox 2013-10-18 04:00:09 UTC (rev 58036)
@@ -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 @@
- \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,808 +1105,7 @@
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
Added: grass/trunk/lib/gis/gislib_cmdline_parsing.dox
===================================================================
--- grass/trunk/lib/gis/gislib_cmdline_parsing.dox (rev 0)
+++ grass/trunk/lib/gis/gislib_cmdline_parsing.dox 2013-10-18 04:00:09 UTC (rev 58036)
@@ -0,0 +1,804 @@
+/*
+\page 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.
+
+*/
Property changes on: grass/trunk/lib/gis/gislib_cmdline_parsing.dox
___________________________________________________________________
Added: svn:executable
+ *
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
More information about the grass-commit
mailing list