advgetopt::variables Class Reference

#include <variables.h>

Public Types
typedef std::shared_ptr< variables >	pointer_t
typedef std::map< std::string, std::string >	variable_t

Public Member Functions
std::string	get_variable (std::string const &name) const
	Return the value of the named variable.
variable_t const &	get_variables () const
	Return a reference to the map of variables.
bool	has_variable (std::string const &name) const
	Check whether a variable is defined.
std::string	process_value (std::string const &value) const
	Process variables against a parameter.
void	set_variable (std::string const &name, std::string const &value, assignment_t assignment=assignment_t::ASSIGNMENT_SET)
	Set a variable.

Static Public Member Functions
static std::string	canonicalize_variable_name (std::string const &name)
	Canonicalize the variable name.

Private Types
typedef string_set_t	variable_names_t

Private Member Functions
std::string	recursive_process_value (std::string const &value, variable_names_t &names) const
	Internal function processing variables recursively.

Private Attributes
variable_t	f_variables = variable_t()

Detailed Description

Definition at line 58 of file variables.h.

Member Typedef Documentation

pointer_t

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

Definition at line 61 of file variables.h.

variable_names_t

typedef string_set_t advgetopt::variables::variable_names_t

private

Definition at line 77 of file variables.h.

variable_t

typedef std::map<std::string, std::string> advgetopt::variables::variable_t

Definition at line 62 of file variables.h.

Member Function Documentation

canonicalize_variable_name()

std::string advgetopt::variables::canonicalize_variable_name ( std::string const &  name )

static

This function canonicalizes the name of a variable.

This means:

• Replace a sequence of ':' with '::'.
• Replace a sequence of '.' with '::'.
• Replace a '_' with '-'.

Note

Variable names that come from a configuration file will already have been canonicalized, but the user can directly call the get_variable() and set_variable() functions which will also benefit from this conversion.

Exceptions

getopt_invalid

If the variable or one of the section names start with a digit, this exception is raised. The exception is also raised if we detect an empty section name (as in "::test" or "double::::scope" or "not..allowed").

Parameters

[in]

name

The name of the variable.

Definition at line 79 of file variables.cpp.

References advgetopt::option_flags_merge().

Referenced by get_variable(), has_variable(), and set_variable().

get_variable()

std::string advgetopt::variables::get_variable

(

std::string const &

name

)

const

This function searches for the named variable and returns its value if defined.

Parameters

[in]

name

The name of the variable to retrieve.

Returns

The variable value of an empty string.

Definition at line 154 of file variables.cpp.

References canonicalize_variable_name(), f_variables, and advgetopt::option_flags_merge().

Referenced by recursive_process_value().

get_variables()

variables::variable_t const & advgetopt::variables::get_variables

(

)

const

This function returns a reference to the whole map of variables.

The map is composed of named values. The first string is the name of variables and the second string is the value.

Note

It is not multi-thread safe since the variable make can be updated at any time.

Returns

The reference to the map of variables.

Definition at line 179 of file variables.cpp.

References f_variables.

has_variable()

bool advgetopt::variables::has_variable

(

std::string const &

name

)

const

If you want to verify that a variable is defined before retrieving it, you can use this function. A variable can be set to the empty string so checking the returned value of the get_variable() is not sufficient to know whether the variable is defined or log.

Parameters

[in]

name

The name of the variable to check.

Returns

true if the variable is defined.

Definition at line 138 of file variables.cpp.

References canonicalize_variable_name(), f_variables, and advgetopt::option_flags_merge().

process_value()

std::string advgetopt::variables::process_value

(

std::string const &

value

)

const

Whenever a parameter is retrieved, its value is passed through this function and if the variable processing is allowed, it searches for ${...} sequances and when such are found, it replaces them with the corresponding variable content.

The process is recursive meaning that if a variable includes the ${...} sequence, that variable will itself also be replaced.

The variables can be defined in a [variables] section and by the programmer by calling the set_variable() function.

Note

This functionality is automatically used when the SYSTEM_OPTION_PROCESS_VARIABLES flag is set in your environment definition. If you prefer to have it only function for a few of your parameters, then do not set the SYSTEM_OPTION_PROCESS_VARIABLES and only call this function for the few values you want to include variables.

Todo:

Consider having a cache, although for variables that would return system information, it could change at any time.

Parameters

[in]

value

The parameter value to be processed.

Returns

The processed value with the variables updated.

Definition at line 291 of file variables.cpp.

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

recursive_process_value()

std::string advgetopt::variables::recursive_process_value ( std::string const &  value, variable_names_t &  names  ) const

private

This function goes through value and replaces the ${...} with the corresponding variable data. The content of a variable is itself passed through this process so it is recursive.

The function records which variables it has worked on so far to prevent the function from re-adding the same variable (avoid infinite loop).

Parameters

[in]	value	The value to parse.
[in]	names	A set of variable names that have already been processed.

Definition at line 316 of file variables.cpp.

References get_variable(), advgetopt::option_flags_merge(), and recursive_process_value().

Referenced by process_value(), and recursive_process_value().

set_variable()

void advgetopt::variables::set_variable	(	std::string const &	name,
		std::string const &	value,
		assignment_t	assignment = assignment_t::ASSIGNMENT_SET
	)

This function sets a variable in the getopt object.

The value of variables can be used to replace ${...} entries in parameters found on the command line or in configuration files.

By default, if that variable already existed, then its value gets replaced (assignment_t::ASSIGNMENT_SET).

You can use this function to define a default after loading data with:

vars->set_variable("foo", "default value", assignment_t::ASSIGNMENT_OPTIONAL);

Note

The value of a variable can itself include ${...} references. When parsing a parameter for variables, such are replaced recursively. See process_value() for details.

Parameters

[in]	name	The name of the variable.
[in]	value	The value of the variable.
[in]	assignment	The operator to use to set this variable.

See also

process_value()

Definition at line 212 of file variables.cpp.

References advgetopt::ASSIGNMENT_APPEND, advgetopt::ASSIGNMENT_NEW, advgetopt::ASSIGNMENT_OPTIONAL, canonicalize_variable_name(), f_variables, and advgetopt::option_flags_merge().

Member Data Documentation

f_variables

variable_t advgetopt::variables::f_variables = variable_t()

private

Definition at line 83 of file variables.h.

Referenced by get_variable(), get_variables(), has_variable(), and set_variable().

---

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

• /home/alexis/snapwebsites/snapcpp/contrib/advgetopt/advgetopt/variables.h
• /home/alexis/snapwebsites/snapcpp/contrib/advgetopt/advgetopt/variables.cpp