GIS Library - Argument parsing functions. More...

#include <errno.h>
#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
void	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 GModule *	G_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 ), int newline)
	Print list of keywords (internal use only) More...

int	G_get_overwrite (void)
	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 state *	st = &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" ;

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

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

Function Documentation

◆ G__print_keywords()

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

Print list of keywords (internal use only)

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

Parameters

[out]	fd	file where to print
	format	pointer to print function
	newline	TRUE to include newline

Definition at line 927 of file parser.c.

◆ G__split_gisprompt()

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

Definition at line 1772 of file parser.c.

References Option::gisprompt.

Referenced by G__uses_new_gisprompt().

◆ G__uses_new_gisprompt()

int G__uses_new_gisprompt ( void )

Definition at line 890 of file parser.c.

References G__split_gisprompt(), Option::gisprompt, Option::next_opt, and st.

◆ G_add_keyword()

void G_add_keyword ( const char * keyword )

Add keyword to the list.

Parameters

keyword keyword string

Definition at line 866 of file parser.c.

References G_realloc, G_store(), 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

file pointer

Definition at line 1958 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 157 of file parser.c.

References G_malloc, G_zero(), NULL, 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 256 of file parser.c.

References G_zero(), 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 211 of file parser.c.

References G_malloc, G_zero(), Option::multiple, NO, Option::required, and st.

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

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

References st.

◆ G_get_overwrite()

int G_get_overwrite ( void )

Get overwrite value.

Returns: 1 overwrite enabled; 0 overwrite disabled

Definition at line 957 of file parser.c.

References st.

Referenced by V1_open_new_ogr().

◆ 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;
 
opt_input = G_define_standard_option(G_OPT_F_INPUT);
opt_output = G_define_standard_option(G_OPT_F_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_close_option_file(fp_output);

Parameters

option pointer to a file option

Returns: file pointer

Definition at line 1919 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;
 
opt_fs = G_define_standard_option(G_OPT_F_SEP);
 
if (G_parser(argc, argv))
exit(EXIT_FAILURE);
 
fs = G_option_to_separator(opt_fs);

Parameters

option pointer to separator option

Returns: allocated string with separator

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

Parameters

argc	number of arguments
argv	argument list

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

Definition at line 321 of file parser.c.

References _, err(), FALSE, G_basename(), G_is_dirsep(), G_store(), G_verbose_std(), G_warning(), Option::key, NULL, Option::required, and st.

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

References FALSE, and recreate_command().

Referenced by 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 856 of file parser.c.

References recreate_command(), and TRUE.

◆ G_set_keywords()

void G_set_keywords ( const char * keywords )

Set keywords from the string.

Parameters

keywords keywords separated by commas

Definition at line 882 of file parser.c.

References G_number_of_tokens(), G_tokenize(), and st.

◆ 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_path TRUE if original path should be used, FALSE for stripped and clean name of the module

Returns: pointer to a char string

Definition at line 678 of file parser.c.

Referenced by G_recreate_command(), and G_recreate_command_original_path().

Variable Documentation

◆ st

struct state* st = &state

Definition at line 104 of file parser.c.

Referenced by AMI_STREAM< T >::AMI_STREAM(), D_setup2(), db_d_append_error(), db_d_init_error(), db_d_report_error(), G__read_env(), G__read_gisrc_path(), G__uses_new_gisprompt(), G__write_env(), G_add_keyword(), G_area_of_cell_at_row(), G_area_of_polygon(), G_create_alt_env(), G_create_alt_search_path(), G_darea0_on_ellipsoid(), G_darea0_on_sphere(), G_define_flag(), G_define_module(), G_define_option(), G_disable_interactive(), G_distance(), G_get_available_mapsets(), G_get_gisrc_mode(), G_get_mapset_name(), G_get_overwrite(), G_is_mapset_in_search_path(), G_ls2(), G_parser(), G_percent_reset(), G_plot_fx(), G_plot_point(), G_plot_where_en(), G_reset_mapsets(), G_rhumbline_lat_from_lon(), G_set_geodesic_distance_lat1(), G_set_geodesic_distance_lat2(), G_set_keywords(), G_set_ls_exclude_filter(), G_set_ls_filter(), G_set_verbose(), G_setup_fill(), G_setup_plot(), G_switch_search_path(), G_unset_window(), G_verbose(), gsd_put_legend(), AMI_STREAM< T >::new_substream(), open_stream(), Rast_close_gdal_write_link(), Rast_create_gdal_link(), sqpAllocCol(), sqpAllocVal(), sqpFreeStmt(), sqpInitParser(), sqpInitStmt(), and sqpPrintStmt().

◆ state

struct state state

Definition at line 1 of file parser.c.

Referenced by db__add_cursor_to_driver_state(), db__close_all_cursors(), db__drop_cursor_from_driver_state(), db__get_driver_state(), db__init_driver_state(), db__mark_database_closed(), db__mark_database_open(), db__test_database_open(), G_popen_clear(), G_popen_close(), LZ4_compress_fast_extState(), LZ4_resetStreamState(), and LZ4_slideInputBuffer().

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ MAX_MATCHES

Enumeration Type Documentation

◆ opt_error

Function Documentation

◆ G__print_keywords()

◆ G__split_gisprompt()

◆ G__uses_new_gisprompt()

◆ G_add_keyword()

◆ G_close_option_file()

◆ G_define_flag()

◆ G_define_module()

◆ G_define_option()

◆ G_disable_interactive()

◆ G_get_overwrite()

◆ G_open_option_file()

◆ G_option_to_separator()

◆ G_parser()

◆ G_recreate_command()

◆ G_recreate_command_original_path()

◆ G_set_keywords()

◆ recreate_command()

Variable Documentation

◆ st

◆ state