One command-line option, flag, or positional argument. More...

Inheritance diagram for cli::option_t:

Public Member Functions
	option_t (const option_t &)=delete
auto	operator= (const option_t &) -> option_t &=delete
auto	count () const -> std::size_t
	Returns how many values were collected.
auto	empty () const -> bool
	Reports whether no values were collected.
	operator bool () const
	Reports whether the option was used.
auto	clear () -> void
	Discards collected values and resets the parse state.
template<typename T = app_t>
auto	ignore_case (bool value=true) -> option_t *
	Makes name matching case-insensitive.
template<typename T = app_t>
auto	ignore_underscore (bool value=true) -> option_t *
	Makes name matching ignore underscores.
auto	multi_option_policy (multi_option_policy_t value=multi_option_policy_t::reject) -> option_t *
	Sets what happens to surplus values.
auto	disable_flag_override (bool value=true) -> option_t *
	Rejects --no-flag style overrides.
Setting options
auto	expected (int value) -> option_t *
	Sets how many values the option accepts.
auto	expected (int value_min, int value_max) -> option_t *
	Sets the range of value counts the option accepts.
auto	allow_extra_args (bool value=true) -> option_t *
	Allows the option to absorb surplus arguments.
auto	get_allow_extra_args () const -> bool
	Reports whether the option absorbs surplus arguments.
auto	trigger_on_parse (bool value=true) -> option_t *
	Runs the callback as soon as a value is parsed.
auto	get_trigger_on_parse () const -> bool
	Reports whether the callback runs during parsing.
auto	force_callback (bool value=true) -> option_t *
	Runs the callback even when the option is absent.
auto	get_force_callback () const -> bool
	Reports whether the callback runs when the option is absent.
auto	run_callback_for_default (bool value=true) -> option_t *
	Runs the callback when only the default value is present.
auto	get_run_callback_for_default () const -> bool
	Reports whether the callback runs for default values.
auto	callback_priority (callback_priority_t value=callback_priority_t::normal) -> option_t *
	Sets when this option's callback runs.
Validators and transforms
A check inspects a value; a transform rewrites it. Checks are appended and run after any transforms, which are prepended.
auto	check (validator_ptr_t validator) -> option_t *
	Appends a shared validator as a check.
auto	check (validator_t validator, const std::string &validator_name="") -> option_t *
	Appends a validator as a check.
auto	check (std::function< std::string(const std::string &)> validator_func, std::string validator_description="", std::string validator_name="") -> option_t *
	Appends a callable as a check.
auto	transform (validator_ptr_t validator) -> option_t *
	Prepends a shared validator as a transform.
auto	transform (validator_t validator, const std::string &transform_name="") -> option_t *
	Prepends a validator as a transform.
auto	transform (std::function< std::string(std::string)> transform_func, std::string transform_description="", std::string transform_name="") -> option_t *
	Prepends a callable as a transform.
auto	each (std::function< void(std::string)> func) -> option_t *
	Appends a callable run once per value, for its side effects.
auto	get_validator (const std::string &validator_name="") -> validator_t *
	Finds a validator by name.
auto	get_validator (int index) -> validator_t *
	Finds a validator by position.
Dependencies
auto	needs (option_t opt) -> option_t
	Requires another option to appear alongside this one.
template<typename T = app_t>
auto	needs (std::string opt_name) -> option_t *
	Requires a named option to appear alongside this one.
template<typename A, typename B, typename... args_t>
auto	needs (A opt, B opt1, args_t... args) -> option_t *
	Requires several options to appear alongside this one.
auto	remove_needs (option_t *opt) -> bool
	Drops a dependency.
auto	excludes (option_t opt) -> option_t
	Forbids another option from appearing alongside this one.
template<typename T = app_t>
auto	excludes (std::string opt_name) -> option_t *
	Forbids a named option from appearing alongside this one.
template<typename A, typename B, typename... args_t>
auto	excludes (A opt, B opt1, args_t... args) -> option_t *
	Forbids several options from appearing alongside this one.
auto	remove_excludes (option_t *opt) -> bool
	Drops an exclusion.
auto	envname (std::string name) -> option_t *
	Sets the environment variable consulted when the option is absent.
Accessors
auto	get_type_size () const -> int
	Returns the smallest number of values one appearance consumes.
auto	get_type_size_min () const -> int
	Returns the smallest number of values one appearance consumes.
auto	get_type_size_max () const -> int
	Returns the largest number of values one appearance consumes.
auto	get_inject_separator () const -> bool
	Reports whether a separator is inserted between value groups.
auto	get_envname () const -> const std::string &
	Returns the environment variable consulted when the option is absent.
auto	get_needs () const -> const std::set< option_t * > &
	Returns the options this one depends on.
auto	get_excludes () const -> const std::set< option_t * > &
	Returns the options this one excludes.
auto	get_default_str () const -> const std::string &
	Returns the default value as shown in help output.
auto	get_callback () const -> const callback_t &
	Returns the callback that writes the bound variable.
auto	get_lnames () const -> const std::vector< std::string > &
	Returns the long names, without their leading dashes.
auto	get_snames () const -> const std::vector< std::string > &
	Returns the short names, without their leading dash.
auto	get_fnames () const -> const std::vector< std::string > &
	Returns the flag names.
auto	get_single_name () const -> const std::string &
	Returns one representative name for this option.
auto	get_expected () const -> int
	Returns the smallest number of values accepted in total.
auto	get_expected_min () const -> int
	Returns the smallest number of values accepted in total.
auto	get_expected_max () const -> int
	Returns the largest number of values accepted in total.
auto	get_items_expected_min () const -> int
	Returns the smallest total number of items accepted.
auto	get_items_expected_max () const -> int
	Returns the largest total number of items accepted.
auto	get_items_expected () const -> int
	Returns the smallest total number of items accepted.
auto	get_positional () const -> bool
	Reports whether this option is a positional.
auto	nonpositional () const -> bool
	Reports whether this option has a dashed name.
auto	has_description () const -> bool
	Reports whether a description was set.
auto	get_description () const -> const std::string &
	Returns the description shown in help output.
auto	description (std::string option_description) -> option_t *
	Sets the description shown in help output.
auto	option_text (std::string text) -> option_t *
	Replaces the generated type name in help output.
auto	get_option_text () const -> const std::string &
	Returns the text replacing the generated type name.
Help output
auto	get_name (bool positional=false, bool all_options=false, bool disable_default_flag_values=false) const -> std::string
	Renders this option's name for help output.
Parsing
auto	run_callback () -> void
	Validates, reduces, and hands the results to the callback.
auto	matching_name (const option_t &other) const -> const std::string &
	Returns the first name this option shares with another.
auto	operator== (const option_t &other) const -> bool
	Reports whether two options share a name.
auto	check_name (const std::string &name) const -> bool
	Reports whether a command-line token names this option.
auto	check_sname (std::string name) const -> bool
	Reports whether a short name belongs to this option.
auto	check_lname (std::string name) const -> bool
	Reports whether a long name belongs to this option.
auto	check_fname (std::string name) const -> bool
	Reports whether a flag name belongs to this option.
auto	get_flag_value (const std::string &name, std::string input_value) const -> std::string
	Resolves the value a flag contributes.
auto	add_result (std::string s) -> option_t *
	Adds one raw result, resetting the parse state.
auto	add_result (std::string s, int &results_added) -> option_t *
	Adds one raw result and reports how many entries it produced.
auto	add_result (std::vector< std::string > s) -> option_t *
	Adds several raw results, resetting the parse state.
auto	results () const -> const results_t &
	Returns the raw results, before validation or reduction.
auto	reduced_results () const -> results_t
	Returns the results after validation and reduction.
template<typename T>
auto	results (T &output) const -> void
	Converts the results into a value of type `T`.
template<typename T>
auto	as () const -> T
	Converts the results and returns them.
auto	get_callback_run () const -> bool
	Reports whether the callback has already run.
Type presentation
auto	type_name_fn (std::function< std::string()> typefun) -> option_t *
	Sets the callable producing the type name shown in help output.
auto	type_name (std::string typeval) -> option_t *
	Sets a fixed type name for help output.
auto	type_size (int option_type_size) -> option_t *
	Sets how many values one appearance consumes.
auto	type_size (int option_type_size_min, int option_type_size_max) -> option_t *
	Sets the range of values one appearance may consume.
auto	inject_separator (bool value=true) -> void
	Sets whether a separator is inserted between value groups.
Default values
auto	default_function (std::function< std::string()> func) -> option_t *
	Sets the callable that produces the printed default.
auto	capture_default_str () -> option_t *
	Evaluates the default function and records the result.
auto	default_str (std::string val) -> option_t *
	Sets the printed default directly.
template<typename X>
auto	default_val (const X &val) -> option_t *
	Sets the default from a typed value, checking that it converts.
auto	get_type_name () const -> std::string
	Returns the type name shown in help output.
Public Member Functions inherited from cli::option_base_t
template<typename self_t>
auto	group (this self_t &self, const std::string &name) -> self_t *
	Sets the help group this option is listed under.
template<typename self_t>
auto	required (this self_t &self, bool value=true) -> self_t *
	Marks the option as required.
template<typename self_t>
auto	mandatory (this self_t &self, bool value=true) -> self_t *
	Marks the option as required.
template<typename self_t>
auto	always_capture_default (this self_t &self, bool value=true) -> self_t *
	Captures the bound variable's value as the printed default.
auto	get_group () const -> const std::string &
	Returns the help group this option is listed under.
auto	get_required () const -> bool
	Reports whether the option must appear.
auto	get_ignore_case () const -> bool
	Reports whether name matching ignores case.
auto	get_ignore_underscore () const -> bool
	Reports whether name matching ignores underscores.
auto	get_configurable () const -> bool
	Reports whether the option may be set from a configuration file.
auto	get_disable_flag_override () const -> bool
	Reports whether flag overrides are rejected.
auto	get_delimiter () const -> char
	Returns the character that splits a value into several.
auto	get_always_capture_default () const -> bool
	Reports whether defaults are captured automatically.
auto	get_multi_option_policy () const -> multi_option_policy_t
	Returns what happens to surplus values.
auto	get_callback_priority () const -> callback_priority_t
	Returns when this option's callback runs.
template<typename self_t>
auto	take_last (this self_t &self) -> self_t *
	Keeps only the last value given.
template<typename self_t>
auto	take_first (this self_t &self) -> self_t *
	Keeps only the first value given.
template<typename self_t>
auto	take_all (this self_t &self) -> self_t *
	Keeps every value given.
template<typename self_t>
auto	join (this self_t &self) -> self_t *
	Joins every value given.
template<typename self_t>
auto	join (this self_t &self, char delim) -> self_t *
	Joins every value given, using a specific delimiter.
template<typename self_t>
auto	configurable (this self_t &self, bool value=true) -> self_t *
	Allows or forbids setting the option from a configuration file.
template<typename self_t>
auto	delimiter (this self_t &self, char value='\0') -> self_t *
	Sets the character that splits a value into several.

Protected Types
enum class	option_state_t : std::uint8_t { parsing = 0 , validated = 2 , reduced = 4 , callback_run = 6 }
	How far an option has progressed through parsing. More...

Protected Member Functions
	option_t (std::string option_name, std::string option_description, callback_t callback, app_t *parent, bool allow_non_standard=false)
	Constructs an option from a name specification.
Protected Member Functions inherited from cli::option_base_t
template<typename T>
auto	copy_to (T *other) const -> void
	Copies every shared setting onto another option.

Protected Attributes
std::vector< std::string >	snames_ {}
	Short names, without their leading dash.
std::vector< std::string >	lnames_ {}
	Long names, without their leading dashes.
std::vector< std::pair< std::string, std::string > >	default_flag_values_ {}
	Flag names paired with the default value each implies.
std::vector< std::string >	fnames_ {}
	Every flag name, in the order given.
std::string	pname_ {}
	The positional name, empty if this is not a positional.
std::string	envname_ {}
	The environment variable consulted when the option is absent.
std::string	description_ {}
	The description shown in help output.
std::string	default_str_ {}
	The default value as shown in help output.
std::string	option_text_ {}
	Text replacing the generated type name in help output.
std::function< std::string()>	type_name_ {[] { return std::string(); }}
	Produces the type name shown in help output.
std::function< std::string()>	default_function_ {}
	Produces the default value shown in help output.
int	type_size_max_ {1}
	Largest number of values one appearance consumes.
int	type_size_min_ {1}
	Smallest number of values one appearance consumes.
int	expected_min_ {1}
	Smallest number of values accepted in total.
int	expected_max_ {1}
	Largest number of values accepted in total.
std::vector< validator_ptr_t >	validators_ {}
	Validators and transforms, applied in order.
std::set< option_t * >	needs_ {}
	Options that must also appear.
std::set< option_t * >	excludes_ {}
	Options that must not appear alongside this one.
app_t *	parent_ {nullptr}
	The application this option belongs to.
callback_t	callback_ {}
	Writes the collected results into the bound variable.
results_t	results_ {}
	The raw strings collected during parsing.
results_t	proc_results_ {}
	The results after validation and reduction.
option_state_t	current_option_state_ {option_state_t::parsing}
	How far this option has progressed.
bool	allow_extra_args_ {false}
	Whether surplus arguments are absorbed by this option.
bool	flag_like_ {false}
	Whether this option behaves like a flag.
bool	run_callback_for_default_ {false}
	Whether the callback runs even when only the default is present.
bool	inject_separator_ {false}
	Whether a separator is inserted between value groups.
bool	trigger_on_result_ {false}
	Whether the callback runs as soon as a value is parsed.
bool	force_callback_ {false}
	Whether the callback runs even when the option is absent.
Protected Attributes inherited from cli::option_base_t
std::string	group_ = std::string("OPTIONS")
	The help group this option is listed under.
bool	required_ {false}
	Whether the option must appear.
bool	ignore_case_ {false}
	Whether name matching ignores case.
bool	ignore_underscore_ {false}
	Whether name matching ignores underscores.
bool	configurable_ {true}
	Whether the option may be set from a configuration file.
bool	disable_flag_override_ {false}
	Whether --no-flag style overrides are rejected.
char	delimiter_ {'\0'}
	Character that splits a single value into several.
bool	always_capture_default_ {false}
	Whether the bound value's default is captured automatically.
multi_option_policy_t	multi_option_policy_ {multi_option_policy_t::reject}
	What to do with surplus values.
callback_priority_t	callback_priority_ {callback_priority_t::normal}
	When this option's callback runs.

Detailed Description

One command-line option, flag, or positional argument.

Not constructed directly; app_t::add_option, add_flag, and their relatives create these and hand back a pointer for chaining.

Member Enumeration Documentation

◆ option_state_t

enum class cli::option_t::option_state_t : std::uint8_t

strongprotected

How far an option has progressed through parsing.

Enumerator
parsing	Collecting raw results.
validated	Validators have run.
reduced	The multi-option policy has been applied.
callback_run	The callback has written the bound variable.

Constructor & Destructor Documentation

◆ option_t()

cli::option_t::option_t	(	std::string	option_name,
		std::string	option_description,
		callback_t	callback,
		app_t *	parent,
		bool	allow_non_standard = false )

inlineprotected

Constructs an option from a name specification.

Parameters

option_name	The name specification, for example "-f,--file".
option_description	The description shown in help output.
callback	Writes collected results into the bound variable.
parent	The owning application.
allow_non_standard	Accept multi-character short names.

Exceptions

cli::bad_name_string_t If the specification is malformed.

Member Function Documentation

◆ add_result() [1/3]

auto cli::option_t::add_result ( std::string s ) -> option_t *

inline

Adds one raw result, resetting the parse state.

Parameters

s	The result to add.

Returns: A pointer to this option, for chaining.

◆ add_result() [2/3]

auto cli::option_t::add_result	(	std::string	s,
		int &	results_added ) -> option_t *

inline

Adds one raw result and reports how many entries it produced.

A delimited value can expand into several entries.

Parameters

[in]	s	The result to add.
[out]	results_added	How many entries were appended.

Returns: A pointer to this option, for chaining.

◆ add_result() [3/3]

auto cli::option_t::add_result ( std::vector< std::string > s ) -> option_t *

inline

Adds several raw results, resetting the parse state.

Parameters

s	The results to add.

Returns: A pointer to this option, for chaining.

◆ allow_extra_args()

auto cli::option_t::allow_extra_args ( bool value = true ) -> option_t *

inline

Allows the option to absorb surplus arguments.

Parameters

value Whether to absorb surplus arguments.

Returns: A pointer to this option, for chaining.

◆ as()

template<typename T>

auto cli::option_t::as ( ) const -> T

inlinenodiscard

Converts the results and returns them.

Template Parameters

T	The type to convert to.

Returns: The converted value.

Exceptions

cli::conversion_error_t If the results cannot be converted.

◆ callback_priority()

auto cli::option_t::callback_priority ( callback_priority_t value = callback_priority_t::normal ) -> option_t *

inline

Sets when this option's callback runs.

Parameters

value The callback priority.

Returns: A pointer to this option, for chaining.

◆ capture_default_str()

auto cli::option_t::capture_default_str ( ) -> option_t *

inline

Evaluates the default function and records the result.

Does nothing when no default function is set.

Returns: A pointer to this option, for chaining.

◆ check() [1/3]

auto cli::option_t::check	(	std::function< std::string(const std::string &)>	validator_func,
		std::string	validator_description = "",
		std::string	validator_name = "" ) -> option_t *

inline

Appends a callable as a check.

Parameters

validator_func	Returns an empty string on success, else a message.
validator_description	The description shown in help output.
validator_name	A name to find it by later.

Returns: A pointer to this option, for chaining.

◆ check() [2/3]

auto cli::option_t::check ( validator_ptr_t validator ) -> option_t *

inline

Appends a shared validator as a check.

Parameters

validator The validator to append.

Returns: A pointer to this option, for chaining.

◆ check() [3/3]

auto cli::option_t::check	(	validator_t	validator,
		const std::string &	validator_name = "" ) -> option_t *

inline

Appends a validator as a check.

Parameters

validator	The validator to append.
validator_name	A name to find it by later.

Returns: A pointer to this option, for chaining.

◆ check_fname()

auto cli::option_t::check_fname ( std::string name ) const -> bool

inlinenodiscard

Reports whether a flag name belongs to this option.

Parameters

name	The name to test.

Returns: true if the name matches.

◆ check_lname()

auto cli::option_t::check_lname ( std::string name ) const -> bool

inlinenodiscard

Reports whether a long name belongs to this option.

Parameters

name	The name to test, without its dashes.

Returns: true if the name matches.

◆ check_name()

auto cli::option_t::check_name ( const std::string & name ) const -> bool

inlinenodiscard

Reports whether a command-line token names this option.

Accepts --long, -s, a bare positional name, or the environment variable name.

Parameters

name	The token to test.

Returns: true if the token names this option.

◆ check_sname()

auto cli::option_t::check_sname ( std::string name ) const -> bool

inlinenodiscard

Reports whether a short name belongs to this option.

Parameters

name	The name to test, without its dash.

Returns: true if the name matches.

◆ count()

auto cli::option_t::count ( ) const -> std::size_t

inlinenodiscard

Returns how many values were collected.

Returns: The result count.

◆ default_function()

auto cli::option_t::default_function ( std::function< std::string()> func ) -> option_t *

inline

Sets the callable that produces the printed default.

The callable is not invoked here; call capture_default_str to evaluate it.

Parameters

func	Produces the printed default.

Returns: A pointer to this option, for chaining.

◆ default_str()

auto cli::option_t::default_str ( std::string val ) -> option_t *

inline

Sets the printed default directly.

Parameters

val	The default as it should appear in help output.

Returns: A pointer to this option, for chaining.

◆ default_val()

template<typename X>

auto cli::option_t::default_val ( const X & val ) -> option_t *

inline

Sets the default from a typed value, checking that it converts.

The value is pushed through the option's own conversion and validation path so that an unusable default is reported at construction rather than at parse time. The option's results and state are restored afterwards, including when conversion throws.

Template Parameters

X	The type of the supplied value.

Parameters

val	The default value.

Returns: A pointer to this option, for chaining.

Exceptions

cli::conversion_error_t If the value cannot be converted.

◆ description()

auto cli::option_t::description ( std::string option_description ) -> option_t *

inline

Sets the description shown in help output.

Parameters

option_description The new description.

Returns: A pointer to this option, for chaining.

◆ disable_flag_override()

auto cli::option_t::disable_flag_override ( bool value = true ) -> option_t *

inline

Rejects --no-flag style overrides.

Parameters

value Whether to reject overrides.

Returns: A pointer to this option, for chaining.

◆ each()

auto cli::option_t::each ( std::function< void(std::string)> func ) -> option_t *

inline

Appends a callable run once per value, for its side effects.

Parameters

func	The callable to run.

Returns: A pointer to this option, for chaining.

◆ empty()

auto cli::option_t::empty ( ) const -> bool

inlinenodiscard

Reports whether no values were collected.

Returns: true if nothing was collected.

◆ envname()

auto cli::option_t::envname ( std::string name ) -> option_t *

inline

Sets the environment variable consulted when the option is absent.

Parameters

name	The variable name.

Returns: A pointer to this option, for chaining.

◆ excludes() [1/3]

template<typename A, typename B, typename... args_t>

auto cli::option_t::excludes	(	A	opt,
		B	opt1,
		args_t...	args ) -> option_t *

inline

Forbids several options from appearing alongside this one.

Parameters

opt	The first excluded option.
opt1	The second excluded option.
args	Any further excluded options.

Returns: A pointer to this option, for chaining.

◆ excludes() [2/3]

auto cli::option_t::excludes ( option_t * opt ) -> option_t *

inline

Forbids another option from appearing alongside this one.

The exclusion is recorded on both options.

Parameters

opt	The option to exclude.

Returns: A pointer to this option, for chaining.

Exceptions

cli::incorrect_construction_t If opt is this option.

◆ excludes() [3/3]

template<typename T = app_t>

auto cli::option_t::excludes ( std::string opt_name ) -> option_t *

inline

Forbids a named option from appearing alongside this one.

Template Parameters

T	The application type to look the name up on.

Parameters

opt_name The name of the excluded option.

Returns: A pointer to this option, for chaining.

Exceptions

cli::incorrect_construction_t If no such option exists.

◆ expected() [1/2]

auto cli::option_t::expected ( int value ) -> option_t *

inline

Sets how many values the option accepts.

A negative value sets a minimum with no maximum. Zero makes the option behave as a flag.

Parameters

value The value count.

Returns: A pointer to this option, for chaining.

◆ expected() [2/2]

auto cli::option_t::expected	(	int	value_min,
		int	value_max ) -> option_t *

inline

Sets the range of value counts the option accepts.

Negative bounds are treated as their magnitude, except that a negative maximum means unbounded. The bounds are swapped if given in the wrong order.

Parameters

value_min	The smallest acceptable count.
value_max	The largest acceptable count.

Returns: A pointer to this option, for chaining.

◆ force_callback()

auto cli::option_t::force_callback ( bool value = true ) -> option_t *

inline

Runs the callback even when the option is absent.

Parameters

value Whether to force the callback.

Returns: A pointer to this option, for chaining.

◆ get_allow_extra_args()

auto cli::option_t::get_allow_extra_args ( ) const -> bool

inlinenodiscard

Reports whether the option absorbs surplus arguments.

Returns: true if surplus arguments are absorbed.

◆ get_callback()

auto cli::option_t::get_callback ( ) const -> const callback_t &

inlinenodiscard

Returns the callback that writes the bound variable.

Returns: The callback.

◆ get_callback_run()

auto cli::option_t::get_callback_run ( ) const -> bool

inlinenodiscard

Reports whether the callback has already run.

Returns: true if the callback has run.

◆ get_default_str()

auto cli::option_t::get_default_str ( ) const -> const std::string &

inlinenodiscard

Returns the default value as shown in help output.

Returns: The rendered default.

◆ get_description()

auto cli::option_t::get_description ( ) const -> const std::string &

inlinenodiscard

Returns the description shown in help output.

Returns: The description.

◆ get_envname()

auto cli::option_t::get_envname ( ) const -> const std::string &

inlinenodiscard

Returns the environment variable consulted when the option is absent.

Returns: The variable name, empty if none is set.

◆ get_excludes()

auto cli::option_t::get_excludes ( ) const -> const std::set< option_t * > &

inlinenodiscard

Returns the options this one excludes.

Returns: The exclusion set.

◆ get_expected()

auto cli::option_t::get_expected ( ) const -> int

inlinenodiscard

Returns the smallest number of values accepted in total.

Returns: The value count.

◆ get_expected_max()

auto cli::option_t::get_expected_max ( ) const -> int

inlinenodiscard

Returns the largest number of values accepted in total.

Returns: The value count.

◆ get_expected_min()

auto cli::option_t::get_expected_min ( ) const -> int

inlinenodiscard

Returns the smallest number of values accepted in total.

Returns: The value count.

◆ get_flag_value()

auto cli::option_t::get_flag_value	(	const std::string &	name,
		std::string	input_value ) const -> std::string

inlinenodiscard

Resolves the value a flag contributes.

With no explicit value the flag's registered default is used. A negated flag inverts whatever was supplied. When overrides are disabled, any value other than the registered one is rejected.

Parameters

name	The flag name as written on the command line.
input_value	The value supplied with it, if any.

Returns: The resolved value.

Exceptions

cli::argument_mismatch_t If an override is supplied but disabled.

◆ get_fnames()

auto cli::option_t::get_fnames ( ) const -> const std::vector< std::string > &

inlinenodiscard

Returns the flag names.

Returns: The flag names.

◆ get_force_callback()

auto cli::option_t::get_force_callback ( ) const -> bool

inlinenodiscard

Reports whether the callback runs when the option is absent.

Returns: true if the callback is forced.

◆ get_inject_separator()

auto cli::option_t::get_inject_separator ( ) const -> bool

inlinenodiscard

Reports whether a separator is inserted between value groups.

Returns: true if a separator is inserted.

◆ get_items_expected()

auto cli::option_t::get_items_expected ( ) const -> int

inlinenodiscard

Returns the smallest total number of items accepted.

Returns: The item count.

◆ get_items_expected_max()

auto cli::option_t::get_items_expected_max ( ) const -> int

inlinenodiscard

Returns the largest total number of items accepted.

Saturates rather than overflowing: if the product does not fit, the unbounded sentinel is reported instead.

Returns: The item count.

◆ get_items_expected_min()

auto cli::option_t::get_items_expected_min ( ) const -> int

inlinenodiscard

Returns the smallest total number of items accepted.

Returns: The item count.

◆ get_lnames()

auto cli::option_t::get_lnames ( ) const -> const std::vector< std::string > &

inlinenodiscard

Returns the long names, without their leading dashes.

Returns: The long names.

◆ get_name()

auto cli::option_t::get_name	(	bool	positional = false,
		bool	all_options = false,
		bool	disable_default_flag_values = false ) const -> std::string

inlinenodiscard

Renders this option's name for help output.

Returns an empty string when the option has no group, since a group-less option is hidden.

Parameters

positional	Prefer the positional name.
all_options	List every name rather than one representative.
disable_default_flag_values	Omit the {value} suffix on flags.

Returns: The rendered name.

◆ get_needs()

auto cli::option_t::get_needs ( ) const -> const std::set< option_t * > &

inlinenodiscard

Returns the options this one depends on.

Returns: The dependency set.

◆ get_option_text()

auto cli::option_t::get_option_text ( ) const -> const std::string &

inlinenodiscard

Returns the text replacing the generated type name.

Returns: The replacement text, empty if none is set.

◆ get_positional()

auto cli::option_t::get_positional ( ) const -> bool

inlinenodiscard

Reports whether this option is a positional.

Returns: true if a positional name is set.

◆ get_run_callback_for_default()

auto cli::option_t::get_run_callback_for_default ( ) const -> bool

inlinenodiscard

Reports whether the callback runs for default values.

Returns: true if the callback runs for defaults.

◆ get_single_name()

auto cli::option_t::get_single_name ( ) const -> const std::string &

inlinenodiscard

Returns one representative name for this option.

Prefers the first long name, then the first short name, then the positional name, then the environment variable name.

Returns: The chosen name.

◆ get_snames()

auto cli::option_t::get_snames ( ) const -> const std::vector< std::string > &

inlinenodiscard

Returns the short names, without their leading dash.

Returns: The short names.

◆ get_trigger_on_parse()

auto cli::option_t::get_trigger_on_parse ( ) const -> bool

inlinenodiscard

Reports whether the callback runs during parsing.

Returns: true if the callback is triggered during parsing.

◆ get_type_name()

auto cli::option_t::get_type_name ( ) const -> std::string

inlinenodiscard

Returns the type name shown in help output.

The generated type name with each validator's description appended, separated by colons.

Returns: The rendered type name.

◆ get_type_size()

auto cli::option_t::get_type_size ( ) const -> int

inlinenodiscard

Returns the smallest number of values one appearance consumes.

Returns: The value count.

◆ get_type_size_max()

auto cli::option_t::get_type_size_max ( ) const -> int

inlinenodiscard

Returns the largest number of values one appearance consumes.

Returns: The value count.

◆ get_type_size_min()

auto cli::option_t::get_type_size_min ( ) const -> int

inlinenodiscard

Returns the smallest number of values one appearance consumes.

Returns: The value count.

◆ get_validator() [1/2]

auto cli::option_t::get_validator ( const std::string & validator_name = "" ) -> validator_t *

inline

Finds a validator by name.

An empty name returns the first validator.

Parameters

validator_name The name to look for.

Returns: A pointer to the validator.

Exceptions

cli::option_not_found_t If no validator matches.

◆ get_validator() [2/2]

auto cli::option_t::get_validator ( int index ) -> validator_t *

inline

Finds a validator by position.

Parameters

index The position to look up.

Returns: A pointer to the validator.

Exceptions

cli::option_not_found_t If index is out of range.

◆ has_description()

auto cli::option_t::has_description ( ) const -> bool

inlinenodiscard

Reports whether a description was set.

Returns: true if the description is not empty.

◆ ignore_case()

template<typename T = app_t>

auto cli::option_t::ignore_case ( bool value = true ) -> option_t *

inline

Makes name matching case-insensitive.

Enabling this can make two previously distinct options collide, so the sibling options are rescanned and the change is rolled back on conflict.

Template Parameters

T	The application type holding the sibling options.

Parameters

value Whether to ignore case.

Returns: A pointer to this option, for chaining.

Exceptions

cli::option_already_added_t If the change causes a name conflict.

◆ ignore_underscore()

template<typename T = app_t>

auto cli::option_t::ignore_underscore ( bool value = true ) -> option_t *

inline

Makes name matching ignore underscores.

Enabling this can make two previously distinct options collide, so the sibling options are rescanned and the change is rolled back on conflict.

Template Parameters

T	The application type holding the sibling options.

Parameters

value Whether to ignore underscores.

Returns: A pointer to this option, for chaining.

Exceptions

cli::option_already_added_t If the change causes a name conflict.

◆ inject_separator()

auto cli::option_t::inject_separator ( bool value = true ) -> void

inline

Sets whether a separator is inserted between value groups.

Parameters

value Whether to insert a separator.

◆ matching_name()

auto cli::option_t::matching_name ( const option_t & other ) const -> const std::string &

inlinenodiscard

Returns the first name this option shares with another.

Two options conflict if any of their names collide. When both are configurable the comparison is looser, because a configuration file does not distinguish short from long names.

Parameters

other The option to compare against.

Returns: The colliding name, or an empty string if there is none.

◆ multi_option_policy()

auto cli::option_t::multi_option_policy ( multi_option_policy_t value = multi_option_policy_t::reject ) -> option_t *

inline

Sets what happens to surplus values.

Moving away from multi_option_policy_t::reject on an unbounded option pins the maximum to the minimum, and resets the parse state so that already-collected results are reduced under the new policy.

Parameters

value The policy to apply.

Returns: A pointer to this option, for chaining.

◆ needs() [1/3]

template<typename A, typename B, typename... args_t>

auto cli::option_t::needs	(	A	opt,
		B	opt1,
		args_t...	args ) -> option_t *

inline

Requires several options to appear alongside this one.

Parameters

opt	The first required option.
opt1	The second required option.
args	Any further required options.

Returns: A pointer to this option, for chaining.

◆ needs() [2/3]

auto cli::option_t::needs ( option_t * opt ) -> option_t *

inline

Requires another option to appear alongside this one.

Self-dependency is ignored rather than reported.

Parameters

opt	The option that must also appear.

Returns: A pointer to this option, for chaining.

◆ needs() [3/3]

template<typename T = app_t>

auto cli::option_t::needs ( std::string opt_name ) -> option_t *

inline

Requires a named option to appear alongside this one.

Template Parameters

T	The application type to look the name up on.

Parameters

opt_name The name of the required option.

Returns: A pointer to this option, for chaining.

Exceptions

cli::incorrect_construction_t If no such option exists.

◆ nonpositional()

auto cli::option_t::nonpositional ( ) const -> bool

inlinenodiscard

Reports whether this option has a dashed name.

Returns: true if a short or long name is set.

◆ operator bool()

cli::option_t::operator bool ( ) const

inlineexplicit

Reports whether the option was used.

Returns: true if values were collected or the callback is forced.

◆ operator==()

auto cli::option_t::operator== ( const option_t & other ) const -> bool

inlinenodiscard

Reports whether two options share a name.

Parameters

other The option to compare against.

Returns: true if any name collides.

◆ option_text()

auto cli::option_t::option_text ( std::string text ) -> option_t *

inline

Replaces the generated type name in help output.

Parameters

text	The replacement text.

Returns: A pointer to this option, for chaining.

◆ reduced_results()

auto cli::option_t::reduced_results ( ) const -> results_t

inlinenodiscard

Returns the results after validation and reduction.

Runs whichever stages have not yet run, without changing the option's recorded state.

Returns: The processed results.

◆ remove_excludes()

auto cli::option_t::remove_excludes ( option_t * opt ) -> bool

inline

Drops an exclusion.

Parameters

opt	The option to stop excluding.

Returns: true if the exclusion was present.

◆ remove_needs()

auto cli::option_t::remove_needs ( option_t * opt ) -> bool

inline

Drops a dependency.

Parameters

opt	The option to stop requiring.

Returns: true if the dependency was present.

◆ results() [1/2]

auto cli::option_t::results ( ) const -> const results_t &

inlinenodiscard

Returns the raw results, before validation or reduction.

Returns: The raw results.

◆ results() [2/2]

template<typename T>

auto cli::option_t::results ( T & output ) const -> void

inline

Converts the results into a value of type T.

Falls back to the printed default when nothing was collected, and to a value-initialised result when there is no default either.

Template Parameters

T	The type to convert to.

Parameters

[out] output The value to fill.

Exceptions

cli::conversion_error_t If the results cannot be converted.

◆ run_callback()

auto cli::option_t::run_callback ( ) -> void

inline

Validates, reduces, and hands the results to the callback.

Advances the option through option_state_t, skipping stages that have already run. When the callback is forced and nothing was collected, the printed default is used and then discarded again.

Exceptions

cli::conversion_error_t If the callback rejects the results.

◆ run_callback_for_default()

auto cli::option_t::run_callback_for_default ( bool value = true ) -> option_t *

inline

Runs the callback when only the default value is present.

Parameters

value Whether to run the callback for defaults.

Returns: A pointer to this option, for chaining.

◆ transform() [1/3]

auto cli::option_t::transform	(	std::function< std::string(std::string)>	transform_func,
		std::string	transform_description = "",
		std::string	transform_name = "" ) -> option_t *

inline

Prepends a callable as a transform.

Parameters

transform_func	Returns the rewritten value.
transform_description	The description shown in help output.
transform_name	A name to find it by later.

Returns: A pointer to this option, for chaining.

◆ transform() [2/3]

auto cli::option_t::transform ( validator_ptr_t validator ) -> option_t *

inline

Prepends a shared validator as a transform.

Parameters

validator The validator to prepend.

Returns: A pointer to this option, for chaining.

◆ transform() [3/3]

auto cli::option_t::transform	(	validator_t	validator,
		const std::string &	transform_name = "" ) -> option_t *

inline

Prepends a validator as a transform.

Parameters

validator	The validator to prepend.
transform_name	A name to find it by later.

Returns: A pointer to this option, for chaining.

◆ trigger_on_parse()

auto cli::option_t::trigger_on_parse ( bool value = true ) -> option_t *

inline

Runs the callback as soon as a value is parsed.

Parameters

value Whether to trigger during parsing.

Returns: A pointer to this option, for chaining.

◆ type_name()

auto cli::option_t::type_name ( std::string typeval ) -> option_t *

inline

Sets a fixed type name for help output.

Parameters

typeval The type name.

Returns: A pointer to this option, for chaining.

◆ type_name_fn()

auto cli::option_t::type_name_fn ( std::function< std::string()> typefun ) -> option_t *

inline

Sets the callable producing the type name shown in help output.

Parameters

typefun Produces the type name.

Returns: A pointer to this option, for chaining.

◆ type_size() [1/2]

auto cli::option_t::type_size ( int option_type_size ) -> option_t *

inline

Sets how many values one appearance consumes.

A negative value fixes the per-appearance count and makes the total unbounded. A count of zero makes the option optional.

Parameters

option_type_size The value count.

Returns: A pointer to this option, for chaining.

◆ type_size() [2/2]

auto cli::option_t::type_size	(	int	option_type_size_min,
		int	option_type_size_max ) -> option_t *

inline

Sets the range of values one appearance may consume.

Negative bounds are treated as their magnitude and make the total unbounded. The bounds are swapped if given in the wrong order.

Parameters

option_type_size_min	The smallest value count.
option_type_size_max	The largest value count.

Returns: A pointer to this option, for chaining.

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

/home/mccakit/desktop/repositories/cli11/src/option.cpp

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ option_state_t

Constructor & Destructor Documentation

◆ option_t()

Member Function Documentation

◆ add_result() [1/3]

◆ add_result() [2/3]

◆ add_result() [3/3]

◆ allow_extra_args()

◆ as()

◆ callback_priority()

◆ capture_default_str()

◆ check() [1/3]

◆ check() [2/3]

◆ check() [3/3]

◆ check_fname()

◆ check_lname()

◆ check_name()

◆ check_sname()

◆ count()

◆ default_function()

◆ default_str()

◆ default_val()

◆ description()

◆ disable_flag_override()

◆ each()

◆ empty()

◆ envname()

◆ excludes() [1/3]

◆ excludes() [2/3]

◆ excludes() [3/3]

◆ expected() [1/2]

◆ expected() [2/2]

◆ force_callback()

◆ get_allow_extra_args()

◆ get_callback()

◆ get_callback_run()

◆ get_default_str()

◆ get_description()

◆ get_envname()

◆ get_excludes()

◆ get_expected()

◆ get_expected_max()

◆ get_expected_min()

◆ get_flag_value()

◆ get_fnames()

◆ get_force_callback()

◆ get_inject_separator()

◆ get_items_expected()

◆ get_items_expected_max()

◆ get_items_expected_min()

◆ get_lnames()

◆ get_name()

◆ get_needs()

◆ get_option_text()

◆ get_positional()

◆ get_run_callback_for_default()

◆ get_single_name()

◆ get_snames()

◆ get_trigger_on_parse()

◆ get_type_name()

◆ get_type_size()

◆ get_type_size_max()

◆ get_type_size_min()

◆ get_validator() [1/2]

◆ get_validator() [2/2]

◆ has_description()

◆ ignore_case()

◆ ignore_underscore()

◆ inject_separator()

◆ matching_name()

◆ multi_option_policy()

◆ needs() [1/3]

◆ needs() [2/3]

◆ needs() [3/3]