Basic argument parsing with automatic help messages. More...

#include <argument_parser.hpp>

Inheritance diagram for lbann::utils::argument_parser< ErrorHandler >:

Collaboration diagram for lbann::utils::argument_parser< ErrorHandler >:

Classes
class	missing_required_arguments
	std::exception subclass that is thrown if a required argument is not found. More...

class	parse_error
	std::exception subclass that is thrown if the parser can not parse the arguments. More...

class	readonly_reference
	A proxy class representing the current value associated with an option. More...

Public Member Functions
template<typename T >
auto	add_option (std::string const &name, std::initializer_list< std::string > cli_flags, std::string const &description, T default_value) -> readonly_reference< T >

template<typename T >
auto	add_argument (std::string const &name, std::string const &description, T default_value) -> readonly_reference< T >

template<typename T >
auto	add_required_argument (std::string const &name, std::string const &description) -> readonly_reference< T >

Constructors
	argument_parser ()
	Create the parser. More...

	argument_parser (argument_parser const &)=delete
	Copy construction is disabled. More...

argument_parser &	operator= (argument_parser const &)=delete
	Copy assignment is disabled. More...

	argument_parser (argument_parser &&)=default
	Move constructor. More...

argument_parser &	operator= (argument_parser &&)=default
	Move assignment operator. More...

Adding options and arguments
readonly_reference< bool >	add_flag (std::string const &name, std::initializer_list< std::string > cli_flags, std::string const &description)
	Add a flag (i.e. a boolean parameter that is "true" if given and "false" if not given). More...

template<typename AccessPolicy >
readonly_reference< bool >	add_flag (std::string const &name, std::initializer_list< std::string > cli_flags, EnvVariable< AccessPolicy > env, std::string const &description)
	Add a flag with environment variable override. More...

template<typename T >
readonly_reference< T >	add_option (std::string const &name, std::initializer_list< std::string > cli_flags, std::string const &description, T default_value=T())
	Add an additional named option. More...

template<typename T , typename AccessPolicy >
readonly_reference< T >	add_option (std::string const &name, std::initializer_list< std::string > cli_flags, EnvVariable< AccessPolicy > env, std::string const &description, T default_value=T())
	Add an additional named option. More...

readonly_reference< std::string >	add_option (std::string const &name, std::initializer_list< std::string > cli_flags, std::string const &description, char const *default_value)
	Add an additional named option; overloaded for "char const*" parameters. More...

template<typename AccessPolicy >
readonly_reference< std::string >	add_option (std::string const &name, std::initializer_list< std::string > cli_flags, EnvVariable< AccessPolicy > env, std::string const &description, char const *default_value)
	Add an additional named option; overloaded for "char const*" parameters. More...

template<typename T >
readonly_reference< T >	add_argument (std::string const &name, std::string const &description, T default_value=T())
	Add an optional positional argument. More...

readonly_reference< std::string >	add_argument (std::string const &name, std::string const &description, char const *default_value)
	Add a positional argument; char const* overload. More...

template<typename T >
readonly_reference< T >	add_required_argument (std::string const &name, std::string const &description)
	Add a "required" positional argument. More...

void	clear () noexcept
	Clear all state in the parser. More...

Command-line-like parsing
void	parse (int argc, char const *const argv[])
	Parse the command line arguments and finalize the arguments. More...

void	parse_no_finalize (int argc, char const *const argv[])
	Parse the command line arguments but do not finalize the parser. More...

void	finalize () const
	Assert that all required components are set properly. More...

Queries
std::string	get_exe_name () const noexcept
	Get the executable name. More...

bool	option_is_defined (std::string const &option_name) const
	Test if an option exists in the parser. More...

bool	help_requested () const
	Test if help has been requested. More...

template<typename T >
T const &	get (std::string const &option_name) const
	Get the requested value from the argument list. More...

Output
void	print_help (std::ostream &stream) const
	Print a help string to a stream. More...

Private Member Functions
void	init () noexcept
	Reinitialize the parser. More...

readonly_reference< bool >	add_flag_impl_ (std::string const &name, std::initializer_list< std::string > cli_flags, std::string const &description, bool default_value)
	Implementation of add_flag. More...

Private Attributes
std::unordered_map< std::string, std::any >	params_
	Dictionary of arguments to their values. More...

std::unordered_set< std::string >	required_
	Patch around in-progress clara limitation. More...

clara::Parser	parser_
	The underlying clara object. More...

Detailed Description

template<typename ErrorHandler>
class lbann::utils::argument_parser< ErrorHandler >

Basic argument parsing with automatic help messages.

Supported parameter types

The argument parser supports 3 types of command line parameters: flags, options, and arguments.

Flags

Flags default to "false" and toggle to "true" when they are given on the command line. It is an error to provide a value to a flag on the command line (e.g., "-flag 0"). If a flag called "-v" is tied to a variable called verbose, verbose will have default value false. Passing "-v" on the command line, a.out -v, will result in verbose having post-parse value true.

Options

Options represent key-value pairs. They must take only a single value (e.g. a.out -key value). It is an error to omit a value for a parameter of option type (e.g., a.out -key). Options are strongly typed to match their default values. The string passed on the command line must be convertible to the type of the default value provided by the developer programmatically.

Arguments

Arguments (or "positional arguments") do not name a key on the command line and are implicitly keyed by their index in the argument list. A corollary to this is that required arguments must appear before optional arguments. Arguments with each category ("required" and "optional") are keyed in the order in which they are added.

On command line, "optional" arguments are ordered after the "required" arguments, in the order in which they are added. For example, adding an (optional) argument called "A", then adding a required argument called "B", then adding an (optioinal) argument called "C" will require that these arguments be passed as a.out B A C. Since "A" and "C" are optional, it is also valid to pass a.out B or a.out B A. It is undefined behavior to pass a.out B C.

Erroneously passing a.out B C might be accepted by the parser if "A" and "C" have the same (or sufficiently compatible) types, but the output will not be as unexpected (the variable bound to "A" will have the value expected in "C", and the variable bound to "C" will have its default value). If "A" and "C" are not compatible types, an exception will be thrown. In the first case, the parser cannot read your mind to know if you passed things in the right order; it is the application developer's responsibility to ensure that all arguments have been added before the help message is printed, and it is the user's responsibility to consult the help message for the runtime ordering of arguments.

Finalization

To accomodate the presence of required arguments with the maintenance-intensive practice of adding arguments willy-nilly (because I don't believe a PR without said terrifying capability would ever make it through), parsing of the arguments can be done two ways: with or without finalization.

If there are no required arguments registered in the parser, these should be equivalent. If there are required arguments, they must all have been registered with the parser and seen in the arguments given to the parse functions before finalization. Semantically, the parser must be finalized before attempting to use any of the required arguments.

Definition at line 160 of file argument_parser.hpp.

Constructor & Destructor Documentation

◆ argument_parser() [1/3]

template<typename ErrorHandler >

lbann::utils::argument_parser< ErrorHandler >::argument_parser ( )

Create the parser.

Definition at line 726 of file argument_parser.hpp.

◆ argument_parser() [2/3]

template<typename ErrorHandler>

lbann::utils::argument_parser< ErrorHandler >::argument_parser ( argument_parser< ErrorHandler > const & )

delete

Copy construction is disabled.

The Clara parser is not actually copyable because the references are bound to memory in the parameter map. They are not re-bound during the default copy, so the copied parser would refer to memory in the source parser. If the source parser is destroyed, these references are left dangling. It would be very hard to rebind the references on copy (it would have to be done through "std::any" object, making it all the more complicated). Rather, we don't have the other machinery to do this at this time, so copy is disabled. This issue should not apply to move.

◆ argument_parser() [3/3]

template<typename ErrorHandler>

lbann::utils::argument_parser< ErrorHandler >::argument_parser ( argument_parser< ErrorHandler > && )

default

Move constructor.

Member Function Documentation

◆ add_argument() [1/3]

template<typename ErrorHandler>

template<typename T >

readonly_reference<T> lbann::utils::argument_parser< ErrorHandler >::add_argument	(	std::string const &	name,
		std::string const &	description,
		T	default_value = `T()`
	)

Add an optional positional argument.

These are essentially defaulted positional arguments. They must be given on the command line in the order in which they are added to the parser. If the arguments have all been added by the time the help message is produced, the help message will display the correct ordering.

Template Parameters

T	The type to which the argument maps.

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	description	A brief description of the argument, used for the help message.
[in]	default_value	The value to use for this argument if not detected in the formal argument list.

Returns: A read-only reference to the value pointed to by this argument.

◆ add_argument() [2/3]

template<typename ErrorHandler>

readonly_reference<std::string> lbann::utils::argument_parser< ErrorHandler >::add_argument	(	std::string const &	name,
		std::string const &	description,
		char const *	default_value
	)

inline

Add a positional argument; char const* overload.

The data is stored in an std::string object internally and must be accessed using get<std::string>(name).

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	description	A brief description of the argument, used for the help message.
[in]	default_value	The value to use for this argument if not detected in the formal argument list.

Returns: A read-only reference to the value pointed to by this argument.

Definition at line 508 of file argument_parser.hpp.

Here is the call graph for this function:

◆ add_argument() [3/3]

template<typename ErrorHandler>

template<typename T >

auto lbann::utils::argument_parser< ErrorHandler >::add_argument	(	std::string const &	name,
		std::string const &	description,
		T	default_value
	)		-> readonly_reference<T>

inline

Definition at line 682 of file argument_parser.hpp.

◆ add_flag() [1/2]

template<typename ErrorHandler >

auto lbann::utils::argument_parser< ErrorHandler >::add_flag	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		std::string const &	description
	)

Add a flag (i.e. a boolean parameter that is "true" if given and "false" if not given).

The value of a flag defaults to false. If, for some strange reason, users should be forced to type the boolean value on the command line, e.g., "my_exe -b 1", use add_option() instead. If a flag with default value true is desired, invert the logic and use this instead.

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	cli_flags	The valid command line flags to trigger this flag to `true`. At least one must be given.
[in]	description	A brief description of the argument, used for the help message.

Returns: A read-only reference to the value pointed to by this flag.

Definition at line 775 of file argument_parser.hpp.

◆ add_flag() [2/2]

template<typename ErrorHandler>

template<typename AccessPolicy >

readonly_reference<bool> lbann::utils::argument_parser< ErrorHandler >::add_flag	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		EnvVariable< AccessPolicy >	env,
		std::string const &	description
	)

inline

Add a flag with environment variable override.

The value of a flag defaults to false. The flag may be set to true by passing the flag on the command line. Alternatively, it may be set to true if the environment variable env is defined and has a value that converts to true.

Template Parameters

AccessPolicy The access method for the environment variable. (Deduced.)

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	cli_flags	The valid command line flags to trigger this flag to `true`. At least one must be given.
[in]	env	The environment variable to prefer over the default parameter value.
[in]	description	A brief description of the argument, used for the help message.

Returns: A read-only reference to the value pointed to by this flag.

Definition at line 318 of file argument_parser.hpp.

Here is the call graph for this function:

◆ add_flag_impl_()

template<typename ErrorHandler >

auto lbann::utils::argument_parser< ErrorHandler >::add_flag_impl_	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		std::string const &	description,
		bool	default_value
	)

private

Implementation of add_flag.

Definition at line 802 of file argument_parser.hpp.

◆ add_option() [1/5]

template<typename ErrorHandler>

template<typename T >

readonly_reference<T> lbann::utils::argument_parser< ErrorHandler >::add_option	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		std::string const &	description,
		T	default_value = `T()`
	)

Add an additional named option.

Currently, named options are all optional. This could be expanded if needed.

Template Parameters

T	The type associated with the option. Deduced if a default value is given. If the default value is not given, the template parameter must be named explicitly and the default value will be default-constructed.

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	cli_flags	The valid command line flags to identify this option and its value. At least one must be given.
[in]	description	A brief description of the argument, used for the help message.
[in]	default_value	The default value to be returned if the option is not passed to the command line.

Returns: A read-only reference to the value pointed to by this option.

◆ add_option() [2/5]

template<typename ErrorHandler>

template<typename T , typename AccessPolicy >

readonly_reference<T> lbann::utils::argument_parser< ErrorHandler >::add_option	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		EnvVariable< AccessPolicy >	env,
		std::string const &	description,
		T	default_value = `T()`
	)

inline

Add an additional named option.

Currently, named options are all optional. This could be expanded if needed.

Template Parameters

T	The type associated with the option. Deduced if a default value is given. If the default value is not given, the template parameter must be named explicitly and the default value will be default-constructed.
AccessPolicy	The access method for the environment variable. (Deduced.)

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	cli_flags	The valid command line flags to identify this option and its value. At least one must be given.
[in]	env	The environment variable to prefer over the default parameter value.
[in]	description	A brief description of the argument, used for the help message.
[in]	default_value	The default value to be returned if the option is not passed to the command line.

Returns: A read-only reference to the value pointed to by this option.

Definition at line 389 of file argument_parser.hpp.

Here is the call graph for this function:

◆ add_option() [3/5]

template<typename ErrorHandler>

readonly_reference<std::string> lbann::utils::argument_parser< ErrorHandler >::add_option	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		std::string const &	description,
		char const *	default_value
	)

inline

Add an additional named option; overloaded for "char const*" parameters.

The value will be stored as an std::string. Its value must be extracted using get<std::string>(name).

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	cli_flags	The valid command line flags to trigger this flag to `true`. At least one must be given.
[in]	description	A brief description of the argument, used for the help message.
[in]	default_value	The default value to be returned if the option is not passed to the command line.

Returns: A read-only reference to the value pointed to by this option.

Definition at line 425 of file argument_parser.hpp.

◆ add_option() [4/5]

template<typename ErrorHandler>

template<typename AccessPolicy >

readonly_reference<std::string> lbann::utils::argument_parser< ErrorHandler >::add_option	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		EnvVariable< AccessPolicy >	env,
		std::string const &	description,
		char const *	default_value
	)

inline

Add an additional named option; overloaded for "char const*" parameters.

The value will be stored as an std::string. Its value must be extracted using get<std::string>(name).

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	cli_flags	The valid command line flags to trigger this flag to `true`. At least one must be given.
[in]	env	The environment variable to prefer over the default parameter value.
[in]	description	A brief description of the argument, used for the help message.
[in]	default_value	The default value to be returned if the option is not passed to the command line.

Returns: A read-only reference to the value pointed to by this option.

Definition at line 457 of file argument_parser.hpp.

Here is the call graph for this function:

◆ add_option() [5/5]

template<typename ErrorHandler>

template<typename T >

auto lbann::utils::argument_parser< ErrorHandler >::add_option	(	std::string const &	name,
		std::initializer_list< std::string >	cli_flags,
		std::string const &	description,
		T	default_value
	)		-> readonly_reference<T>

inline

Definition at line 664 of file argument_parser.hpp.

◆ add_required_argument() [1/2]

template<typename ErrorHandler>

template<typename T >

readonly_reference<T> lbann::utils::argument_parser< ErrorHandler >::add_required_argument	(	std::string const &	name,
		std::string const &	description
	)

Add a "required" positional argument.

Template Parameters

T	The type to which the argument maps.

Parameters

[in]	name	The name to be used to refer to the argument.
[in]	description	A brief description of the argument, used for the help message.

Returns: A read-only reference to the value pointed to by this argument.

◆ add_required_argument() [2/2]

template<typename ErrorHandler>

template<typename T >

auto lbann::utils::argument_parser< ErrorHandler >::add_required_argument	(	std::string const &	name,
		std::string const &	description
	)		-> readonly_reference<T>

inline

Definition at line 695 of file argument_parser.hpp.

◆ clear()

template<typename ErrorHandler >

void lbann::utils::argument_parser< ErrorHandler >::clear ( )

noexcept

Clear all state in the parser.

The resulting state is as though the parser had been newly constructed.

Definition at line 732 of file argument_parser.hpp.

◆ finalize()

template<typename ErrorHandler >

void lbann::utils::argument_parser< ErrorHandler >::finalize ( ) const

Assert that all required components are set properly.

This should be called sometime after parse_no_finalize() and before using the values. This is implicitly called by parse().

Exceptions

missing_required_arguments If a missing argument is detected.

Definition at line 768 of file argument_parser.hpp.

◆ get()

template<typename ErrorHandler >

template<typename T >

T const & lbann::utils::argument_parser< ErrorHandler >::get ( std::string const & option_name ) const

inline

Get the requested value from the argument list.

Template Parameters

T	The type of the requested parameter.

Parameters

option_name The name given to the option or argument.

Returns: A const-reference to the held value.

Definition at line 654 of file argument_parser.hpp.

◆ get_exe_name()

template<typename ErrorHandler >

std::string lbann::utils::argument_parser< ErrorHandler >::get_exe_name ( ) const

noexcept

Get the executable name.

This is only meaningful after calling either parse() or parse_no_finalize().

Returns: The name of the executable.

Definition at line 784 of file argument_parser.hpp.

◆ help_requested()

template<typename ErrorHandler >

bool lbann::utils::argument_parser< ErrorHandler >::help_requested ( ) const

Test if help has been requested.

Definition at line 790 of file argument_parser.hpp.

◆ init()

template<typename ErrorHandler >

void lbann::utils::argument_parser< ErrorHandler >::init ( )

privatenoexcept

Reinitialize the parser.

Definition at line 741 of file argument_parser.hpp.

◆ operator=() [1/2]

template<typename ErrorHandler>

argument_parser& lbann::utils::argument_parser< ErrorHandler >::operator= ( argument_parser< ErrorHandler > const & )

delete

Copy assignment is disabled.

◆ operator=() [2/2]

template<typename ErrorHandler>

argument_parser& lbann::utils::argument_parser< ErrorHandler >::operator= ( argument_parser< ErrorHandler > && )

default

Move assignment operator.

◆ option_is_defined()

template<typename ErrorHandler >

bool lbann::utils::argument_parser< ErrorHandler >::option_is_defined ( std::string const & option_name ) const

inline

Test if an option exists in the parser.

This only tests whether the argument or option is known to the parser, not whether it has been set or modified by the parser.

Parameters

[in] option_name The name of the option/argument.

Definition at line 645 of file argument_parser.hpp.

◆ parse()

template<typename ErrorHandler >

void lbann::utils::argument_parser< ErrorHandler >::parse	(	int	argc,
		char const *const	argv[]
	)

Parse the command line arguments and finalize the arguments.

This is equivalent to calling parse_no_finalize() followed immediately by finalize().

Parameters

[in]	argc	The number of arguments
[in]	argv	The list of arguments

Exceptions

parse_error if an internal parsing error is detected.

Definition at line 749 of file argument_parser.hpp.

Here is the call graph for this function:

◆ parse_no_finalize()

template<typename ErrorHandler >

void lbann::utils::argument_parser< ErrorHandler >::parse_no_finalize	(	int	argc,
		char const *const	argv[]
	)

Parse the command line arguments but do not finalize the parser.

This parses command-line-like arguments but does no checks for required arguments. Users should call finalize() before attempting to use the values associated with any required arguments.

Parameters

[in]	argc	The number of arguments
[in]	argv	The list of arguments

Exceptions

parse_error if an internal parsing error is detected.

Definition at line 756 of file argument_parser.hpp.

◆ print_help()

template<typename ErrorHandler >

void lbann::utils::argument_parser< ErrorHandler >::print_help ( std::ostream & stream ) const

Print a help string to a stream.

Parameters

[in] stream The ostream to print the help message to.

Definition at line 796 of file argument_parser.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ params_

template<typename ErrorHandler>

std::unordered_map<std::string, std::any> lbann::utils::argument_parser< ErrorHandler >::params_

private

Dictionary of arguments to their values.

Definition at line 637 of file argument_parser.hpp.

◆ parser_

template<typename ErrorHandler>

clara::Parser lbann::utils::argument_parser< ErrorHandler >::parser_

private

The underlying clara object.

Definition at line 641 of file argument_parser.hpp.

◆ required_

template<typename ErrorHandler>

std::unordered_set<std::string> lbann::utils::argument_parser< ErrorHandler >::required_

private

Patch around in-progress clara limitation.

Definition at line 639 of file argument_parser.hpp.

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

argument_parser.hpp

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

template<typename ErrorHandler> class lbann::utils::argument_parser< ErrorHandler >

Supported parameter types

Flags

Options

Arguments

Finalization

Constructor & Destructor Documentation

◆ argument_parser() [1/3]

◆ argument_parser() [2/3]

◆ argument_parser() [3/3]

Member Function Documentation

◆ add_argument() [1/3]

◆ add_argument() [2/3]

◆ add_argument() [3/3]

◆ add_flag() [1/2]

◆ add_flag() [2/2]

◆ add_flag_impl_()

◆ add_option() [1/5]

◆ add_option() [2/5]

◆ add_option() [3/5]

◆ add_option() [4/5]

◆ add_option() [5/5]

◆ add_required_argument() [1/2]

◆ add_required_argument() [2/2]

◆ clear()

◆ finalize()

◆ get()

◆ get_exe_name()

◆ help_requested()

◆ init()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ option_is_defined()

◆ parse()

◆ parse_no_finalize()

◆ print_help()

Member Data Documentation

◆ params_

◆ parser_

◆ required_

template<typename ErrorHandler>
class lbann::utils::argument_parser< ErrorHandler >