GIS Library - Argument parsing functions. More...

#include <grass/config.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <stdarg.h>
#include <sys/types.h>
#include <grass/gis.h>
#include <grass/glocale.h>
#include <grass/spawn.h>

Include dependency graph for parser.c:

Go to the source code of this file.

Data Structures
struct	Item

Macros
#define	BAD_SYNTAX 1

#define	OUT_OF_RANGE 2

#define	MISSING_VALUE 3

#define	KEYLENGTH 64

#define	do_escape(c, escaped) case c: fputs(escaped,f);break
	Format text for HTML output. More...

Functions
int	G_disable_interactive (void)
	Disables the ability of the parser to operate interactively. More...

struct Flag *	G_define_flag (void)
	Initializes a Flag struct. More...

struct Option *	G_define_option (void)
	Initializes an Option struct. More...

struct Option *	G_define_standard_option (int opt)
	Create standardised Option structure. More...

struct GModule *	G_define_module (void)
	Initializes a new module. More...

int	G_parser (int argc, char **argv)
	Parse command line. More...

int	G_usage (void)
	Command line help/usage message. More...

char *	G_recreate_command (void)
	Creates command to run non-interactive. More...

Detailed Description

GIS Library - Argument parsing functions.

Parses the command line provided through argc and argv. Example: Assume the previous calls:

*  opt1 = G_define_option() ;
*  opt1->key        = "map",
*  opt1->type       = TYPE_STRING,
*  opt1->required   = YES,
*  opt1->checker    = sub,
*  opt1->description= "Name of an existing raster map" ;
*
*  opt2 = G_define_option() ;
*  opt2->key        = "color",
*  opt2->type       = TYPE_STRING,
*  opt2->required   = NO,
*  opt2->answer     = "white",
*  opt2->options    = "red,orange,blue,white,black",
*  opt2->description= "Color used to display the map" ;
*
*  opt3 = G_define_option() ;
*  opt3->key        = "number",
*  opt3->type       = TYPE_DOUBLE,
*  opt3->required   = NO,
*  opt3->answer     = "12345.67",
*  opt3->options    = "0-99999",
*  opt3->description= "Number to test parser" ;
* 

G_parser() will respond to the following command lines as described:

* command      (No command line arguments)
*

Parser enters interactive mode.

* command map=map.name
*

Parser will accept this line. Map will be set to "map.name", the 'a' and 'b' flags will remain off and the num option will be set to the default of 5.

* command -ab map=map.name num=9
* command -a -b map=map.name num=9
* command -ab map.name num=9
* command map.name num=9 -ab
* command num=9 -a map=map.name -b
*

These are all treated as acceptable and identical. Both flags are set to on, the map option is "map.name" and the num option is "9". Note that the "map=" may be omitted from the command line if it is part of the first option (flags do not count).

* command num=12
*

This command line is in error in two ways. The user will be told that the "map" option is required and also that the number 12 is out of range. The acceptable range (or list) will be printed.

This program is free software under the GNU General Public License (>=v2). Read the file COPYING that comes with GRASS for details.

Author: Original author CERL; enhancements: Radim Blazek

Date: 2003-2014

Definition in file parser.c.

Macro Definition Documentation

#define BAD_SYNTAX 1

Definition at line 99 of file parser.c.

#define do_escape	(	c,
		escaped
	)	case c: fputs(escaped,f);break

Format text for HTML output.

Definition at line 1264 of file parser.c.

#define KEYLENGTH 64

Definition at line 102 of file parser.c.

#define MISSING_VALUE 3

Definition at line 101 of file parser.c.

#define OUT_OF_RANGE 2

Definition at line 100 of file parser.c.

Function Documentation

struct Flag* G_define_flag ( void )

Initializes a Flag struct.

Allocates memory for the Flag structure and returns a pointer to this memory (of type struct Flag *).

Flags are always represented by single letters. A user "turns them on" at the command line using a minus sign followed by the character representing the flag.

Returns: Flag * Pointer to a Flag struct

Definition at line 191 of file parser.c.

References Item::flag, tools::flag, G_zero(), Item::next_item, NULL, and Item::option.

struct GModule* G_define_module ( void )

Initializes a new module.

Returns: GModule * Pointer to a GModule struct

Definition at line 691 of file parser.c.

References G_zero().

struct Option* G_define_option ( void )

Initializes an Option struct.

Allocates memory for the Option structure and returns a pointer to this memory (of type struct Option *).

Options are provided by user on command line using the standard format: key=value. Options identified as REQUIRED must be specified by user on command line. The option string can either specify a range of values (e.g. "10-100") or a list of acceptable values (e.g. "red,orange,yellow"). Unless the option string is NULL, user provided input will be evaluated agaist this string.

Returns: Option * Pointer to an Option struct

Definition at line 247 of file parser.c.

References Item::flag, G_zero(), Item::next_item, NULL, and Item::option.

Referenced by G3d_setStandard3dInputParams(), G3d_setWindowParams(), G_define_standard_option(), and N_define_standard_option().

struct Option* G_define_standard_option ( int opt )

Create standardised Option structure.

This function will create a standardised Option structure defined by parameter opt. A list of valid parameters can be found in gis.h. It allocates memory for the Option structure and returns a pointer to this memory (of type struct Option *).

If an invalid parameter was specified a empty Option structure will be returned (not NULL).

general: G_OPT_WHERE, G_OPT_COLUMN, G_OPT_COLUMNS, G_OPT_TABLE, G_OPT_DRIVER, G_OPT_DATABASE
imagery: G_OPT_I_GROUP, G_OPT_I_SUBGROUP
raster: G_OPT_R_INPUT, G_OPT_R_INPUTS, G_OPT_R_OUTPUT, G_OPT_R_MAP, G_OPT_R_MAPS, G_OPT_R_BASE, G_OPT_R_COVER, G_OPT_R_ELEV, G_OPT_R_ELEVS
raster3d: G_OPT_R3_INPUT, G_OPT_R3_INPUTS, G_OPT_R3_OUTPUT, G_OPT_R3_MAP, G_OPT_R3_MAPS
vector: G_OPT_V_INPUT, G_OPT_V_INPUTS, G_OPT_V_OUTPUT, G_OPT_V_MAP, G_OPT_V_MAPS, G_OPT_V_TYPE, G_OPT_V_FIELD, G_OPT_V_CAT, G_OPT_V_CATS

Parameters

[in] opt Type of Option struct to create

Returns: Option * Pointer to an Option struct

Definition at line 327 of file parser.c.

References G_define_option().

int G_disable_interactive ( void )

Disables the ability of the parser to operate interactively.

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.

Returns: always returns 0

Definition at line 170 of file parser.c.

int G_parser	(	int	argc,
		char **	argv
	)

Parse command line.

The command line parameters argv and the number of parameters argc 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.

Note: The only functions which can legitimately be called before G_parser() are:

The usual order a module calls functions is:

G_gisinit()
G_define_module()
G_define_{flag,option}()
G_parser()

Parameters

[in]	argc	number of arguments
[in]	argv	argument list

Returns: 0 on success; -1 on error and calls G_usage()

Definition at line 743 of file parser.c.

References buff, FALSE, G_basename(), G_free_tokens(), G_important_message(), G_is_dirsep(), G_store(), G_tokenize(), G_usage(), G_verbose_max(), G_verbose_min(), G_warning(), getenv(), NULL, sprintf(), and TRUE.

char* G_recreate_command ( void )

Creates command to run non-interactive.

Creates a command-line that runs the current command completely non-interactive.

Returns: char * Pointer to a char string

Definition at line 2829 of file parser.c.

References buff, tools::flag, G_debug(), G_program_name(), n, and NULL.

Referenced by G_command_history(), and Vect_hist_command().

int G_usage ( void )

Command line help/usage message.

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.

Returns: always returns 0

Definition at line 1060 of file parser.c.

References tools::flag, G_program_name(), n, and NULL.

Referenced by G_parser().

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation