Parses, stores, and exposes command-line options and YAML configuration values. More...

#include <goptions.h>

Public Member Functions
	GOptions ()
	Default constructor.
	GOptions (std::string name)
	Constructor for creating verbosity/debug schema helpers.
	GOptions (int argc, char *argv[], const GOptions &user_defined_options=GOptions())
	Main constructor: registers options and parses inputs (YAML + command line).
	~GOptions ()
	Destructor.
void	defineSwitch (const std::string &name, const std::string &description, bool default_status=false)
	Defines and adds a command-line switch.
void	defineOption (const GVariable &gvar, const std::string &help)
	Defines and adds a scalar option.
void	defineOption (const std::string &name, const std::string &description, const std::vector< GVariable > &gvars, const std::string &help)
	Defines and adds a structured option (map or sequence of maps).
int	getScalarInt (const std::string &tag) const
	Retrieves the value of a scalar integer option.
double	getScalarDouble (const std::string &tag) const
	Retrieves the value of a scalar double option.
std::string	getScalarString (const std::string &tag) const
	Retrieves the value of a scalar string option.
bool	getSwitch (const std::string &tag) const
	Retrieves the status of a switch.
YAML::Node	getOptionNode (const std::string &tag) const
	Retrieves the YAML node for the specified option.
YAML::Node	getOptionMapInNode (const std::string &option_name, const std::string &map_key) const
	Retrieves a map entry value from a structured option stored as a sequence of maps.
void	setOptionValueFromString (const std::string &optionName, const std::string &possibleYamlNode)
	Updates an option value from a YAML-formatted string.
int	getVerbosityFor (const std::string &tag) const
	Retrieves the verbosity level for the specified tag.
int	getDebugFor (const std::string &tag) const
	Retrieves the debug level for the specified tag.
const std::vector< GOption > &	getOptions () const
	Returns the list of defined options.
const std::map< std::string, GSwitch > &	getSwitches () const
	Returns the map of defined switches.
void	addGOptions (const GOptions &src)
	Merges options and switches from another GOptions : into this one.
void	addOptionTitle (const std::string &name)
template<typename T>
T	get_variable_in_option (const YAML::Node &node, const std::string &variable_name, const T &default_value)
	Retrieves a typed variable from a YAML node within an option.
std::vector< std::string >	getYamlFiles () const
	Returns the list of YAML file paths detected on the command line.
bool	doesOptionExist (const std::string &tag) const
	Checks if an option exists.

Data Fields
std::string	option_verbosity_name {UNINITIALIZEDSTRINGQUANTITY}
	Name used when constructing the verbosity/debug schema helper.
std::vector< GVariable >	option_verbosity_names
	Schema entries used to define the verbosity and debug structured options.

Detailed Description

GOptions : manages two categories of configuration inputs:

Switches (GSwitch :): boolean flags toggled by presence (e.g., -gui).
Options (GOption :): values that can be scalar or structured (map/sequence), set via YAML files and/or -name=value command line arguments.

Parsing precedence is:

YAML file(s) (in the order they appear on the command line)
Command-line options, which overwrite YAML values

The main constructor GOptions(argc, argv, user_defined_options) performs parsing immediately and may call exit() for help/version requests or invalid inputs.

Typical lifecycle:

Build a definition-only GOptions : instance (often in a plugin/framework function).
Construct a parsing GOptions : instance in main() using that definition set.
Query resolved values using typed getters or direct YAML node access.

Definition at line 45 of file goptions.h.

Constructor & Destructor Documentation

◆ GOptions() [1/3]

GOptions::GOptions ( )

inline

Creates an empty GOptions : instance. This is primarily used to build up user-defined option sets (e.g., in plugin/framework defineOptions() functions) that will later be merged into a parsing instance.

Definition at line 56 of file goptions.h.

◆ GOptions() [2/3]

GOptions::GOptions ( std::string name )

inlineexplicit

This convenience constructor registers one schema entry (via addOptionTitle()) into option_verbosity_names. It is used to populate the standard verbosity and debug structured options.

Parameters

name	The verbosity/debug key name to add to the schema.

Definition at line 69 of file goptions.h.

◆ GOptions() [3/3]

GOptions::GOptions	(	int	argc,
		char *	argv[],
		const GOptions &	user_defined_options = GOptions() )

The parsing pipeline performs:

registration of built-in switches/options,
merging of any user-defined switches/options,
parsing of YAML files present in argv,
parsing of command-line tokens (including dot-notation for structured sub-options),
writing of a resolved configuration YAML snapshot.

Parameters

argc	Number of command-line arguments.
argv	Array of command-line argument strings.
user_defined_options	A GOptions : containing additional options/switches to register.

Definition at line 55 of file goptions.cc.

◆ ~GOptions()

GOptions::~GOptions ( )

inline

Owns and deletes yamlConf if it was allocated by the parsing constructor. This ensures file handles are closed and memory is released deterministically.

Definition at line 96 of file goptions.h.

Member Function Documentation

◆ addGOptions()

void GOptions::addGOptions ( const GOptions & src )

inline

Merge rules:

Options are merged by option name; an option is added only if absent.
Switches are inserted by name; existing names remain unchanged.
Verbosity/debug schema names are merged by key name; duplicates are avoided.

This function enables a plugin/framework pattern:

goptions += pluginA::defineOptions();

goptions += pluginB::defineOptions();

goptions

Definition goptionsConventions.h:69

Parameters

src	Source GOptions : to merge into this instance.

Definition at line 302 of file goptions.h.

◆ addOptionTitle()

void GOptions::addOptionTitle ( const std::string & name )

inline

Definition at line 347 of file goptions.h.

◆ defineOption() [1/2]

void GOptions::defineOption	(	const GVariable &	gvar,
		const std::string &	help )

Scalar options hold a single value (int/double/string/bool expressed as string in YAML) and are set using -name=value.

Parameters

gvar	Option descriptor (name, default value, description).
help	Additional detailed help text.

Definition at line 254 of file goptions.cc.

◆ defineOption() [2/2]

void GOptions::defineOption	(	const std::string &	name,
		const std::string &	description,
		const std::vector< GVariable > &	gvars,
		const std::string &	help )

A structured option is described by a vector of GVariable : schema entries. If any schema entry uses goptions::NODFLT : as its default, that key becomes mandatory and the option becomes cumulative.

Parameters

name	Option name (without leading '-').
description	Brief description shown in summary help.
gvars	Schema definitions (keys, defaults, descriptions).
help	Detailed help text and examples.

Definition at line 266 of file goptions.cc.

◆ defineSwitch()

void GOptions::defineSwitch	(	const std::string &	name,
		const std::string &	description,
		bool	default_status = false )

Switches are presence-based boolean flags and are activated by specifying -<name> on the command line. They default to off, but a switch may be defined as on by default via default_status; such a switch can be turned off explicitly (e.g. -<name>=false).

Registration rules:

A switch name must be unique.
Defining the same switch twice is a configuration error and results in an exit code.

Parameters

name	Switch name (without leading '-').
description	Text shown in help output.
default_status	Initial on/off status of the switch (default: off).

Definition at line 242 of file goptions.cc.

◆ doesOptionExist()

bool GOptions::doesOptionExist ( const std::string & tag ) const

nodiscard

Parameters

tag	Option name.

Returns: True if the option exists; false otherwise.

Definition at line 388 of file goptions.cc.

◆ get_variable_in_option()

template<typename T>

template bool GOptions::get_variable_in_option< bool >	(	const YAML::Node &	node,
		const std::string &	variable_name,
		const T &	default_value )

Utility for structured options where individual keys may or may not be present. If the key is absent, the caller-provided default_value is returned.

Template Parameters

T	The type of the variable.

Parameters

node	YAML node to query.
variable_name	Key name.
default_value	Fallback value when key is absent.

Returns: Parsed value or fallback.

Definition at line 520 of file goptions.cc.

◆ getDebugFor()

int GOptions::getDebugFor ( const std::string & tag ) const

nodiscard

Accepts values as either booleans ("true"/"false") or integers. This allows a command line such as:

-debug.gemc=true
-debug.gemc=1

Parameters

tag	Debug key (e.g., "gemc").

Returns: Debug level as integer.

Definition at line 552 of file goptions.cc.

◆ getOptionMapInNode()

YAML::Node GOptions::getOptionMapInNode	(	const std::string &	option_name,
		const std::string &	map_key ) const

nodiscard

This is commonly used for options like verbosity and debug, where each sequence element is a {key: value} map.

The function searches the sequence for a map whose key matches map_key and returns the corresponding YAML node (which may itself be a scalar, map, or sequence).

Parameters

option_name	Structured option name.
map_key	Key to retrieve.

Returns: YAML node associated with map_key .

Definition at line 502 of file goptions.cc.

◆ getOptionNode()

YAML::Node GOptions::getOptionNode ( const std::string & tag ) const

inlinenodiscard

This provides direct access to the YAML node underlying the option, enabling clients to inspect structured content without additional copying.

This is typically used when:

the option stores a sequence of maps and the caller wants custom logic,
the caller wants to forward the node to another component without re-parsing.

Parameters

tag	Option name.

Returns: YAML node representing the option value.

Warning: If the option does not exist, this function exits with EC__NOOPTIONFOUND .

Definition at line 208 of file goptions.h.

◆ getOptions()

const std::vector< GOption > & GOptions::getOptions ( ) const

inlinenodiscard

Returns: Const reference to internal option vector.

Definition at line 276 of file goptions.h.

◆ getScalarDouble()

double GOptions::getScalarDouble ( const std::string & tag ) const

nodiscard

Parameters

tag	Option name.

Returns: Value converted to double.

Definition at line 291 of file goptions.cc.

◆ getScalarInt()

int GOptions::getScalarInt ( const std::string & tag ) const

nodiscard

See getScalarString() for YAML null sentinel behavior.

Parameters

tag	Option name.

Returns: Value converted to int.

Definition at line 280 of file goptions.cc.

◆ getScalarString()

std::string GOptions::getScalarString ( const std::string & tag ) const

nodiscard

If the underlying YAML node is null, returns the literal sentinel "NULL". This sentinel is intentionally explicit so downstream code can distinguish "unset" from an empty string.

Parameters

tag	Option name.

Returns: Value as string (or "NULL").

Definition at line 302 of file goptions.cc.

◆ getSwitch()

bool GOptions::getSwitch ( const std::string & tag ) const

nodiscard

Parameters

tag	Switch name.

Returns: True if enabled; false otherwise.

Definition at line 489 of file goptions.cc.

◆ getSwitches()

const std::map< std::string, GSwitch > & GOptions::getSwitches ( ) const

inlinenodiscard

Returns: Const reference to internal switch map.

Definition at line 283 of file goptions.h.

◆ getVerbosityFor()

int GOptions::getVerbosityFor ( const std::string & tag ) const

nodiscard

The verbosity option is stored as a sequence of single-entry maps. This helper finds the entry whose key matches tag and returns the associated integer.

Parameters

tag	Verbosity key (e.g., "ghits").

Returns: Verbosity level as integer.

Definition at line 538 of file goptions.cc.

◆ getYamlFiles()

std::vector< std::string > GOptions::getYamlFiles ( ) const

inlinenodiscard

YAML files are detected by extension (".yaml" or ".yml") and are parsed in argv order. This order matters because later YAML files overwrite earlier YAML values, and command-line tokens overwrite all YAML values.

Returns: Vector of YAML file path strings.

Definition at line 378 of file goptions.h.

◆ setOptionValueFromString()

void GOptions::setOptionValueFromString	(	const std::string &	optionName,
		const std::string &	possibleYamlNode )

This uses the same parser as command-line -name=value options, allowing GUI modules to keep runtime options synchronized with user selections.

Parameters

optionName	Option name to update.
possibleYamlNode	Scalar, map, or sequence encoded as YAML text.

Definition at line 471 of file goptions.cc.

Field Documentation

◆ option_verbosity_name

std::string GOptions::option_verbosity_name {UNINITIALIZEDSTRINGQUANTITY}

Defaults to UNINITIALIZEDSTRINGQUANTITY and is typically set by the GOptions(name) helper constructor.

Definition at line 336 of file goptions.h.

◆ option_verbosity_names

std::vector<GVariable> GOptions::option_verbosity_names

Each GVariable : in this vector is used as a schema key (e.g., "gemc", "gparticle", etc.) with an integer default value and a short description.

Definition at line 345 of file goptions.h.

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

Public Member Functions

Data Fields

Detailed Description

Constructor & Destructor Documentation

◆ GOptions() [1/3]

◆ GOptions() [2/3]

◆ GOptions() [3/3]

◆ ~GOptions()

Member Function Documentation

◆ addGOptions()

◆ addOptionTitle()

◆ defineOption() [1/2]

◆ defineOption() [2/2]

◆ defineSwitch()

◆ doesOptionExist()

◆ get_variable_in_option()

◆ getDebugFor()

◆ getOptionMapInNode()

◆ getOptionNode()

◆ getOptions()

◆ getScalarDouble()

◆ getScalarInt()

◆ getScalarString()

◆ getSwitch()

◆ getSwitches()

◆ getVerbosityFor()

◆ getYamlFiles()

◆ setOptionValueFromString()

Field Documentation

◆ option_verbosity_name

◆ option_verbosity_names