grass  7.8.6
About: GRASS (Geographic Resources Analysis Support System) is a raster- and vector-based GIS, image processing system, graphics production system and spatial modeling system.
  Fossies Dox: grass-7.8.6.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

parser.c File Reference

GIS Library - Argument parsing functions. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <grass/gis.h>
#include <grass/spawn.h>
#include <grass/glocale.h>
#include "parser_local_proto.h"
Include dependency graph for parser.c:

Go to the source code of this file.

Macros

#define MAX_MATCHES   50
 

Enumerations

enum  opt_error {
  BAD_SYNTAX = 1 , OUT_OF_RANGE = 2 , MISSING_VALUE = 3 , INVALID_VALUE = 4 ,
  AMBIGUOUS = 5 , REPLACED = 6
}
 

Functions

static void set_flag (int)
 
static int contains (const char *, int)
 
static int valid_option_name (const char *)
 
static int is_option (const char *)
 
static int match_option_1 (const char *, const char *)
 
static int match_option (const char *, const char *)
 
static void set_option (const char *)
 
static void check_opts (void)
 
static void check_an_opt (const char *, int, const char *, const char **, char **)
 
static int check_int (const char *, const char **)
 
static int check_double (const char *, const char **)
 
static int check_string (const char *, const char **, int *)
 
static void check_required (void)
 
static void split_opts (void)
 
static void check_multiple_opts (void)
 
static int check_overwrite (void)
 
static void define_keywords (void)
 
static int module_gui_wx (void)
 Invoke GUI dialog. More...
 
static void append_error (const char *)
 
static const char * get_renamed_option (const char *)
 
void G_disable_interactive (void)
 Disables the ability of the parser to operate interactively. More...
 
struct FlagG_define_flag (void)
 Initializes a Flag struct. More...
 
struct OptionG_define_option (void)
 Initializes an Option struct. More...
 
struct GModuleG_define_module (void)
 Initializes a new module. More...
 
int G_parser (int argc, char **argv)
 Parse command line. More...
 
char * recreate_command (int original_path)
 Creates command to run non-interactive. More...
 
char * G_recreate_command (void)
 Creates command to run non-interactive. More...
 
char * G_recreate_command_original_path (void)
 Creates command to run non-interactive. More...
 
void G_add_keyword (const char *keyword)
 Add keyword to the list. More...
 
void G_set_keywords (const char *keywords)
 Set keywords from the string. More...
 
int G__uses_new_gisprompt (void)
 
void G__print_keywords (FILE *fd, void(*format)(FILE *, const char *))
 Print list of keywords (internal use only) More...
 
int G_get_overwrite ()
 Get overwrite value. More...
 
void G__split_gisprompt (const char *gisprompt, char *age, char *element, char *desc)
 
char * G_option_to_separator (const struct Option *option)
 Get separator string from the option. More...
 
FILE * G_open_option_file (const struct Option *option)
 Get an input/output file pointer from the option. If the file name is omitted or '-', it returns either stdin or stdout based on the gisprompt. More...
 
void G_close_option_file (FILE *fp)
 Close an input/output file returned by G_open_option_file(). If the file pointer is stdin, stdout, or stderr, nothing happens. More...
 

Variables

struct state state
 
struct statest = &state
 

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" ;
#define TYPE_STRING
Definition: gis.h:162
#define YES
Definition: gis.h:163
#define NO
Definition: gis.h:164
#define TYPE_DOUBLE
Definition: gis.h:161
struct Option * G_define_option(void)
Initializes an Option struct.
Definition: parser.c:209

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.

Overview table: Parser standard options

(C) 2001-2015 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
Original author CERL
Soeren Gebbert added Dec. 2009 WPS process_description document

Definition in file parser.c.

Macro Definition Documentation

◆ MAX_MATCHES

#define MAX_MATCHES   50

Definition at line 99 of file parser.c.

Enumeration Type Documentation

◆ opt_error

enum opt_error
Enumerator
BAD_SYNTAX 
OUT_OF_RANGE 
MISSING_VALUE 
INVALID_VALUE 
AMBIGUOUS 
REPLACED 

Definition at line 89 of file parser.c.

Function Documentation

◆ append_error()

void append_error ( const char *  msg)
static

◆ check_an_opt()

void check_an_opt ( const char *  key,
int  type,
const char *  options,
const char **  opts,
char **  answerp 
)
static

◆ check_double()

int check_double ( const char *  ans,
const char **  opts 
)
static

Definition at line 1339 of file parser.c.

References BAD_SYNTAX, contains(), d, INVALID_VALUE, MISSING_VALUE, Option::opts, and OUT_OF_RANGE.

Referenced by check_an_opt().

◆ check_int()

int check_int ( const char *  ans,
const char **  opts 
)
static

Definition at line 1289 of file parser.c.

References BAD_SYNTAX, contains(), d, INVALID_VALUE, MISSING_VALUE, Option::opts, and OUT_OF_RANGE.

Referenced by check_an_opt().

◆ check_multiple_opts()

void check_multiple_opts ( void  )
static

◆ check_opts()

◆ check_overwrite()

◆ check_required()

void check_required ( void  )
static

◆ check_string()

int check_string ( const char *  ans,
const char **  opts,
int *  result 
)
static

◆ contains()

int contains ( const char *  s,
int  c 
)
static

Definition at line 1010 of file parser.c.

References c, FALSE, s, and TRUE.

Referenced by check_double(), and check_int().

◆ define_keywords()

void define_keywords ( void  )
static

Definition at line 938 of file parser.c.

References state::n_keys, state::n_keys_alloc, and st.

Referenced by G_define_module().

◆ G__print_keywords()

void G__print_keywords ( FILE *  fd,
void(*)(FILE *, const char *)  format 
)

Print list of keywords (internal use only)

If format function is NULL than list of keywords is printed comma-separated.

Parameters
[out]fdfile where to print
formatpointer to print function

Definition at line 909 of file parser.c.

References format(), GModule::keywords, state::module_info, state::n_keys, and st.

Referenced by G__usage_html(), G__usage_rest(), G__usage_xml(), and usage().

◆ G__split_gisprompt()

void G__split_gisprompt ( const char *  gisprompt,
char *  age,
char *  element,
char *  desc 
)

Definition at line 1652 of file parser.c.

References Option::gisprompt.

Referenced by check_overwrite(), G__json(), and G__uses_new_gisprompt().

◆ G__uses_new_gisprompt()

◆ G_add_keyword()

void G_add_keyword ( const char *  keyword)

Add keyword to the list.

Parameters
keywordkeyword string

Definition at line 849 of file parser.c.

References G_store(), GModule::keywords, state::module_info, state::n_keys, state::n_keys_alloc, and st.

◆ G_close_option_file()

void G_close_option_file ( FILE *  fp)

Close an input/output file returned by G_open_option_file(). If the file pointer is stdin, stdout, or stderr, nothing happens.

Parameters
filepointer

Definition at line 1836 of file parser.c.

◆ G_define_flag()

struct Flag * G_define_flag ( void  )

Initializes a Flag struct.

Allocates memory for the Flag structure and returns a pointer to this memory.

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
Pointer to a Flag struct

Definition at line 155 of file parser.c.

References state::current_flag, state::current_item, state::first_flag, state::first_item, Item::flag, G_zero(), state::n_flags, state::n_items, Flag::next_flag, Item::next_item, NULL, Item::option, and st.

Referenced by G_define_standard_flag().

◆ G_define_module()

struct GModule * G_define_module ( void  )

Initializes a new module.

Returns
pointer to a GModule struct

Definition at line 254 of file parser.c.

References define_keywords(), G_zero(), state::module_info, and st.

◆ G_define_option()

struct Option * G_define_option ( void  )

Initializes an Option struct.

Allocates memory for the Option structure and returns a pointer to this memory.

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 against this string.

Returns
pointer to an Option struct

Definition at line 209 of file parser.c.

References state::current_item, state::current_option, state::first_item, state::first_option, G_zero(), Option::multiple, state::n_items, state::n_opts, Item::next_item, Option::next_opt, NO, Item::option, Option::required, and st.

Referenced by G_define_standard_option(), M_define_option(), N_define_standard_option(), and Rast3d_set_window_params().

◆ G_disable_interactive()

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

Definition at line 138 of file parser.c.

References state::no_interactive, and st.

◆ G_get_overwrite()

int G_get_overwrite ( )

Get overwrite value.

Returns
1 overwrite enabled
0 overwrite disabled

Definition at line 933 of file parser.c.

References state::module_info, GModule::overwrite, and st.

Referenced by copy_table(), V1_open_new_ogr(), and V1_open_new_pg().

◆ G_open_option_file()

FILE * G_open_option_file ( const struct Option option)

Get an input/output file pointer from the option. If the file name is omitted or '-', it returns either stdin or stdout based on the gisprompt.

Calls G_fatal_error() on error. File pointer can be later closed by G_close_option_file().

FILE *fp_input;
FILE *fp_output;
struct Option *opt_input;
struct Option *opt_output;
if (G_parser(argc, argv))
exit(EXIT_FAILURE);
fp_input = G_open_option_file(opt_input);
fp_output = G_open_option_file(opt_output);
...
G_close_option_file(fp_input);
@ G_OPT_F_INPUT
Definition: gis.h:290
@ G_OPT_F_OUTPUT
Definition: gis.h:292
int G_parser(int argc, char **argv)
Parse command line.
Definition: parser.c:319
FILE * G_open_option_file(const struct Option *option)
Get an input/output file pointer from the option. If the file name is omitted or '-',...
Definition: parser.c:1799
void G_close_option_file(FILE *fp)
Close an input/output file returned by G_open_option_file(). If the file pointer is stdin,...
Definition: parser.c:1836
struct Option * G_define_standard_option(int opt)
Create standardised Option structure.
Structure that stores option information.
Definition: gis.h:533
Parameters
optionpointer to a file option
Returns
file pointer

Definition at line 1799 of file parser.c.

References _, Option::answer, G_fatal_error(), Option::gisprompt, Option::key, Option::multiple, and NULL.

◆ G_option_to_separator()

char * G_option_to_separator ( const struct Option option)

Get separator string from the option.

Calls G_fatal_error() on error. Allocated string can be later freed by G_free().

char *fs;
struct Option *opt_fs;
if (G_parser(argc, argv))
exit(EXIT_FAILURE);
fs = G_option_to_separator(opt_fs);
@ G_OPT_F_SEP
Definition: gis.h:293
char * G_option_to_separator(const struct Option *option)
Get separator string from the option.
Definition: parser.c:1737
Parameters
optionpointer to separator option
Returns
allocated string with separator

Definition at line 1737 of file parser.c.

References _, Option::answer, G_debug(), G_fatal_error(), G_store(), Option::gisprompt, Option::key, and NULL.

◆ G_parser()

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:

  1. G_gisinit()
  2. G_define_module()
  3. G_define_standard_flag()
  4. G_define_standard_option()
  5. G_define_flag()
  6. G_define_option()
  7. G_option_exclusive()
  8. G_option_required()
  9. G_option_requires()
  10. G_option_requires_all()
  11. G_option_excludes()
  12. G_option_collective()
  13. G_parser()
Parameters
argcnumber of arguments
argvargument list
Returns
0 on success
-1 on error and calls G_usage()

Definition at line 319 of file parser.c.

References _, Option::answer, Option::answers, append_error(), check_multiple_opts(), check_opts(), check_overwrite(), check_required(), Option::count, Option::def, Option::description, GModule::description, Option::descriptions, Option::descs, err(), state::error, FALSE, state::first_option, G__check_option_rules(), G__has_required_rule(), G__json(), G__script(), G__usage_html(), G__usage_rest(), G__usage_text(), G__usage_xml(), G__wps_print_process_description(), G_asprintf(), G_basename(), G_chop(), G_fatal_error(), G_free_tokens(), G_getenv_nofatal(), G_is_dirsep(), G_store(), G_strcasecmp(), G_suppress_warnings(), G_tokenize(), G_usage(), G_verbose(), G_verbose_max(), G_verbose_min(), G_verbose_std(), G_warning(), state::has_required, is_option(), Option::key, Option::label, GModule::label, module_gui_wx(), state::module_info, Option::multiple, state::n_errors, state::n_opts, Option::next_opt, state::no_interactive, NULL, Option::options, Option::opts, state::overwrite, state::pgm_name, state::pgm_path, state::quiet, Option::required, set_flag(), set_option(), split_opts(), st, state::suppress_overwrite, state::suppress_required, TRUE, valid_option_name(), and GModule::verbose.

◆ G_recreate_command()

char * G_recreate_command ( void  )

Creates command to run non-interactive.

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

Returns
pointer to a char string

Definition at line 821 of file parser.c.

References FALSE, and recreate_command().

Referenced by D_open_driver(), Rast_command_history(), and Vect_hist_command().

◆ G_recreate_command_original_path()

char * G_recreate_command_original_path ( void  )

Creates command to run non-interactive.

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

This gives the same as G_recreate_command() but the original path from the command line is used instead of the module name only.

Returns
pointer to a char string

Definition at line 839 of file parser.c.

References recreate_command(), and TRUE.

Referenced by module_gui_wx().

◆ G_set_keywords()

void G_set_keywords ( const char *  keywords)

Set keywords from the string.

Parameters
keywordskeywords separated by commas

Definition at line 865 of file parser.c.

References G_number_of_tokens(), G_tokenize(), GModule::keywords, state::module_info, state::n_keys, state::n_keys_alloc, and st.

◆ get_renamed_option()

const char * get_renamed_option ( const char *  key)
static

◆ is_option()

int is_option ( const char *  string)
static

Definition at line 1037 of file parser.c.

Referenced by G_parser().

◆ match_option()

int match_option ( const char *  string,
const char *  option 
)
static

Definition at line 1070 of file parser.c.

References match_option_1().

Referenced by check_string(), and set_option().

◆ match_option_1()

int match_option_1 ( const char *  string,
const char *  option 
)
static

Definition at line 1044 of file parser.c.

References match_option_1(), and next().

Referenced by match_option(), and match_option_1().

◆ module_gui_wx()

int module_gui_wx ( void  )
static

Invoke GUI dialog.

The remaining routines are all local (static) routines used to support the parsing process.

Definition at line 954 of file parser.c.

References _, G_fatal_error(), G_program_name(), G_recreate_command_original_path(), G_spawn(), getenv(), GPATH_MAX, NULL, state::pgm_path, and st.

Referenced by G_parser().

◆ recreate_command()

char * recreate_command ( int  original_path)

Creates command to run non-interactive.

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

Parameters
original_pathTRUE if original path should be used, FALSE for stripped and clean name of the module
Returns
pointer to a char string

Definition at line 664 of file parser.c.

References Option::answer, Flag::answer, Option::answers, cur, state::first_flag, state::first_option, G_debug(), G_original_program_name(), G_program_name(), G_verbose_max(), G_verbose_std(), Option::key, Flag::key, state::module_info, state::n_flags, state::n_opts, Flag::next_flag, Option::next_opt, state::overwrite, st, tmp, Option::type, TYPE_STRING, and GModule::verbose.

Referenced by G_recreate_command(), and G_recreate_command_original_path().

◆ set_flag()

◆ set_option()

◆ split_opts()

void split_opts ( void  )
static

Definition at line 1467 of file parser.c.

References Option::answer, Option::answers, state::first_option, state::n_opts, Option::next_opt, NULL, and st.

Referenced by G_parser().

◆ valid_option_name()

int valid_option_name ( const char *  string)
static

Definition at line 1020 of file parser.c.

Referenced by G_parser().

Variable Documentation

◆ st

◆ state

struct state state

Definition at line 102 of file parser.c.

Referenced by LZ4_slideInputBuffer(), and tokenize().