#include <option_info.h>

Classes
struct	callback_entry_t

Public Types
typedef int	callback_id_t

typedef std::function< void(option_info const &opt)>	callback_t

typedef std::map< std::string, pointer_t >	map_by_name_t

typedef std::map< short_name_t, pointer_t >	map_by_short_name_t

typedef std::shared_ptr< option_info >	pointer_t

typedef std::vector< pointer_t >	vector_t

Public Member Functions
	option_info (std::string const &name, short_name_t short_name=NO_SHORT_NAME)
	Create a new option_info object.

callback_id_t	add_callback (callback_t const &c)
	Add a callback to call on a change to this value.

void	add_flag (flag_t flag)
	Make sure a given flag is set.

bool	add_value (std::string const &value, string_list_t const &option_keys=string_list_t(), option_source_t source=option_source_t::SOURCE_DIRECT)
	Add a value to this option.

int	find_value_index_by_key (std::string key, int idx=0) const
	Get the index at which a value with the given key is defined.

pointer_t	get_alias_destination () const
	Get a link to the destination alias.

std::string	get_basename () const
	Retrieve the name of the option without any section names.

std::string const &	get_default () const
	Retrieve the default value.

double	get_double (int idx=0) const
	Get the value as a double.

std::string	get_environment_variable_name () const
	Retrieve the environment variable name of this option.

bool	get_environment_variable_value (std::string &value, char const *intro=nullptr) const
	Retrieve the environment variable value of this option.

flag_t	get_flags () const
	Retrieve the flags.

std::string const &	get_help () const
	Get the help string.

long	get_long (int idx=0) const
	Get the value as a long.

string_list_t const &	get_multiple_separators () const
	Retrieve the list of separators for this argument.

std::string const &	get_name () const
	Get the long name of the option.

std::string	get_section_name () const
	Retrieve the name of the sections.

string_list_t	get_section_name_list () const
	Retrieve a list of section names.

short_name_t	get_short_name () const
	Get the short name of the option.

validator::pointer_t	get_validator () const
	Retrieve a pointer to the validator.

std::string	get_value (int idx=0, bool raw=false) const
	Retrieve the value.

variables::pointer_t	get_variables () const
	Retrieve the list of variables held by this option info.

bool	has_default () const
	Check whether this option has a default value.

bool	has_flag (flag_t flag) const
	Check whether a flag is set.

bool	has_value (std::string const &value) const
	Check whether one of the values matches the input.

bool	is_default_option () const
	Check whether this is the default option.

bool	is_defined () const
	Check whether a value is defined.

void	lock (bool always=true)
	Lock this value.

void	remove_callback (callback_id_t id)
	Remove a callback.

void	remove_default ()
	Remove the default value.

void	remove_flag (flag_t flag)
	Make sure a given flag is not set.

void	reset ()
	Reset this value.

void	set_alias_destination (pointer_t destination)
	Set the alias option.

void	set_default (char const *default_value)
	Set the default value of this option.

void	set_default (std::string const &default_value)
	Set the default value.

void	set_environment_variable_name (char const *name)
	Set the default value of this option.

void	set_environment_variable_name (std::string const &name)
	Set the option specific environment variable name.

void	set_flags (flag_t flags)
	Get the flags.

void	set_help (char const *help)
	Set the help string for this option.

void	set_help (std::string const &help)
	Set the help string for this option.

void	set_multiple_separators (char const const separators)
	Set the list of separators.

void	set_multiple_separators (string_list_t const &separators)
	Set the list of separators.

bool	set_multiple_values (std::string const &value, string_list_t const &option_keys=string_list_t(), option_source_t source=option_source_t::SOURCE_DIRECT)
	Set a multi-value at once.

void	set_short_name (short_name_t short_name)
	Assign a short name to an option.

bool	set_validator (std::nullptr_t)
	Clear the validator.

bool	set_validator (std::string const &name_and_params)
	Set the validator for this option.

bool	set_validator (validator::pointer_t validator)
	Set the validator for this option.

bool	set_value (int idx, std::string const &value, string_list_t const &option_keys=string_list_t(), option_source_t source=option_source_t::SOURCE_DIRECT)
	Replace a value.

void	set_variables (variables::pointer_t vars)
	Assign variables to this option info.

size_t	size () const
	Retrieve the number of values defined for this option.

option_source_t	source () const
	Return the source of this option info.

string_list_t const &	trace_sources () const
	Get the trace of this option.

void	unlock ()
	Unlock this value.

Static Public Member Functions
static void	set_configuration_filename (std::string const &filename)
	Save the filename of the current configuration file.

static void	set_trace_sources (bool trace)
	Whether the sources should be traced.

Private Types
typedef std::vector< callback_entry_t >	callback_vector_t

Private Member Functions
void	trace_source (int idx)
	Remember the source information at of this last change.

bool	validate_all_values ()
	Validate all the values of this option_info object.

bool	validates (int idx=0)
	Check a value validity.

void	value_changed (int idx)
	Call whenever the value changed so we can handle callbacks.

Private Attributes
pointer_t	f_alias_destination = pointer_t()

callback_vector_t	f_callbacks = callback_vector_t()

std::string	f_default_value = std::string()

std::vector< double >	f_double = std::vector<double>()

std::string	f_environment_variable_name = std::string()

flag_t	f_flags = GETOPT_FLAG_NONE

std::string	f_help = std::string()

std::vector< long >	f_integer = std::vector<long>()

string_list_t	f_multiple_separators = string_list_t()

std::string	f_name = std::string()

id_t	f_next_callback_id = 0

short_name_t	f_short_name = NO_SHORT_NAME

option_source_t	f_source = option_source_t::SOURCE_UNDEFINED

string_list_t	f_trace_sources = string_list_t()

validator::pointer_t	f_validator = validator::pointer_t()

string_list_t	f_value = string_list_t()

variables::pointer_t	f_variables = variables::pointer_t()

Detailed Description

Definition at line 75 of file option_info.h.

Member Typedef Documentation

◆ callback_id_t

typedef int advgetopt::option_info::callback_id_t

Definition at line 83 of file option_info.h.

◆ callback_t

typedef std::function<void (option_info const & opt)> advgetopt::option_info::callback_t

Definition at line 82 of file option_info.h.

◆ callback_vector_t

typedef std::vector<callback_entry_t> advgetopt::option_info::callback_vector_t

private

Definition at line 168 of file option_info.h.

◆ map_by_name_t

typedef std::map<std::string, pointer_t> advgetopt::option_info::map_by_name_t

Definition at line 80 of file option_info.h.

◆ map_by_short_name_t

typedef std::map<short_name_t, pointer_t> advgetopt::option_info::map_by_short_name_t

Definition at line 81 of file option_info.h.

◆ pointer_t

typedef std::shared_ptr<option_info> advgetopt::option_info::pointer_t

Definition at line 78 of file option_info.h.

◆ vector_t

typedef std::vector<pointer_t> advgetopt::option_info::vector_t

Definition at line 79 of file option_info.h.

Constructor & Destructor Documentation

◆ option_info()

advgetopt::option_info::option_info	(	std::string const &	name,
		short_name_t	short_name = `NO_SHORT_NAME`
	)

This function creates a new option_info object with the specified name and short_name. The short_name is optional.

When adding options to a map of options, all the long and short names must be unique. See the add_child() function for details.

The short_name parameter is a UTF-32 character. To not offer a short name for an option, use NO_SHORT_NAME as the value (which is the default if not specified to the constructor.)

Special Option Name: "--"

The "--" long name is viewed as the separator between options and filenames. When "--" is found by itself on the command line, then it is viewed as a switch to go from having options to only having filenames. Of course, these options may be used as any type of values, not just filenames (it could be URLs, email addresses, numbers, etc.)

The "--" separator cannot be assigned a short name.

Special Option Name: "*"

The "*" long name is viewed as the accept all option. This means all the options may not be defined in the list of options but we still want to accept them. This is to allow dynamically defined (supported) command options and especially to not have to declare all the valid options found in a configuration file.

Underscore and Dashes

It is customary to support dashes between words in options appearing on the command line (--help-me), however, it is unusual in configuration files where underscores are used instead (under_score.) When we compare option names, ‘’-' == '_'` is always considered true so either dashes or underscore can be used in both cases.

For this reason, the long name is saved with only dashes. That means all the maps are indexed using the long name with dashes.

Exceptions

getopt_exception_logic The constructor raises the invalid exception if the long name is an empty string since this is not allowed. It will also raise that exception if the name is the default option ("--") and a short name is also defined. (i.e. no short name is allowed along the default option.)

Parameters

[in]	name	The (long) name of this option.
[in]	short_name	The short name of this option (one character.)

Definition at line 224 of file option_info.cpp.

References add_flag(), f_name, advgetopt::GETOPT_FLAG_DEFAULT_OPTION, advgetopt::NO_SHORT_NAME, and advgetopt::option_flags_merge().

Member Function Documentation

◆ add_callback()

option_info::callback_id_t advgetopt::option_info::add_callback ( callback_t const & c )

Since we now officially support dynamically setting option values, we decided to add a callback mechanism that lets you know that an option changed. That way you can react to the change as soon as possible instead of having to poll for the value once in a while.

Parameters

[in] c The callback. Usually an std::bind() call.

Returns: The new callback identifier.

Definition at line 1985 of file option_info.cpp.

References f_callbacks, f_next_callback_id, advgetopt::get_global_mutex(), lock(), and advgetopt::option_flags_merge().

◆ add_flag()

void advgetopt::option_info::add_flag ( flag_t flag )

This function adds the given flag from the set of flags being set.

Note: Multiple flags can be defined in flag.

Parameters

[in] flag The flag(s) to set.

Definition at line 578 of file option_info.cpp.

References f_flags, advgetopt::option_flags_merge(), and set_flags().

Referenced by option_info(), lock(), and set_default().

◆ add_value()

bool advgetopt::option_info::add_value	(	std::string const &	value,
		string_list_t const &	option_keys = `string_list_t()`,
		option_source_t	source = `option_source_t::SOURCE_DIRECT`
	)

Whenever an option is found it may be followed by one or more values. This function is used to add these values to this option.

Later you can use the size() function to know how many values were added and the get_value() to retrieve any one of these values.

Warning: This function sets the value at offset 0 if it is already defined and the GETOPT_FLAG_MULTIPLE flag is not set in this option. In other words, you can't use this function to add multiple values if this option does not support that feature.

Parameters

[in]	value	The value to add to this option.
[in]	option_keys	The set of keys found at the end of the option name.
[in]	source	Where the value comes from.

Returns: true when the value was accepted (no error occurred).

See also: set_value()

Definition at line 1176 of file option_info.cpp.

References f_value, advgetopt::GETOPT_FLAG_MULTIPLE, has_flag(), advgetopt::option_flags_merge(), set_value(), and source().

◆ find_value_index_by_key()

int advgetopt::option_info::find_value_index_by_key	(	std::string	key,
		int	idx = `0`
	)		const

This function searches a value with the specified key and return the index where it was found.

If the function does not find a value starting with key, then it returns -1.

The function can be called with the start idx set to a value other than zero in which case the search starts at that index. It is valid to call the function with idx larger or equal to the number of values defined.

Exceptions

getopt_logic_error	If the `idx` parameter is negative, this exception is raised.
getopt_undefined	If no values were defined, this exception is raised. To avoid receiving the exception, make sure to first test with is_defined(). Note that if the requested key is not found, the function simply returns an empty string opposed to raising an exception.

Parameters

[in]	key	The key to search for.
[in]	idx	Start from this index.

Returns: The index at which that value is defined or -1 when not found.

Definition at line 1715 of file option_info.cpp.

References f_name, f_value, and advgetopt::option_flags_merge().

Referenced by set_value().

◆ get_alias_destination()

option_info::pointer_t advgetopt::option_info::get_alias_destination ( ) const

This function returns a pointer to the aliased option.

Returns: The alias or a nullptr.

Definition at line 1020 of file option_info.cpp.

References f_alias_destination.

◆ get_basename()

std::string advgetopt::option_info::get_basename ( ) const

The name of an option can include section names. These are rarely used on the command line, but they are useful for configuration files if you want to create multiple layers of options (a.k.a. sections.)

This function removes all the section names from the option name and returns what's left.

Returns: The base name without any section names.

Definition at line 344 of file option_info.cpp.

References f_name, and advgetopt::option_flags_merge().

◆ get_default()

std::string const & advgetopt::option_info::get_default ( ) const

This function returns the default value.

Returns: The default string value.

Definition at line 722 of file option_info.cpp.

References f_default_value.

◆ get_double()

double advgetopt::option_info::get_double ( int idx = 0 ) const

This function returns the value converted to a double.

If the value does not represent a valid double value, an error is emitted through the logger.

The value will be parsed through the variables if defined and this parameter allows it. This means the value may be a variable reference instead of an actually value (i.e. ${pi})

Note: The function will transform all the values in case this is a GETOPT_FLAG_MULTIPLE option and cache the results. Calling the function many times with the same index is very fast after the first time.

Exceptions

getopt_exception_undefined If the value was not defined, the function raises this exception.

Parameters

[in] idx The index of the value to retrieve as a double.

Returns: The value at idx converted to a double or -1.0 on error.

Definition at line 1845 of file option_info.cpp.

References advgetopt::validator_double::convert_string(), f_double, f_name, f_value, advgetopt::get_global_mutex(), get_value(), lock(), and advgetopt::option_flags_merge().

◆ get_environment_variable_name()

std::string advgetopt::option_info::get_environment_variable_name ( ) const

Each command line option can be assigned an environment variable name. When checking for the global environment variable name, the advgetopt library also checks each option's environment variable name which has priority over the global variable (i.e. it will overwrite a value found in the global environment variable).

The value returned is an empty string by default, which means the option does not have a value defined in an environment variable.

Returns: The environment variable name of this option.

See also: set_environment_variable_name(); get_environment_variable_value()

Definition at line 492 of file option_info.cpp.

References f_environment_variable_name.

◆ get_environment_variable_value()

bool advgetopt::option_info::get_environment_variable_value	(	std::string &	value,
		char const *	intro = `nullptr`
	)		const

Each command line option can be assigned an environment variable name. Using this name, this function attempts to retrieve the corresponding value defined in that variable.

Parameters

[out]	value	Save the resulting value in this variable.
[in]	intro	The introducer to prepend. May be nullptr.

Returns: true if a value was defined.

See also: set_environment_variable_name(); get_environment_variable_name()

Definition at line 512 of file option_info.cpp.

References f_environment_variable_name, and advgetopt::option_flags_merge().

◆ get_flags()

flag_t advgetopt::option_info::get_flags ( ) const

This function retrieves all the flags defined in this option.

To just check whether a flag is set or not, use the has_flag() function instead.

Returns: This option flags.

Definition at line 608 of file option_info.cpp.

References f_flags.

◆ get_help()

std::string const & advgetopt::option_info::get_help ( ) const

This function returns the help string for this command line option.

Warning: Note that when a special flag is set, this string may represent something else that a help string.

Returns: The help string of this argument.

Definition at line 795 of file option_info.cpp.

References f_help.

◆ get_long()

long advgetopt::option_info::get_long ( int idx = 0 ) const

This function returns the value converted to a long.

If the value does not represent a valid long value, an error is emitted through the logger.

The value will be parsed through the variables if defined and this parameter allows it. This means the value may be a variable reference instead of an actually value (i.e. ${one})

Note: The function will transform all the values in case this is a GETOPT_FLAG_MULTIPLE option and cache the results. Calling the function many times with the same index is very fast after the first time.

Exceptions

getopt_exception_undefined If the value was not defined, the function raises this exception.

Parameters

[in] idx The index of the value to retrieve as a long.

Returns: The value at idx converted to a long or -1 on error.

Definition at line 1770 of file option_info.cpp.

References advgetopt::validator_integer::convert_string(), f_integer, f_name, f_value, advgetopt::get_global_mutex(), get_value(), lock(), and advgetopt::option_flags_merge().

◆ get_multiple_separators()

string_list_t const & advgetopt::option_info::get_multiple_separators ( ) const

This function returns a reference to the list of separators of this option. It is expected to be used when a value is found in a configuration file or a command line in an environment variable. Parameters on the command line are already broken down by the shell and we do not do any further manipulation with those.

Warning: As mentioned in the set_multiple_separators() function, the separators are only used when parsing a long parameter using the equal sign notation (i.e. --tags=a,b,c,d). It also works in environment variables. I am thinking that the --tags a,b,c,d should probably work the same way though because otherwise many people will have a surprise.

Returns: A reference to the list of separators used to cut multiple arguments found in a configuration file or an environment variable.

Definition at line 1095 of file option_info.cpp.

References f_multiple_separators.

◆ get_name()

std::string const & advgetopt::option_info::get_name ( ) const

This option retrieves the long name of the option.

Note: Remember that the underscores in long names are converted to dashes. This is because it makes more sense to look for command line parameters with dashes. This function will return the name with only dashes.; The name is always defined. The creation of an option_info object fails if the name is empty.

Returns: The long name with dashes instead of underscores.

Definition at line 287 of file option_info.cpp.

References f_name.

◆ get_section_name()

std::string advgetopt::option_info::get_section_name ( ) const

The name of an option can include section names. These are rarely used on the command line, but they are useful for configuration files if you want to create multiple layers of options (a.k.a. sections.)

This function returns all the section names found in this option name. The last scope operator gets removed too.

If the name does not include any sections, then this function returns an empty string.

Returns: The section names without the basename.

Definition at line 371 of file option_info.cpp.

References f_name, and advgetopt::option_flags_merge().

◆ get_section_name_list()

string_list_t advgetopt::option_info::get_section_name_list ( ) const

The name of an option can include section names. These are rarely used on the command line, but they are useful for configuration files if you want to create multiple layers of options (a.k.a. sections.)

This function returns a string_list_t of the section names found in this option name.

If the name does not include any sections, then this function returns an empty list.

Returns: The list of section name.

Definition at line 398 of file option_info.cpp.

References f_name, and advgetopt::option_flags_merge().

◆ get_short_name()

short_name_t advgetopt::option_info::get_short_name ( ) const

This function returns the short_name of this option.

The short name is a Unicode character (UTF-32).

Returns: The short name character.

Definition at line 326 of file option_info.cpp.

References f_short_name.

◆ get_validator()

validator::pointer_t advgetopt::option_info::get_validator ( ) const

The validator of an option may be used for additional tasks such as converting the value to a specific type (i.e. a string to an integer, for example.)

This function allows you to retrieve the validator to be able to make use of those functions. You will have to use std::dynamic_cast_pointer<>() to change the type of validator to the specialized validator of this option. If that returns a null pointer, then the option is not using that type of validator.

Todo:: Add a template function that does the cast for the caller.

Returns: A pointer to this option validator.

Definition at line 987 of file option_info.cpp.

References f_validator.

◆ get_value()

std::string advgetopt::option_info::get_value	(	int	idx = `0`,
		bool	raw = `false`
	)		const

This function returns the value for this option. By default, set the idx parameter to zero.

The number of values is defined by the size() function.

The is_defined() function returns true if at least one value is defined. It is a good idea to check first otherwise you will get an exception.

If the parameter is marked as one that can be processed through the variables::process_value() function and the variables were defined with set_variables(), then the value will be processed for variables unless you set the raw parameter to true.

Exceptions

getopt_exception_undefined If the idx parameter is too large or no value was found for this option, then this function raises an invalid error.

Parameters

[in]	idx	The index of the parameter to retrieve.
[in]	raw	Whether to allow the variable processing or not.

Returns: The value at idx.

Definition at line 1661 of file option_info.cpp.

References f_name, f_value, f_variables, advgetopt::GETOPT_FLAG_PROCESS_VARIABLES, has_flag(), and advgetopt::option_flags_merge().

Referenced by get_double(), and get_long().

◆ get_variables()

variables::pointer_t advgetopt::option_info::get_variables ( ) const

This option info object may replace variables in values (see get_value() for details) using this list of variables. Option info objects created by the getopt class always have this pointer set, although the list of variables may be empty.

Returns: A pointer to the list of variables found in the option info object.

Definition at line 1125 of file option_info.cpp.

References f_variables.

◆ has_default()

bool advgetopt::option_info::has_default ( ) const

Whenever an option is given a default value, the GETOPT_FLAG_HAS_DEFAULT flag gets set. This allows us to distinguish between an option with a default which is the empty string and an option without a default.

The set_default() forces the flag to be set.

The remove_default() clears the flag.

Returns: true if the flag is set, false otherwise.

See also: set_default(); remove_default(); get_default()

Definition at line 646 of file option_info.cpp.

References advgetopt::GETOPT_FLAG_HAS_DEFAULT, and has_flag().

◆ has_flag()

bool advgetopt::option_info::has_flag ( flag_t flag ) const

This function is used to check whether a flag is set or not.

Note: The flag parameter can be set to more than one flag in which case the function returns true if any one of those flags is set.

Returns: true if the flag is set, false otherwise.

Definition at line 624 of file option_info.cpp.

References f_flags, and advgetopt::option_flags_merge().

Referenced by add_value(), get_value(), has_default(), is_default_option(), set_multiple_values(), set_value(), and trace_source().

◆ has_value()

bool advgetopt::option_info::has_value ( std::string const & value ) const

This function searches the set of existing values in this option_info and if found returns true.

Note: It is possible to add the same value multiple times. However, there are cases where you may not want to have the same value more than once. This function can be used to try to not do that.

Parameters

[in] value The value to search in this option.

Returns: true if the value is already defined in this option_info.

See also: set_value()

Definition at line 1147 of file option_info.cpp.

References f_value, and advgetopt::option_flags_merge().

◆ is_default_option()

bool advgetopt::option_info::is_default_option ( ) const

This function checks whether this option represents the default option. The default option is where non-options, generally filenames, are added when not following an argument.

The name of the default option is always "--". However, it is not required. When no default option is defined, filenames can't be specified and when such are found on the command line, an error ensues.

Returns: true if the name of the option is "--".

Definition at line 430 of file option_info.cpp.

References f_name, advgetopt::GETOPT_FLAG_DEFAULT_OPTION, and has_flag().

◆ is_defined()

bool advgetopt::option_info::is_defined ( ) const

When parsing the options on the command line or a configuration file, values get added to the various existing option_info. If a special "*" option is also defined, then any value found on the command line or the configuration file are returned.

To know whether this or that option was defined with a value, use this function. Even an option which doesn't come with a parameter will get an is_defined() returning true once it was found on the command line. The value will be the empty string.

Returns: true if that option was found on the command line, in the environment variable, or in the configuration file.

Definition at line 1531 of file option_info.cpp.

References f_value.

Referenced by lock(), and reset().

◆ lock()

void advgetopt::option_info::lock ( bool always = true )

This function allows for locking a value so further reading of data from different sources will not overwrite it.

When parsing the data we have multiple levels. Here are these levels in priority order (first option found is the one we keep):

Command line options
Environment Variables
Configuration File: Local (./\<name>.conf)
Configuration File: User's (~/.config/\<proc>/\<name>.conf)
Configuration File: Project sub-folder (/etc/\<proc>/\<proc>.d/\<ohter-name>.conf)
Configuration File: Project folder (/etc/\<proc>/\<other-name>.conf)
Configuration File: System sub-folder (/etc/\<proc>/\<name>.conf)
Configuration File: System folder (/etc/\<proc>/\<name>.conf)

Note: Most of our packages do not have a Project and a System set of configuration files. Often they will have just the System files.

We use this lock because we want to support multiple values so just detecting that a value is set to not add more options is not a good test. Instead we lock the values that are set before moving to the next level.

Parameters

[in] always Always lock that option, whether it is defined or not.

Definition at line 1924 of file option_info.cpp.

References add_flag(), advgetopt::GETOPT_FLAG_LOCK, is_defined(), and advgetopt::option_flags_merge().

Referenced by add_callback(), get_double(), get_long(), remove_callback(), and value_changed().

◆ remove_callback()

void advgetopt::option_info::remove_callback ( callback_id_t id )

This function is the opposite of the add_callback(). It removes a callback that you previously added. This is useful if you are interested in hearing about the value when set but are not interested at all about future changes.

Parameters

[in] id The id returned by the add_callback() function.

Definition at line 2004 of file option_info.cpp.

References f_callbacks, advgetopt::get_global_mutex(), lock(), and advgetopt::option_flags_merge().

◆ remove_default()

void advgetopt::option_info::remove_default ( )

Call this function remove the default value. The default string gets cleared and the GETOPT_FLAG_NO_DEFAULT flag gets set.

See also: set_default(); has_default(); get_default()

Definition at line 709 of file option_info.cpp.

References f_default_value, advgetopt::GETOPT_FLAG_HAS_DEFAULT, and remove_flag().

◆ remove_flag()

void advgetopt::option_info::remove_flag ( flag_t flag )

This function removes the given flag from the set of flags currently set.

Note: Multiple flags can be defined in flag.

Parameters

[in] flag The flag(s) to clear.

Definition at line 593 of file option_info.cpp.

References f_flags, advgetopt::option_flags_merge(), and set_flags().

Referenced by remove_default(), and unlock().

◆ reset()

void advgetopt::option_info::reset ( )

This function clears the value so it is marked as undefined again.

To reuse the same getopt object multiple times, you can use the reset() function which clears the values. Then you can parse a new set of argc/argv parameters.

Definition at line 1960 of file option_info.cpp.

References f_double, f_integer, f_source, f_value, is_defined(), advgetopt::SOURCE_UNDEFINED, and value_changed().

◆ set_alias_destination()

void advgetopt::option_info::set_alias_destination ( option_info::pointer_t destination )

After loading all the options, we run the link_aliases() function which makes sure that all the options that are marked as an alias are properly linked.

Parameters

[in] alias The final destination of this option.

Definition at line 1001 of file option_info.cpp.

References f_alias_destination, advgetopt::GETOPT_FLAG_ALIAS, and advgetopt::option_flags_merge().

◆ set_configuration_filename()

void advgetopt::option_info::set_configuration_filename ( std::string const & filename )

static

While parsing a configuration file, this function gets called to set the name which is used to generate the trace of the source of all the configuration data.

Definition at line 1610 of file option_info.cpp.

References advgetopt::option_flags_merge().

Referenced by advgetopt::getopt::process_configuration_file().

◆ set_default() [1/2]

void advgetopt::option_info::set_default ( char const * default_value )

This function is an overload which allows us to call set_default() with a nullptr.

Parameters

[in] default_value The new default value for this option.

See also: remove_default(); has_default(); get_default()

Definition at line 691 of file option_info.cpp.

References advgetopt::option_flags_merge(), and set_default().

◆ set_default() [2/2]

void advgetopt::option_info::set_default ( std::string const & default_value )

This function sets the default value for this option.

The default value is always defined as a string, but it can later be converted to a different type using the option validator.

Often, though, the default value is not compatible with the validator. For example, you may have a parameter which is set to a percentage from -100% to +100% and the default may be the string "off".

Note: After calling this function, the option is viewed as having a default even if that's the empty string.

Parameters

[in] default_value The new default value for this option.

See also: remove_default(); has_default(); get_default()

Definition at line 673 of file option_info.cpp.

References add_flag(), f_default_value, advgetopt::GETOPT_FLAG_HAS_DEFAULT, and advgetopt::option_flags_merge().

Referenced by set_default().

◆ set_environment_variable_name() [1/2]

void advgetopt::option_info::set_environment_variable_name ( char const * name )

This function is an overload which allows us to call set_default() with a nullptr.

Parameters

[in] default_value The new default value for this option.

See also: get_environment_variable_name(); get_environment_variable_value()

Definition at line 467 of file option_info.cpp.

References set_environment_variable_name().

◆ set_environment_variable_name() [2/2]

void advgetopt::option_info::set_environment_variable_name ( std::string const & name )

Each option can be given a specific environment variable name. That parameter is used to retrieve the option value if not defined on the command line.

By default this is an empty string.

Parameters

[in] name The name of the environment variable attached to this option.

See also: get_environment_variable_name(); get_environment_variable_value()

Definition at line 451 of file option_info.cpp.

References f_environment_variable_name.

Referenced by set_environment_variable_name().

◆ set_flags()

void advgetopt::option_info::set_flags ( flag_t flags )

The options have flags determining various sub-options available to them. Right now we have flags to tell how each option can be used (on the command line, in an environment variable, or in a configuration file.)

Note: We have the GETOPT_FLAG_ALIAS flag which is used to define an alias. That means values do not get set in an option which is marked as an alias. Instead, they get set in the option which is being aliased. This means your software does not have to check both options. The setup function will actually call the set_alias() function at some point to finalize aliases so you do not really need the flag, except to know that no value will be defined here because it will instead be saved in the aliased option.

Parameters

[in] flags The new flags.

Definition at line 563 of file option_info.cpp.

References f_flags, and advgetopt::option_flags_merge().

Referenced by add_flag(), and remove_flag().

◆ set_help() [1/2]

void advgetopt::option_info::set_help ( char const * help )

This function is an overload which allows us to call set_help() with a nullptr and not crash. We just ignore the call when that happens.

Parameters

[in] help The help string for this option or nullptr.

Definition at line 776 of file option_info.cpp.

References advgetopt::option_flags_merge(), and set_help().

◆ set_help() [2/2]

void advgetopt::option_info::set_help ( std::string const & help )

The usage() function prints this string whenever the command line includes the help command line option (such as -h or --help.)

The string can include various flags such as p to include dynamically defined parameters. See the process_help_string() function for additional details about these parameters.

Note: When using a special flag (i.e. GETOPT_FLAG_HELP), the help value string is used as the value used by that special feature:

GETOPT_FLAG_HELP

It represents a string to print out by the usage() function. The option purpose is solaly for adding a string of help in the output.

GETOPT_FLAG_EXTERNAL_OPTIONS

It represents the filename to read additional advgetopt options. In some cases, your static array of option structures is to define this special flag.

GETOPT_FLAG_LICENSE

It represents the program license.

GETOPT_FLAG_COPYRIGHT

It represents the program copyright notice.

Parameters

[in] help The help string for this option.

Definition at line 763 of file option_info.cpp.

References f_help, and advgetopt::option_flags_merge().

Referenced by set_help().

◆ set_multiple_separators() [1/2]

void advgetopt::option_info::set_multiple_separators ( char const *const * separators )

Options marked with the GETOPT_FLAG_MULTIPLE flag get their value cut by separators when such is found in an environment variable or a configuration file.

This function saves the list of separators in a vector.

Todo:: At the moment, this is only applied when the parameter is specified with the long option and an equal sign, as in: --tags=a,b,c,d. I thinks that it should also work without the equal sign.

Parameters

[in] separators The list of separators to be used for this argument.

Definition at line 1041 of file option_info.cpp.

References f_multiple_separators, and advgetopt::option_flags_merge().

◆ set_multiple_separators() [2/2]

void advgetopt::option_info::set_multiple_separators ( string_list_t const & separators )

Options marked with the GETOPT_FLAG_MULTIPLE flag get their value cut by separators when such is found in an environment variable or a configuration file.

This function saves the specified list of separators.

Todo:: See the other set_multiple_separators() function about the issue of the separators not being used in all cases.

Parameters

[in] separators The list of separators to be used for this argument.

Definition at line 1070 of file option_info.cpp.

References f_multiple_separators, and advgetopt::option_flags_merge().

◆ set_multiple_values()

bool advgetopt::option_info::set_multiple_values	(	std::string const &	value,
		string_list_t const &	option_keys = `string_list_t()`,
		option_source_t	source = `option_source_t::SOURCE_DIRECT`
	)

This function views the value parameter as a multi-value parameter which it breaks down in multiple parameters and add the results to this option_info object as the current value(s).

To separate the values, the function makes use of the separators as set by one the set_multiple_separators() functions.

The resulting values must not be the empty string. Empty strings are ignored. So if the separator is a comma and you write:

foo,,,bar

advgetopt::option_flags_merge

constexpr flag_t option_flags_merge()

Definition flags.h:87

The result includes "foo" and "bar" and no empty strings.

The value can be quoted in which case it can include any of the separators.

"foo, bar",'bar, foo'

The result includes "foo, bar" and "bar, foo" (without the quotes which get removed in the process).

Note: The function has the side effect of clearing any existing parameters first. So only the newly defined parameters in value will be set in the option once the function returns.

Parameters

[in]	value	The multi-value to save in this option.
[in]	option_keys	The keys to which the values are applied.
[in]	source	Where the value comes from.

Returns: true if all the values in value were considered valid.

See also: add_value(); set_value()

Definition at line 1404 of file option_info.cpp.

References f_double, f_integer, f_multiple_separators, f_name, f_source, f_value, advgetopt::GETOPT_FLAG_ARRAY, advgetopt::GETOPT_FLAG_MULTIPLE, has_flag(), advgetopt::option_flags_merge(), source(), advgetopt::SOURCE_UNDEFINED, advgetopt::split_string(), advgetopt::unquote(), validate_all_values(), and value_changed().

◆ set_short_name()

void advgetopt::option_info::set_short_name ( short_name_t short_name )

This function is used to assign a short name to an option.

It can be changed to anything, including the NO_SHORT_NAME special value.

Warning: If you want this function to work as expected (i.e. for the option to later be found using its short name), make sure to call the getopt::set_short_name() on your getopt object and not directly this function. This is because the getopt object needs to add the newly named option to its map of options sorted by short name.

Parameters

[in] short_name The short name to assign to this option.

See also: get_short_name(); getopt::set_short_name()

Definition at line 312 of file option_info.cpp.

References f_short_name, and advgetopt::option_flags_merge().

◆ set_trace_sources()

void advgetopt::option_info::set_trace_sources ( bool trace )

static

This is a global flag that you can set before calling any getopt functions so that way you can make sure that you get a full trace of all the sources for all your options. Then you can use the –show-sources command line options to see the resulting data.

Note: This option is costly since it saves a lot of data, which is why we have it as an option. If the getopt() function detects in the argv passed to it a "--show-sources" option, then it will automatically call this function with true, even before it starts parsing anything. The flag is false by default.

Parameters

[in] trace Whether the sources should be traced.

Definition at line 1582 of file option_info.cpp.

References advgetopt::option_flags_merge().

Referenced by advgetopt::anonymous_namespace{advgetopt.cpp}::check_for_show_sources().

◆ set_validator() [1/3]

bool advgetopt::option_info::set_validator ( std::nullptr_t null_ptr )

This function removes the existing validator by resetting the pointer back to nullptr.

Parameters

[in] null_ptr Ignored.

Returns: Always true since no validator means any existing values would be considered valid.

Definition at line 893 of file option_info.cpp.

References f_validator, and advgetopt::option_flags_merge().

◆ set_validator() [2/3]

bool advgetopt::option_info::set_validator ( std::string const & name_and_params )

This function parses the specified name and optional parameters and create a corresponding validator for this option.

The name_and_params string can be defined as one of:

<validator-name>
<validator-name>()
<validator-name>(<param1>)
<validator-name>(<param1>, <param2>, ...)

The list of parameters is optional. There may be no, just one, or any number of parameters. How the parameters are parsed is left to the validator to decide.

If the input string is empty, the current validator, if one is installed, gets removed.

Note: If the option_info already has a set of values, they get validated against the new validator. Any value which does not validate gets removed at once. The validation process also generates an error when an invalid error is found. Note that it is expected that you will setup a validator before you start parsing data so this feature should seldom be used.

Parameters

[in] name_and_params The validator name and parameters.

Returns: true if the validator was installed and all existing values were considered valid.

Definition at line 835 of file option_info.cpp.

References advgetopt::validator::create(), advgetopt::option_flags_merge(), and set_validator().

Referenced by set_validator().

◆ set_validator() [3/3]

bool advgetopt::option_info::set_validator ( validator::pointer_t validator )

Options may be assigned a validator. Without a validator, any value is considered valid.

A value is checked when you call the validates() function. The function returns true if the value is considered valid. False in all other cases.

You can define your own validators and add them to the library list of available validators before using the library in order to get your options to use said validators.

Note: If the option_info already has a set of values, they get validated against the new validator. Any value which does not validate gets removed at once. The validation process also generates an error when an invalid error is found. Note that it is expected that you will setup a validator before you start parsing data so this feature should seldom be used.

Parameters

[in] validator A pointer to a validator.

Returns: true if the validator was installed and all existing values were considered valid.

Definition at line 866 of file option_info.cpp.

References f_validator, f_value, advgetopt::option_flags_merge(), size(), validate_all_values(), and value_changed().

◆ set_value()

bool advgetopt::option_info::set_value	(	int	idx,
		std::string const &	value,
		string_list_t const &	option_keys = `string_list_t()`,
		option_source_t	source = `option_source_t::SOURCE_DIRECT`
	)

This function is generally used to replace an existing value. If the index is set to the size of the existing set of values, then a new value is saved in the vector.

This is particularly useful if you want to edit a configuration file.

If the option comes with a validator, then the value gets checked against that validator. If that results in an error, the value is not added to the vector so an invalid value will never be returned by the option_info class.

The value does not get added when it currently is locked or when it does not validate as per the validator of this option_info.

Exceptions

getopt_exception_undefined If the index is out of range (too large or negative), then this exception is raised.

Parameters

[in]	idx	The position of the value to update.
[in]	value	The new value.
[in]	option_keys	An array of keys to prepend to each value.
[in]	source	Where the value comes from.

Returns: true if the set_value() added the value.

See also: add_value(); validates(); lock(); unlock()

Definition at line 1223 of file option_info.cpp.

References f_double, f_integer, f_name, f_source, f_value, find_value_index_by_key(), advgetopt::GETOPT_FLAG_DYNAMIC_CONFIGURATION, advgetopt::GETOPT_FLAG_LOCK, advgetopt::GETOPT_FLAG_MULTIPLE, has_flag(), advgetopt::option_flags_merge(), source(), advgetopt::SOURCE_DIRECT, advgetopt::SOURCE_UNDEFINED, validates(), and value_changed().

Referenced by add_value().

◆ set_variables()

void advgetopt::option_info::set_variables ( variables::pointer_t vars )

The getopt object holds a set of variables which is can pass down to the option info. If defined, then the get_value() function returns a processed value (a.k.a. the ${...} references in that value are replaced by their corresponding value).

Parameters

[in] vars A pointer to a list of variables.

Definition at line 1110 of file option_info.cpp.

References f_variables, and advgetopt::option_flags_merge().

◆ size()

size_t advgetopt::option_info::size ( ) const

This function returns the number of values that were found for this option.

If the option is marked as GETOPT_FLAG_MULTIPLE, then this function may return 0 or more. Without that flag, this function only returns 0 or 1.

You must use the size() parameter to know how many items are defined and call the get_value() with a correct idx parameter (i.e. a value between 0 and size() - 1.)

Returns: The number of values defined in this option.

Definition at line 1631 of file option_info.cpp.

References f_value.

Referenced by set_validator().

◆ source()

option_source_t advgetopt::option_info::source ( ) const

This function returns the source of this option, i.e. whether it came from the command line, the environment variable, a configuration file, or some other source that you can define.

The source is similar to a priority in the sense that a source with a higher number cannot overwrite the value of a smaller source. The source is set at the same time as you set the option. The mechanism may not be working exactly as expected when trying to add options from different sources.

Note: In the old version, the value would be the value set with the last set_value() command. That worked because we did not try to support fully dynamic options. Now we want to have the ability to set an option on the command line and that has to prevent the set from a dynamic source. Since the dynamic source would do the set_value() at a later time, just the order is not enough to know whether the dynamic source has permission to overwrite that value.

Returns: The source of the option info.

Definition at line 1560 of file option_info.cpp.

References f_source.

Referenced by add_value(), set_multiple_values(), and set_value().

◆ trace_source()

void advgetopt::option_info::trace_source ( int idx )

private

The getopt class supports a flag which turns on the trace mode. This allows it to memorize where the values came fram. This includes the source and if the source is a configuration file, the path to that configuration file.

Definition at line 2064 of file option_info.cpp.

References f_name, f_source, f_trace_sources, f_value, advgetopt::GETOPT_FLAG_MULTIPLE, has_flag(), advgetopt::option_flags_merge(), advgetopt::SOURCE_COMMAND_LINE, advgetopt::SOURCE_CONFIGURATION, advgetopt::SOURCE_DIRECT, advgetopt::SOURCE_DYNAMIC, advgetopt::SOURCE_ENVIRONMENT_VARIABLE, and advgetopt::SOURCE_UNDEFINED.

Referenced by value_changed().

◆ trace_sources()

string_list_t const & advgetopt::option_info::trace_sources ( ) const

An option can be marked for tracing. This allows you to see exactly which value came from which source. We currently support multiple sources such as the command line, environment variable, direct, dynamic, configuration files.

Returns: An array of strings representing the source of each value in the order they were set in this option_info.

Definition at line 1598 of file option_info.cpp.

References f_trace_sources.

◆ unlock()

void advgetopt::option_info::unlock ( )

This function does the opposite of the lock() function. It allows for the value to be updated again.

Once the getpot object is done parsing all the input, it unlocks all the values using this function. The unlock is always unconditional.

Definition at line 1946 of file option_info.cpp.

References advgetopt::GETOPT_FLAG_LOCK, and remove_flag().

◆ validate_all_values()

bool advgetopt::option_info::validate_all_values ( )

private

Whenever you change the validator of an option_info, or change all the values with set_multiple_value(), all the values get verified using this function. The function removes any value which does not validate according to the current validator.

Note: Keep in mind that an empty value is always considered valid, no matter what the validator is. This is because when you use an option without a value (i.e. --order instead of --order asc) the value is set to the empty string unless there is a default. This allows you to know that the option was used without a value, which is useful for some options.

Returns: true if all the values were considered valid.

Definition at line 1492 of file option_info.cpp.

References f_validator, f_value, advgetopt::option_flags_merge(), and validates().

Referenced by set_multiple_values(), and set_validator().

◆ validates()

bool advgetopt::option_info::validates ( int idx = 0 )

private

This function us used internally to verify values that get added at the time they get added. It runs the validator::validate() function and returns true if the value is considered valid. When the value does not validate, it returns false and removes the value from the f_value vector. This means no invalid values are ever kept in an option_info object.

An option without a validator has values that are always valid. Also, an empty value is always considered valid.

Note: This function is private since there is no need for the user of the option_info to ever call it (i.e. it automatically gets called any time a value gets added to the f_value vector.)

Parameters

[in] idx The value to check.

Returns: true if the value is considered valid, false otherwise.

Definition at line 924 of file option_info.cpp.

References f_name, f_source, f_validator, f_value, advgetopt::option_flags_merge(), and advgetopt::SOURCE_UNDEFINED.

Referenced by set_value(), and validate_all_values().

◆ value_changed()

void advgetopt::option_info::value_changed ( int idx )

private

This function is called on a change of the internal values.

The function is used to call the callbacks that were added to this option_info object. The function first copies the existing list of callbacks so you can safely update the list from within a callback.

Warning: Destroying your advgetopt::getopt option is not safe while a callback is running.

Parameters

[in] idx This represents the index of the value that last changed (currently poor attempt to fix this issue).

Definition at line 2037 of file option_info.cpp.

References f_callbacks, advgetopt::get_global_mutex(), lock(), advgetopt::option_flags_merge(), and trace_source().

Referenced by reset(), set_multiple_values(), set_validator(), and set_value().

Member Data Documentation

◆ f_alias_destination

pointer_t advgetopt::option_info::f_alias_destination = pointer_t()

private

Definition at line 184 of file option_info.h.

Referenced by get_alias_destination(), and set_alias_destination().

◆ f_callbacks

callback_vector_t advgetopt::option_info::f_callbacks = callback_vector_t()

private

Definition at line 186 of file option_info.h.

Referenced by add_callback(), remove_callback(), and value_changed().

◆ f_default_value

std::string advgetopt::option_info::f_default_value = std::string()

private

Definition at line 181 of file option_info.h.

Referenced by get_default(), remove_default(), and set_default().

◆ f_double

std::vector<double> advgetopt::option_info::f_double = std::vector<double>()

mutableprivate

Definition at line 196 of file option_info.h.

Referenced by get_double(), reset(), set_multiple_values(), and set_value().

◆ f_environment_variable_name

std::string advgetopt::option_info::f_environment_variable_name = std::string()

private

Definition at line 179 of file option_info.h.

Referenced by get_environment_variable_name(), get_environment_variable_value(), and set_environment_variable_name().

◆ f_flags

flag_t advgetopt::option_info::f_flags = GETOPT_FLAG_NONE

private

Definition at line 180 of file option_info.h.

Referenced by add_flag(), get_flags(), has_flag(), remove_flag(), and set_flags().

◆ f_help

std::string advgetopt::option_info::f_help = std::string()

private

Definition at line 182 of file option_info.h.

Referenced by get_help(), and set_help().

◆ f_integer

std::vector<long> advgetopt::option_info::f_integer = std::vector<long>()

mutableprivate

Definition at line 195 of file option_info.h.

Referenced by get_long(), reset(), set_multiple_values(), and set_value().

◆ f_multiple_separators

string_list_t advgetopt::option_info::f_multiple_separators = string_list_t()

private

Definition at line 185 of file option_info.h.

Referenced by get_multiple_separators(), set_multiple_separators(), set_multiple_separators(), and set_multiple_values().

◆ f_name

std::string advgetopt::option_info::f_name = std::string()

private

Definition at line 177 of file option_info.h.

Referenced by option_info(), find_value_index_by_key(), get_basename(), get_double(), get_long(), get_name(), get_section_name(), get_section_name_list(), get_value(), is_default_option(), set_multiple_values(), set_value(), trace_source(), and validates().

◆ f_next_callback_id

id_t advgetopt::option_info::f_next_callback_id = 0

private

Definition at line 187 of file option_info.h.

Referenced by add_callback().

◆ f_short_name

short_name_t advgetopt::option_info::f_short_name = NO_SHORT_NAME

private

Definition at line 178 of file option_info.h.

Referenced by get_short_name(), and set_short_name().

◆ f_source

option_source_t advgetopt::option_info::f_source = option_source_t::SOURCE_UNDEFINED

private

Definition at line 193 of file option_info.h.

Referenced by reset(), set_multiple_values(), set_value(), source(), trace_source(), and validates().

◆ f_trace_sources

string_list_t advgetopt::option_info::f_trace_sources = string_list_t()

private

Definition at line 188 of file option_info.h.

Referenced by trace_source(), and trace_sources().

◆ f_validator

validator::pointer_t advgetopt::option_info::f_validator = validator::pointer_t()

private

Definition at line 183 of file option_info.h.

Referenced by get_validator(), set_validator(), set_validator(), validate_all_values(), and validates().

◆ f_value

string_list_t advgetopt::option_info::f_value = string_list_t()

private

Definition at line 194 of file option_info.h.

Referenced by add_value(), find_value_index_by_key(), get_double(), get_long(), get_value(), has_value(), is_defined(), reset(), set_multiple_values(), set_validator(), set_value(), size(), trace_source(), validate_all_values(), and validates().

◆ f_variables

variables::pointer_t advgetopt::option_info::f_variables = variables::pointer_t()

private

Definition at line 189 of file option_info.h.

Referenced by get_value(), get_variables(), and set_variables().

The documentation for this class was generated from the following files:

/home/alexis/snapwebsites/snapcpp/contrib/advgetopt/advgetopt/option_info.h
/home/alexis/snapwebsites/snapcpp/contrib/advgetopt/advgetopt/option_info.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ callback_id_t

◆ callback_t

◆ callback_vector_t

◆ map_by_name_t

◆ map_by_short_name_t

◆ pointer_t

◆ vector_t

Constructor & Destructor Documentation

◆ option_info()

Member Function Documentation

◆ add_callback()

◆ add_flag()

◆ add_value()

◆ find_value_index_by_key()

◆ get_alias_destination()

◆ get_basename()

◆ get_default()

◆ get_double()

◆ get_environment_variable_name()

◆ get_environment_variable_value()

◆ get_flags()

◆ get_help()

◆ get_long()

◆ get_multiple_separators()

◆ get_name()

◆ get_section_name()

◆ get_section_name_list()

◆ get_short_name()

◆ get_validator()

◆ get_value()

◆ get_variables()

◆ has_default()

◆ has_flag()

◆ has_value()

◆ is_default_option()

◆ is_defined()

◆ lock()

◆ remove_callback()

◆ remove_default()

◆ remove_flag()

◆ reset()

◆ set_alias_destination()

◆ set_configuration_filename()

◆ set_default() [1/2]

◆ set_default() [2/2]

◆ set_environment_variable_name() [1/2]

◆ set_environment_variable_name() [2/2]

◆ set_flags()

◆ set_help() [1/2]

◆ set_help() [2/2]

◆ set_multiple_separators() [1/2]

◆ set_multiple_separators() [2/2]

◆ set_multiple_values()

◆ set_short_name()

◆ set_trace_sources()

◆ set_validator() [1/3]

◆ set_validator() [2/3]

◆ set_validator() [3/3]

◆ set_value()

◆ set_variables()

◆ size()

◆ source()

◆ trace_source()

◆ trace_sources()

◆ unlock()

◆ validate_all_values()

◆ validates()

◆ value_changed()

Member Data Documentation

◆ f_alias_destination

◆ f_callbacks