/*! \page gislib_cmdline_parsing Command Line Parsing \tableofcontents \section gislibcmd_Introduction Introduction This section describes a standard mechanism for command line parsing in GRASS. The system is usually referred as parser or g.parser (because of the related \gmod{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 ensures even better standardization of names, values and descriptions. \section gislibcmd_Description Description The GRASS parser is a collection of functions and structures that are 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: \note Python modules uses the same system but instead of functions and structures, comments in files are used to define options and flags. \section Parser_Interface 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 \ref Complete_Structure_Members_Description. \subsection Option_structure Option structure The basic usage of the Option structure is as follows. You create a pointer to the Option structure. \code struct Option *opt; \endcode And then you call G_define_option() function which allocates memory for the Option structure and returns a pointer to it. \code opt = G_define_option(); \endcode Then you set the structure members, basic members are: - key - Option name that user will use - description - Option description that is shown to the user - type - Variable type of the user's answer to the option - required - If this option is required on the command line? For full list of members see Option structure documentation. \subsection Flag_structure Flag structure The basic usage of the Flag structure is as follows. You create a pointer to the Flag structure. \code struct Flag *flag; \endcode And then you call G_define_flag() function which allocates memory for the Flag structure and returns a pointer to it. \code flag = G_define_flag() \endcode Then you set the structure members, basic members are: - key - Single letter used for flag name - description - Flag description that is shown to the user For full list of members see Flag structure documentation. \subsection Running_Parser Running Parser To process and check the command line parameters of you module, you need to call G_parser() function. The command line parameters argv and the number of parameters argc from the main() routine are should be passed directly to G_parser() function. G_parser() 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, a usage statement is displayed that describes the expected and/or required options and flags and a non-zero value is returned. \subsection Parser_Additional_checks Additional checks of command line parameters When a G_parser() function is not sufficient to check all the details about the options and flags and their combinations, programmer has to add additional checks which are needed. If these checks are not successful programmer can call G_usage() function. 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. \subsection Parser_Displaying_multiple_answers Displaying multiple answers default values Providing multiple default values (answers) for option with allows multiple values is possible using: \code char *def[] = {"One", "Two", "Last", NULL}; opt->multiple = YES; opt->answers = def; \endcode The programmer may not forget last NULL value. New in GRASS 5. \subsection Parser_Disabling_interactive Disabling interactive mode This is mainly historical feature which enables to disable interactive prompting in command line. 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. \section 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: \subsubsection gislib_cmdline_Allocate 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 \ref Parser_Interface. \code #include ; /* 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 \subsubsection gislib_cmdline_Define Define members of Flag and Option structures 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 \note There are more options defined in \ref Complete_Structure_Members_Table. You should for sure explore label member, options member and multiple member. \subsubsection gislib_cmdline_Call Call the parser \code 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 */ \endcode \subsubsection gislib_cmdline_Extracting Extracting information from the parser structures The following lines will extract the information form option and flag and print it to the standard output. \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 \subsubsection gislib_cmdline_Running Running the example program Once such a module has been compiled (see \ref Compiling_and_Installing_GRASS_Modules), execution will result in the following user interface scenarios. Lines that begin with '$' (dollar sign) imply user entered commands on the command line. \verbatim $ r.mysample --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 r.mysample [-t] option=name Flags: -t Flag test Parameters: option Option test \endverbatim Now the following command is executed: \verbatim # r.mysample -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