Register and parse command line options and read/write configuration files. More...

#include <sc_keyvalue.h>

Include dependency graph for sc_options.h:

Typedefs
typedef struct sc_options	sc_options_t
	The options data structure is opaque.

typedef int(*	sc_options_callback_t) (sc_options_t opt, const char opt_arg, void *data)
	This callback can be invoked with sc_options_parse. More...

Functions
sc_options_t *	sc_options_new (const char *program_path)
	Create an empty options structure. More...

void	sc_options_destroy_deep (sc_options_t *opt)
	Destroy the options structure and all allocated structures contained. More...

void	sc_options_destroy (sc_options_t *opt)
	Destroy the options structure. More...

void	sc_options_set_spacing (sc_options_t *opt, int space_type, int space_help)
	Set the spacing for sc_options_print_summary. More...

void	sc_options_print_usage (int package_id, int log_priority, sc_options_t opt, const char arg_usage)
	Print a usage message. More...

void	sc_options_print_summary (int package_id, int log_priority, sc_options_t *opt)
	Print a summary of all option values. More...

int	sc_options_parse (int package_id, int err_priority, sc_options_t opt, int argc, char *argv)
	Parse command line options. More...

Add option variables
void	sc_options_add_switch (sc_options_t opt, int opt_char, const char opt_name, int variable, const char help_string)
	Add a switch option. More...

void	sc_options_add_bool (sc_options_t opt, int opt_char, const char opt_name, int variable, int init_value, const char help_string)
	Add a boolean option. More...

void	sc_options_add_int (sc_options_t opt, int opt_char, const char opt_name, int variable, int init_value, const char help_string)
	Add an option that takes an integer argument. More...

void	sc_options_add_size_t (sc_options_t opt, int opt_char, const char opt_name, size_t variable, size_t init_value, const char help_string)
	Add an option that takes a size_t argument. More...

void	sc_options_add_double (sc_options_t opt, int opt_char, const char opt_name, double variable, double init_value, const char help_string)
	Add an option that takes a double argument. More...

void	sc_options_add_string (sc_options_t opt, int opt_char, const char opt_name, const char *variable, const char init_value, const char *help_string)
	Add a string option. More...

void	sc_options_add_inifile (sc_options_t opt, int opt_char, const char opt_name, const char *help_string)
	Add an option to read in a file in `.ini` format. More...

void	sc_options_add_jsonfile (sc_options_t opt, int opt_char, const char opt_name, const char *help_string)
	Add an option to read in a file in JSON format. More...

void	sc_options_add_callback (sc_options_t opt, int opt_char, const char opt_name, int has_arg, sc_options_callback_t fn, void data, const char help_string)
	Add an option that calls a user-defined function when parsed. More...

void	sc_options_add_keyvalue (sc_options_t opt, int opt_char, const char opt_name, int variable, const char init_value, sc_keyvalue_t keyvalue, const char help_string)
	Add an option that takes string keys into a lookup table of integers. More...

void	sc_options_add_suboptions (sc_options_t opt, sc_options_t subopt, const char *prefix)
	Copy one set of options to another as a subset, with a prefix. More...

Load and save configuration files
int	sc_options_load (int package_id, int err_priority, sc_options_t opt, const char file)
	Load a file in the default format and update option values. More...

int	sc_options_load_ini (int package_id, int err_priority, sc_options_t opt, const char inifile, void *re)
	Load a file in `.ini` format and update entries found under [Options]. More...

int	sc_options_load_json (int package_id, int err_priority, sc_options_t opt, const char jsonfile, void *re)
	Load a file in JSON format and update entries from object "Options". More...

int	sc_options_save (int package_id, int err_priority, sc_options_t opt, const char inifile)
	Save all options and arguments to a file in `.ini` format. More...

int	sc_options_load_args (int package_id, int err_priority, sc_options_t opt, const char inifile)
	Load a file in `.ini` format and update entries found under [Arguments]. More...

Detailed Description

Register and parse command line options and read/write configuration files.

A detailed description can be found under Option Parser. In addition, we provide the example options.c.

Typedef Documentation

◆ sc_options_callback_t

typedef int(* sc_options_callback_t) (sc_options_t *opt, const char *opt_arg, void *data)

This callback can be invoked with sc_options_parse.

Parameters

[in]	opt	Valid options data structure. This is passed as a matter of principle.
[in]	opt_arg	The option argument or NULL if there is none. This variable is internal. Do not store pointer.
[in]	data	User-defined data passed to sc_options_add_callback.

Returns: Return 0 if successful, -1 to indicate a parse error.

Function Documentation

◆ sc_options_add_bool()

void sc_options_add_bool	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		int *	variable,
		int	init_value,
		const char *	help_string
	)

Add a boolean option.

It can be initialized to true or false in the C sense. Specifying it on the command line without argument sets the option to true. The argument 0/f/F/n/N sets it to false (0). The argument 1/t/T/y/Y sets it to true (nonzero).

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	variable	Address of the variable to store the option value.
[in]	init_value	Initial value to set the option, read as true or false.
[in]	help_string	Help string for usage message, may be NULL.

◆ sc_options_add_callback()

void sc_options_add_callback	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		int	has_arg,
		sc_options_callback_t	fn,
		void *	data,
		const char *	help_string
	)

Add an option that calls a user-defined function when parsed.

The callback function should be implemented to allow multiple calls. The callback may be used to set multiple option variables in bulk that would otherwise require an inconvenient number of individual options. This option is not loaded from or saved to files.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	has_arg	Specify whether the option needs an option argument. This can be 0 for none, 1 for a required argument, and 2 for an optional argument; see getopt_long (3).
[in]	fn	Function to call when this option is encountered.
[in]	data	User-defined data passed to the callback.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_add_double()

void sc_options_add_double	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		double *	variable,
		double	init_value,
		const char *	help_string
	)

Add an option that takes a double argument.

The double must be in the legal range. "inf" and "nan" are legal too.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	variable	Address of the variable to store the option value.
[in]	init_value	The initial value of the option variable.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_add_inifile()

void sc_options_add_inifile	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		const char *	help_string
	)

Add an option to read in a file in .ini format.

The argument to this option must be a filename. On parsing the specified file is read to set known option variables. It does not have an associated option variable itself.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_add_int()

void sc_options_add_int	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		int *	variable,
		int	init_value,
		const char *	help_string
	)

Add an option that takes an integer argument.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	variable	Address of the variable to store the option value.
[in]	init_value	The initial value of the option variable.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_add_jsonfile()

void sc_options_add_jsonfile	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		const char *	help_string
	)

Add an option to read in a file in JSON format.

The argument to this option must be a filename. On parsing the specified file is read to set known option variables. It does not have an associated option variable itself.

This functionality is only active when sc_have_json returns true, equivalent to the define SC_HAVE_JSON existing, and ignored otherwise.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_add_keyvalue()

void sc_options_add_keyvalue	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		int *	variable,
		const char *	init_value,
		sc_keyvalue_t *	keyvalue,
		const char *	help_string
	)

Add an option that takes string keys into a lookup table of integers.

On calling this function, it must be certain that the initial value exists.

Parameters

[in]	opt	Initialized options structure.
[in]	opt_char	Option character for command line, or 0.
[in]	opt_name	Name of the long option, or NULL.
[in]	variable	Address of an existing integer that holds the value of this option parameter.
[in]	init_value	The key that is looked up for the initial value. It must be certain that the key exists and its value is of type integer.
[in]	keyvalue	A valid key-value structure where the values must be integers. If a key is asked for that does not exist, we will produce an option error. This structure must stay alive as long as opt.
[in]	help_string	Instructive one-line string to explain the option.

Examples: options.c.

◆ sc_options_add_size_t()

void sc_options_add_size_t	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		size_t *	variable,
		size_t	init_value,
		const char *	help_string
	)

Add an option that takes a size_t argument.

The value of the size_t variable must not be greater than LLONG_MAX.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	variable	Address of the variable to store the option value.
[in]	init_value	The initial value of the option variable.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_add_string()

void sc_options_add_string	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		const char **	variable,
		const char *	init_value,
		const char *	help_string
	)

Add a string option.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	variable	Address of the variable to store the option value.
[in]	init_value	This default value of the option may be NULL. If not NULL, the value is copied to internal storage.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_add_suboptions()

void sc_options_add_suboptions	(	sc_options_t *	opt,
		sc_options_t *	subopt,
		const char *	prefix
	)

Copy one set of options to another as a subset, with a prefix.

The variables referenced by the options and the suboptions are the same.

Parameters

[in,out]	opt	A set of options.
[in]	subopt	Another set of options to be copied.
[in]	prefix	The prefix to add to option names as they are copied. If an option has a long name "name" in subopt, its name in opt is "prefix:name"; if an option only has a character 'c' in subopt, its name in opt is "prefix:-c".

Examples: options.c.

◆ sc_options_add_switch()

void sc_options_add_switch	(	sc_options_t *	opt,
		int	opt_char,
		const char *	opt_name,
		int *	variable,
		const char *	help_string
	)

Add a switch option.

This option is used without option arguments. Every use increments the variable by one. Its initial value is 0. Either opt_char or opt_name must be valid, that is, not '\0'/NULL.

Parameters

[in,out]	opt	A valid options structure.
[in]	opt_char	Short option character, may be '\0'.
[in]	opt_name	Long option name without initial dashes, may be NULL.
[in]	variable	Address of the variable to store the option value.
[in]	help_string	Help string for usage message, may be NULL.

Examples: options.c.

◆ sc_options_destroy()

void sc_options_destroy ( sc_options_t * opt )

Destroy the options structure.

Whatever has been passed into sc_keyvalue_add is left alone.

Parameters

[in,out] opt This options structure is deallocated.

Examples: options.c.

◆ sc_options_destroy_deep()

void sc_options_destroy_deep ( sc_options_t * opt )

Destroy the options structure and all allocated structures contained.

The keyvalue structure passed into sc_keyvalue_add is destroyed.

Parameters

[in,out] opt This options structure is deallocated, including all key-value containers referenced.

Deprecated:: This function is kept for backwards compatibility. It is best to destroy any key-value container outside of the lifetime of the options object.

◆ sc_options_load()

int sc_options_load	(	int	package_id,
		int	err_priority,
		sc_options_t *	opt,
		const char *	file
	)

Load a file in the default format and update option values.

The default is a file in the .ini format; see sc_options_load_ini.

Parameters

[in]	package_id	Registered package id or -1.
[in]	err_priority	Error priority according to Log Priorities.
[in]	opt	The option structure.
[in]	file	Filename of the file to load.

Returns: Returns 0 on success, -1 on failure.

Examples: options.c.

◆ sc_options_load_args()

int sc_options_load_args	(	int	package_id,
		int	err_priority,
		sc_options_t *	opt,
		const char *	inifile
	)

Load a file in .ini format and update entries found under [Arguments].

There needs to be a key Arguments.count specifying the number. Then as many integer keys starting with 0 need to be present.

Parameters

[in]	package_id	Registered package id or -1.
[in]	err_priority	Error priority according to Log Priorities.
[in]	opt	The args are stored in this option structure.
[in]	inifile	Filename of the ini file to load.

Returns: Returns 0 on success, -1 on failure.

Examples: options.c.

◆ sc_options_load_ini()

int sc_options_load_ini	(	int	package_id,
		int	err_priority,
		sc_options_t *	opt,
		const char *	inifile,
		void *	re
	)

Load a file in .ini format and update entries found under [Options].

An option whose name contains a colon such as "prefix:basename" will be updated by a "basename =" entry in a [prefix] section.

Parameters

[in]	package_id	Registered package id or -1.
[in]	err_priority	Error priority according to Log Priorities.
[in]	opt	The option structure.
[in]	inifile	Filename of the ini file to load.
[in,out]	re	Provisioned for runtime error checking implementation; currently must be NULL.

Returns: Returns 0 on success, -1 on failure.

◆ sc_options_load_json()

int sc_options_load_json	(	int	package_id,
		int	err_priority,
		sc_options_t *	opt,
		const char *	jsonfile,
		void *	re
	)

Load a file in JSON format and update entries from object "Options".

An option whose name contains a colon such as "Prefix:basename" will be updated by a "basename :" entry in a "Prefix" nested object.

Parameters

[in]	package_id	Registered package id or -1.
[in]	err_priority	Error priority according to Log Priorities.
[in]	opt	The option structure.
[in]	jsonfile	Filename of the JSON file to load.
[in,out]	re	Provisioned for runtime error checking implementation; currently must be NULL.

Returns: Returns 0 on success, -1 on failure.

◆ sc_options_new()

sc_options_t* sc_options_new ( const char * program_path )

Create an empty options structure.

Parameters

[in] program_path Name or path name of the program to display. Usually argv[0] is fine.

Returns: A valid and empty options structure.

Examples: options.c.

◆ sc_options_parse()

int sc_options_parse	(	int	package_id,
		int	err_priority,
		sc_options_t *	opt,
		int	argc,
		char **	argv
	)

Parse command line options.

Parameters

[in]	package_id	Registered package id or -1.
[in]	err_priority	Error priority according to Log Priorities.
[in]	opt	The option structure.
[in]	argc	Length of argument list.
[in,out]	argv	Argument list may be permuted.

Returns: Returns -1 on an invalid option, otherwise the position of the first non-option argument.

Examples: options.c.

◆ sc_options_print_summary()

void sc_options_print_summary	(	int	package_id,
		int	log_priority,
		sc_options_t *	opt
	)

Print a summary of all option values.

Prints the title "Options:" and a line for every option, then the title "Arguments:" and a line for every argument. This function uses the SC_LC_GLOBAL log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler.

Parameters

[in]	package_id	Registered package id or -1.
[in]	log_priority	Priority for output according to Log Priorities.
[in]	opt	The option structure.

Examples: options.c.

◆ sc_options_print_usage()

void sc_options_print_usage	(	int	package_id,
		int	log_priority,
		sc_options_t *	opt,
		const char *	arg_usage
	)

Print a usage message.

This function uses the SC_LC_GLOBAL log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler.

Parameters

[in]	package_id	Registered package id or -1.
[in]	log_priority	Priority for output according to Log Priorities.
[in]	opt	The option structure.
[in]	arg_usage	If not NULL, an <ARGUMENTS> string is appended to the usage line. If the string is non-empty, it will be printed after the option summary and an "ARGUMENTS:\n" title line. Line breaks are identified by strtok(3) and honored.

Examples: options.c.

◆ sc_options_save()

int sc_options_save	(	int	package_id,
		int	err_priority,
		sc_options_t *	opt,
		const char *	inifile
	)

Save all options and arguments to a file in .ini format.

This function must only be called after successful option parsing. This function should only be called on rank 0. This function will log errors with category SC_LC_GLOBAL. An options whose name contains a colon such as "Prefix:basename" will be written in a section titled [Prefix] as "basename =".

Parameters

[in]	package_id	Registered package id or -1.
[in]	err_priority	Error priority according to Log Priorities.
[in]	opt	The option structure.
[in]	inifile	Filename of the ini file to save.

Returns: Returns 0 on success, -1 on failure.

Examples: options.c.

◆ sc_options_set_spacing()

void sc_options_set_spacing	(	sc_options_t *	opt,
		int	space_type,
		int	space_help
	)

Set the spacing for sc_options_print_summary.

There are two values to be set: the spacing from the beginning of the printed line to the type of the option variable, and from the beginning of the printed line to the help string.

Parameters

[in,out]	opt	Valid options structure.
[in]	space_type	Number of spaces to the type display, for example <INT>, <STRING>, etc. Setting this negative sets the default 20.
[in]	space_help	Number of space to the help string. Setting this negative sets the default 32.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ sc_options_callback_t

Function Documentation

◆ sc_options_add_bool()

◆ sc_options_add_callback()

◆ sc_options_add_double()

◆ sc_options_add_inifile()

◆ sc_options_add_int()

◆ sc_options_add_jsonfile()

◆ sc_options_add_keyvalue()

◆ sc_options_add_size_t()

◆ sc_options_add_string()

◆ sc_options_add_suboptions()

◆ sc_options_add_switch()

◆ sc_options_destroy()

◆ sc_options_destroy_deep()

◆ sc_options_load()

◆ sc_options_load_args()

◆ sc_options_load_ini()

◆ sc_options_load_json()

◆ sc_options_new()

◆ sc_options_parse()

◆ sc_options_print_summary()

◆ sc_options_print_usage()

◆ sc_options_save()

◆ sc_options_set_spacing()