Data Structures | Defines | Functions

parser.c File Reference

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

Defines

#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.

Functions

int G_disable_interactive (void)
 Disables the ability of the parser to operate interactively.
struct Flag * G_define_flag (void)
 Initializes a Flag struct.
struct Option * G_define_option (void)
 Initializes an Option struct.
struct Option * G_define_standard_option (int opt)
 Create standardised Option structure.
struct GModule * G_define_module (void)
 Initializes a new module.
int G_parser (int argc, char **argv)
 Parse command line.
int G_usage (void)
 Command line help/usage message.
char * G_recreate_command (void)
 Creates command to run non-interactive.

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.

(C) 2001-2009 by the GRASS Development Team

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

Author:
Radim Blazek
Date:
2003-2009

Definition in file parser.c.


Define Documentation

#define BAD_SYNTAX   1

Definition at line 90 of file parser.c.

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

Format text for HTML output.

Definition at line 1236 of file parser.c.

#define KEYLENGTH   64

Definition at line 93 of file parser.c.

#define MISSING_VALUE   3

Definition at line 92 of file parser.c.

#define OUT_OF_RANGE   2

Definition at line 91 of file parser.c.


Function Documentation

struct Flag* G_define_flag ( void   ) [read]

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 182 of file parser.c.

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

struct GModule* G_define_module ( void   ) [read]

Initializes a new module.

Returns:
GModule * Pointer to a GModule struct

Definition at line 672 of file parser.c.

References G_zero().

struct Option* G_define_option ( void   ) [read]

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 238 of file parser.c.

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

Referenced by G_define_standard_option().

struct Option* G_define_standard_option ( int  opt ) [read]

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]optType of Option struct to create
Returns:
Option * Pointer to an Option struct

Definition at line 318 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 161 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:

Parameters:
[in]argcnumber of arguments
[in]argvargument list
Returns:
0 on success
-1 on error and calls G_usage()

Definition at line 724 of file parser.c.

References G_basename(), G_free_tokens(), G_is_dirsep(), G_store(), G_tokenize(), G_usage(), G_verbose(), G_verbose_max(), G_verbose_min(), G_warning(), and NULL.

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 2797 of file parser.c.

References G_debug(), G_program_name(), and NULL.

Referenced by G_command_history().

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 1032 of file parser.c.

References G_program_name(), and NULL.

Referenced by G_parser().