The format that organizes the actual parsing of command line arguments. More...

#include <sharg/detail/format_parse.hpp>

Inheritance diagram for sharg::detail::format_parse:

Public Member Functions
template<typename option_type , typename validator_t >
void	add_option (option_type &value, config< validator_t > const &config)
	Adds an sharg::detail::get_option call to be evaluated later on.

template<typename validator_t >
void	add_flag (bool &value, config< validator_t > const &config)
	Adds a get_flag call to be evaluated later on.

template<typename option_type , typename validator_t >
void	add_positional_option (option_type &value, config< validator_t > const &config)
	Adds a get_positional_option call to be evaluated later on.

void	parse (parser_meta_data const &)
	Initiates the actual command line parsing.

Constructors, destructor and assignment
	format_parse ()=delete
	Deleted.

	format_parse (format_parse const &pf)=default
	Defaulted.

format_parse &	operator= (format_parse const &pf)=default
	Defaulted.

	format_parse (format_parse &&)=default
	Defaulted.

format_parse &	operator= (format_parse &&)=default
	Defaulted.

	~format_parse ()=default
	Defaulted.

	format_parse (std::vector< std::string > cmd_arguments)
	The constructor of the parse format.

Static Public Member Functions
template<typename id_type >
static bool	is_empty_id (id_type const &id)
	Checks whether `id` is empty.

template<typename iterator_type , typename id_type >
static iterator_type	find_option_id (iterator_type begin_it, iterator_type end_it, id_type const &id)
	Finds the position of a short/long identifier in format_parse::arguments.

Private Types
enum class	option_parse_result { success , error , overflow_error }
	Describes the result of parsing the user input string given the respective option value type. More...

Private Member Functions
std::string	combine_option_names (char const short_id, std::string const &long_id)
	Returns "-[short_id]/--[long_id]" if both are non-empty or just one of them if the other is empty.

bool	flag_is_set (std::string const &long_id)
	Returns true and removes the long identifier if it is in format_parse::arguments.

bool	flag_is_set (char const short_id)
	Returns true and removes the short identifier if it is in format_parse::arguments.

template<typename option_t > requires istreamable<option_t>
option_parse_result	parse_option_value (option_t &value, std::string const &in)
	Tries to parse an input string into a value using the stream `operator>>`.

template<named_enumeration option_t>
option_parse_result	parse_option_value (option_t &value, std::string const &in)
	Sets an option value depending on the keys found in sharg::enumeration_names<option_t>.

template<detail::is_container_option container_option_t, typename format_parse_t = format_parse> requires requires (format_parse_t fp, typename container_option_t::value_type & container_value, std::string const & in) { {fp.parse_option_value(container_value, in)} -> std::same_as<option_parse_result>; }
option_parse_result	parse_option_value (container_option_t &value, std::string const &in)
	Parses the given option value and appends it to the target container.

template<typename option_t > requires std::is_arithmetic_v<option_t> && istreamable<option_t>
option_parse_result	parse_option_value (option_t &value, std::string const &in)
	Tries to parse an input string into an arithmetic value.

option_parse_result	parse_option_value (bool &value, std::string const &in)
	Tries to parse an input string into a boolean value.

template<typename option_type >
void	throw_on_input_error (option_parse_result const res, std::string const &option_name, std::string const &input_value)
	Tries to parse an input string into boolean value.

template<typename option_type , typename id_type >
bool	identify_and_retrieve_option_value (option_type &value, std::vector< std::string >::iterator &option_it, id_type const &id)
	Handles value retrieval for options based on different key-value pairs.

template<typename option_type , typename id_type >
bool	get_option_by_id (option_type &value, id_type const &id)
	Handles value retrieval (non container type) options.

template<detail::is_container_option option_type, typename id_type >
bool	get_option_by_id (option_type &value, id_type const &id)
	Handles value retrieval (container type) options.

void	check_for_unknown_ids ()
	Checks format_parse::arguments for unknown options/flags.

void	check_for_left_over_args ()
	Checks format_parse::arguments for unknown options/flags.

template<typename option_type , typename validator_t >
void	get_option (option_type &value, config< validator_t > const &config)
	Handles command line option retrieval.

void	get_flag (bool &value, char const short_id, std::string const &long_id)
	Handles command line flags, whether they are set or not.

template<typename option_type , typename validator_type >
void	get_positional_option (option_type &value, validator_type &&validator)
	Handles command line positional option retrieval.

Static Private Member Functions
static std::string	prepend_dash (std::string const &long_id)
	Appends a double dash to a long identifier and returns it.

static std::string	prepend_dash (char const short_id)
	Appends a double dash to a short identifier and returns it.

Private Attributes
std::vector< std::function< void()> >	option_calls
	Stores get_option calls to be evaluated when calling format_parse::parse().

std::vector< std::function< void()> >	flag_calls
	Stores get_flag calls to be evaluated when calling format_parse::parse().

std::vector< std::function< void()> >	positional_option_calls
	Stores get_positional_option calls to be evaluated when calling format_parse::parse().

unsigned	positional_option_count {0}
	Keeps track of the number of specified positional options.

std::vector< std::string >	arguments
	Vector of command line arguments.

std::vector< std::string >::iterator	end_of_options_it
	Artificial end of arguments if -- was seen.

Additional Inherited Members
Static Protected Member Functions inherited from sharg::detail::format_base
template<typename value_type >
static std::string	get_type_name_as_string (value_type const &)
	Returns the input type as a string (reflection).

template<detail::is_container_option container_type>
static std::string	get_type_name_as_string (container_type const &)
	Returns the `value_type` of the input container as a string (reflection).

template<typename option_value_type >
static std::string	option_type_and_list_info (option_value_type const &value)
	Formats the type of a value for the help page printing.

template<detail::is_container_option container_type>
static std::string	option_type_and_list_info (container_type const &container)
	Formats the container and its value_type for the help page printing.

static std::string	prep_id_for_help (char const short_id, std::string const &long_id)
	Formats the option/flag identifier pair for the help page printing.

static std::string	escape_special_xml_chars (std::string const &original)
	Escapes certain characters for correct output.

static std::string	expand_multiple_flags (std::string const &flag_cluster)
	Expands multiple one character flag identifiers for pretty help output.

template<typename option_type , typename default_type >
static std::string	get_default_message (option_type const &option, default_type const &value)
	Returns the default message for the help page.

Detailed Description

The format that organizes the actual parsing of command line arguments.

In order to be independent of the options value type, we do not want to store parameters/options/flags/.. directly (though a variant might work, it is hacky). Directly parsing is also difficult, since the order of parsing options/flags is non trivial (e.g. ambiguousness of '-g 4' => option+value or flag+positional). Therefore, we store the parsing calls of the developer in a function object, (format_parse::option_and_flag_calls, sharg::detail::format_parse::positional_option_calls) executing them in a new order when calling format_parse::parse(). This enables us to parse any option type and resolve any ambiguousness, so no additional restrictions apply to the developer when setting up the parser.

Order of parsing: -#. Options (order within as specified by the developer) -#. Flags (order within as specified by the developer) -#. Positional Options (order within as specified by the developer)

When parsing flags and options, the identifiers (and values) are removed from the vector format_parse::arguments. That way, options that are specified multiple times, but are no container type, can be identified and an error is reported.

Remarks: For a complete overview, take a look at Parser

Member Enumeration Documentation

◆ option_parse_result

enum class sharg::detail::format_parse::option_parse_result

strongprivate

Describes the result of parsing the user input string given the respective option value type.

Enumerator
success	Parsing of user input was successful.
error	There was some error while trying to parse the user input.
overflow_error	Parsing was successful but the arithmetic value would cause an overflow.

Constructor & Destructor Documentation

◆ format_parse()

sharg::detail::format_parse::format_parse ( std::vector< std::string > cmd_arguments )

inline

The constructor of the parse format.

Parameters

[in] cmd_arguments The command line arguments to parse.

Member Function Documentation

◆ add_flag()

template<typename validator_t >

void sharg::detail::format_parse::add_flag	(	bool &	value,
		config< validator_t > const &	config )

inline

Adds a get_flag call to be evaluated later on.

Parameters

[in,out]	value	The variable which shows if the flag is turned off (default) or on.
[in]	config	A configuration object to customise the sharg::parser behaviour. See sharg::config.

Exceptions

sharg::design_error	if sharg::parser::parse was already called.
sharg::design_error	if `value` is true.
sharg::design_error	if the option identifier was already used.
sharg::design_error	if the option identifier is not a valid identifier.

This entity is stable. Since version 1.0.

◆ add_option()

template<typename option_type , typename validator_t >

void sharg::detail::format_parse::add_option	(	option_type &	value,
		config< validator_t > const &	config )

inline

Adds an sharg::detail::get_option call to be evaluated later on.

Template Parameters

option_type	Must have a formatted input function (stream >> value). If option_type is a container, its value type must have the formatted input function (exception: std::string is not regarded as a container). See FormattedInputFunction .
validator_type	The type of validator to be applied to the option value. Must model sharg::validator.

Parameters

[in,out]	value	The variable in which to store the given command line argument.
[in]	config	A configuration object to customise the sharg::parser behaviour. See sharg::config.

The config.validator must be applicable to the given output variable (value).

Exceptions

sharg::design_error	if sharg::parser::parse was already called.
sharg::design_error	if the option is required and has a default_message.
sharg::design_error	if the option identifier was already used.
sharg::design_error	if the option identifier is not a valid identifier.

This entity is stable. Since version 1.0.

◆ add_positional_option()

template<typename option_type , typename validator_t >

void sharg::detail::format_parse::add_positional_option	(	option_type &	value,
		config< validator_t > const &	config )

inline

Adds a get_positional_option call to be evaluated later on.

Template Parameters

option_type	Must have a formatted input function (stream >> value). If option_type is a container, its value type must have the formatted input function (exception: std::string is not regarded as a container). See FormattedInputFunction .
validator_type	The type of validator to be applied to the option value. Must model sharg::validator.

Parameters

[in,out]	value	The variable in which to store the given command line argument.
[in]	config	Customise the sharg::parser behaviour. See sharg::positional_config.

Exceptions

sharg::design_error	if sharg::parser::parse was already called.
sharg::design_error	if the option has a short or long identifier.
sharg::design_error	if the option is advanced or hidden.
sharg::design_error	if the option has a default_message.
sharg::design_error	if there already is a positional list option.
sharg::design_error	if there are subcommands.

The config.validator must be applicable to the given output variable (value).

This entity is stable. Since version 1.0.

◆ check_for_left_over_args()

void sharg::detail::format_parse::check_for_left_over_args ( )

inlineprivate

Checks format_parse::arguments for unknown options/flags.

Exceptions

sharg::too_many_arguments

This function is used by format_parse::parse() AFTER all flags, options and positional options specified by the developer were parsed and therefore removed from arguments. Thus, all remaining non-empty arguments are too much.

◆ check_for_unknown_ids()

void sharg::detail::format_parse::check_for_unknown_ids ( )

inlineprivate

Checks format_parse::arguments for unknown options/flags.

Exceptions

sharg::unknown_option

This function is used by format_parse::parse() AFTER all flags and options specified by the developer were parsed and therefore removed from arguments. Thus, all remaining flags/options are unknown.

In addition this function removes "--" (if specified) from arguments to clean arguments for positional option retrieval.

◆ combine_option_names()

std::string sharg::detail::format_parse::combine_option_names	(	char const	short_id,
		std::string const &	long_id )

inlineprivate

Returns "-[short_id]/--[long_id]" if both are non-empty or just one of them if the other is empty.

Parameters

[in]	short_id	The name of the short identifier.
[in]	long_id	The name of the long identifier.

Returns: The short_id prepended with a single dash and the long_id prepended with a double dash, separated by '/'.

◆ find_option_id()

template<typename iterator_type , typename id_type >

static iterator_type sharg::detail::format_parse::find_option_id	(	iterator_type	begin_it,
		iterator_type	end_it,
		id_type const &	id )

inlinestatic

Finds the position of a short/long identifier in format_parse::arguments.

Template Parameters

iterator_type	The type of iterator that defines the range to search in.
id_type	The identifier type; must be either of type `char` if it denotes a short identifier or std::string if it denotes a long identifier.

Parameters

[in]	begin_it	The iterator where to start the search of the identifier.
[in]	end_it	The iterator one past the end of where to search the identifier.
[in]	id	The identifier to search for (must not contain dashes).

Returns: An iterator pointing to the first occurrence of id in the list pointed to by begin_it or end_it if it is not contained.

Valid short-id value pairs are: -iValue, -i=Value, or -i Value If the id passed to this function is of type char, it is assumed to be a short identifier. The id is found by comparing the prefix of every argument in arguments to the id prepended with a single -.

Valid long id value pairs are: --id=Value, --id Value. If the id passed to this function is of type std::string, it is assumed to be a long identifier. The id is found by comparing every argument in arguments to id prepended with two dashes (--) or a prefix of such followed by the equal sign =.

◆ flag_is_set() [1/2]

bool sharg::detail::format_parse::flag_is_set ( char const short_id )

inlineprivate

Returns true and removes the short identifier if it is in format_parse::arguments.

Parameters

[in] short_id The short identifier of the flag to check.

◆ flag_is_set() [2/2]

bool sharg::detail::format_parse::flag_is_set ( std::string const & long_id )

inlineprivate

Returns true and removes the long identifier if it is in format_parse::arguments.

Parameters

[in] long_id The long identifier of the flag to check.

◆ get_flag()

void sharg::detail::format_parse::get_flag	(	bool &	value,
		char const	short_id,
		std::string const &	long_id )

inlineprivate

Handles command line flags, whether they are set or not.

Parameters

[out]	value	The variable which shows if the flag is turned off (default) or on.
[in]	short_id	The short identifier for the flag (e.g. 'i').
[in]	long_id	The long identifier for the flag (e.g. "integer").

◆ get_option()

template<typename option_type , typename validator_t >

void sharg::detail::format_parse::get_option	(	option_type &	value,
		config< validator_t > const &	config )

inlineprivate

Handles command line option retrieval.

Parameters

[out]	value	The variable in which to store the given command line argument.
[in]	config	A configuration object to customise the sharg::parser behaviour. See sharg::config.

Exceptions

sharg::option_declared_multiple_times
sharg::validation_error
sharg::required_option_missing

This function

checks if the option is required but not set,
retrieves any value found by the short or long identifier,
throws on (mis)use of both identifiers for non-container type values,
re-throws the validation exception with appended option information.

◆ get_option_by_id() [1/2]

template<typename option_type , typename id_type >

bool sharg::detail::format_parse::get_option_by_id	(	option_type &	value,
		id_type const &	id )

inlineprivate

Handles value retrieval (non container type) options.

Parameters

[out]	value	Stores the value found in arguments, parsed by parse_option_value.
[in]	id	The option identifier supplied on the command line.

Exceptions

sharg::option_declared_multiple_times

If the option identifier is found in format_parse::arguments, the value of the following position in arguments is tried to be parsed given the respective option value type and the identifier and value argument are removed from arguments.

Returns true on success and false otherwise. This is needed to catch the user error of supplying multiple arguments for the same (non container!) option by specifying the short AND long identifier.

◆ get_option_by_id() [2/2]

template<detail::is_container_option option_type, typename id_type >

bool sharg::detail::format_parse::get_option_by_id	(	option_type &	value,
		id_type const &	id )

inlineprivate

Handles value retrieval (container type) options.

Parameters

[out]	value	Stores all values found in arguments, parsed by parse_option_value.
[in]	id	The option identifier supplied on the command line.

Since option_type is a container, the option is a list and can be parsed multiple times.

◆ get_positional_option()

template<typename option_type , typename validator_type >

void sharg::detail::format_parse::get_positional_option	(	option_type &	value,
		validator_type &&	validator )

inlineprivate

Handles command line positional option retrieval.

Parameters

[out]	value	The variable in which to store the given command line argument.
[in]	validator	The validator applied to the value after parsing (callable).

Exceptions

sharg::parser_error
sharg::too_few_arguments
sharg::validation_error
sharg::design_error

This function assumes that -#) arguments has been stripped from all known options and flags -#) arguments has been checked for unknown options -#) arguments does not contain "--" anymore Thus we can simply iterate over non empty entries of arguments.

This function

checks if the user did not provide enough arguments,
retrieves the next (no container type) or all (container type) remaining non empty value/s in arguments

◆ identify_and_retrieve_option_value()

template<typename option_type , typename id_type >

bool sharg::detail::format_parse::identify_and_retrieve_option_value	(	option_type &	value,
		std::vector< std::string >::iterator &	option_it,
		id_type const &	id )

inlineprivate

Handles value retrieval for options based on different key-value pairs.

Parameters

[out]	value	Stores the value found in arguments, parsed by parse_option_value.
[in]	option_it	The iterator where the option identifier was found.
[in]	id	The option identifier supplied on the command line.

Exceptions

sharg::too_few_arguments	if the option was not followed by a value.
sharg::user_input_error	if the given option value was invalid.

The value at option_it is inspected whether it is an '-key value', '-key=value' or '-keyValue' pair and the input is extracted accordingly. The input will then be tried to be parsed into the value parameter.

Returns true on success and false otherwise.

◆ parse_option_value() [1/5]

option_parse_result sharg::detail::format_parse::parse_option_value	(	bool &	value,
		std::string const &	in )

inlineprivate

Tries to parse an input string into a boolean value.

Parameters

[out]	value	Stores the parsed value.
[in]	in	The input argument to be parsed.

Returns: A sharg::option_parse_result whether parsing was successful or not.

This function accepts the strings "0" or "false" which sets sets value to false or "1" or "true" which sets value to true.

◆ parse_option_value() [2/5]

template<detail::is_container_option container_option_t, typename format_parse_t = format_parse>
requires requires (format_parse_t fp, typename container_option_t::value_type & container_value, std::string const & in) { {fp.parse_option_value(container_value, in)} -> std::same_as<option_parse_result>; }

option_parse_result sharg::detail::format_parse::parse_option_value	(	container_option_t &	value,
		std::string const &	in )

inlineprivate

Parses the given option value and appends it to the target container.

Template Parameters

container_option_t	Must model sharg::detail::is_container_option and its value_type must be parseable via parse_option_value
format_parse_t	Needed to make the function "dependent" (i.e. do instantiation in the second phase of two-phase lookup) as the requires clause needs to be able to access the other parse_option_value overloads.

Parameters

[out]	value	The container that stores the parsed value.
[in]	in	The input argument to be parsed.

Returns: A sharg::option_parse_result whether parsing was successful or not.

◆ parse_option_value() [3/5]

template<typename option_t >
requires istreamable<option_t>

option_parse_result sharg::detail::format_parse::parse_option_value	(	option_t &	value,
		std::string const &	in )

inlineprivate

Tries to parse an input string into a value using the stream operator>>.

Template Parameters

option_t Must model sharg::istreamable.

Parameters

[out]	value	Stores the parsed value.
[in]	in	The input argument to be parsed.

Returns: sharg::option_parse_result::error if in could not be parsed via the stream operator and otherwise sharg::option_parse_result::success.

◆ parse_option_value() [4/5]

template<named_enumeration option_t>

option_parse_result sharg::detail::format_parse::parse_option_value	(	option_t &	value,
		std::string const &	in )

inlineprivate

Sets an option value depending on the keys found in sharg::enumeration_names<option_t>.

Template Parameters

option_t Must model sharg::named_enumeration.

Parameters

[out]	value	Stores the parsed value.
[in]	in	The input argument to be parsed.

Exceptions

sharg::user_input_error if in is not a key in sharg::enumeration_names<option_t>.

Returns: sharg::option_parse_result::success.

◆ parse_option_value() [5/5]

template<typename option_t >
requires std::is_arithmetic_v<option_t> && istreamable<option_t>

option_parse_result sharg::detail::format_parse::parse_option_value	(	option_t &	value,
		std::string const &	in )

inlineprivate

Tries to parse an input string into an arithmetic value.

Template Parameters

option_t The option value type; must model std::is_arithmetic_v.

Parameters

[out]	value	Stores the parsed value.
[in]	in	The input argument to be parsed.

Returns: sharg::option_parse_result::error if in could not be parsed to an arithmetic type via std::from_chars, sharg::option_parse_result::overflow_error if in could be parsed but the value is too large for the respective type, and otherwise sharg::option_parse_result::success.

This function delegates to std::from_chars.

◆ prepend_dash() [1/2]

static std::string sharg::detail::format_parse::prepend_dash ( char const short_id )

inlinestaticprivate

Appends a double dash to a short identifier and returns it.

Parameters

[in] short_id The name of the short identifier.

Returns: The input short name prepended with a single dash.

◆ prepend_dash() [2/2]

static std::string sharg::detail::format_parse::prepend_dash ( std::string const & long_id )

inlinestaticprivate

Appends a double dash to a long identifier and returns it.

Parameters

[in] long_id The name of the long identifier.

Returns: The input long name prepended with a double dash.

◆ throw_on_input_error()

template<typename option_type >

void sharg::detail::format_parse::throw_on_input_error	(	option_parse_result const	res,
		std::string const &	option_name,
		std::string const &	input_value )

inlineprivate

Tries to parse an input string into boolean value.

Parameters

[in]	res	A result value of parsing an input string to the respective option value type.
[in]	option_name	The name of the option whose input was parsed.
[in]	input_value	The original user input in question.

Exceptions

sharg::user_input_error if res was not sharg::option_parse_result::success.

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

format_parse.hpp

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ option_parse_result

Constructor & Destructor Documentation

◆ format_parse()

Member Function Documentation

◆ add_flag()

◆ add_option()

◆ add_positional_option()

◆ check_for_left_over_args()

◆ check_for_unknown_ids()

◆ combine_option_names()

◆ find_option_id()

◆ flag_is_set() [1/2]

◆ flag_is_set() [2/2]

◆ get_flag()

◆ get_option()

◆ get_option_by_id() [1/2]

◆ get_option_by_id() [2/2]

◆ get_positional_option()

◆ identify_and_retrieve_option_value()

◆ parse_option_value() [1/5]

◆ parse_option_value() [2/5]

◆ parse_option_value() [3/5]

◆ parse_option_value() [4/5]

◆ parse_option_value() [5/5]

◆ prepend_dash() [1/2]

◆ prepend_dash() [2/2]

◆ throw_on_input_error()