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

#include <seqan3/argument_parser/detail/format_parse.hpp>

Inheritance diagram for seqan3::detail::format_parse:

Public Member Functions
void	add_flag (bool &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const &spec)
	Adds a get_flag call to be evaluated later on.

template<typename option_type , typename validator_type >
void	add_option (option_type &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const spec, validator_type &&option_validator)
	Adds an seqan3::detail::get_option call to be evaluated later on.

template<typename option_type , typename validator_type >
void	add_positional_option (option_type &value, std::string const &desc, validator_type &&option_validator)
	Adds a get_positional_option call to be evaluated later on.

void	parse (argument_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 (int const, std::vector< std::string > argv_)
	The constructor of the parse format.

Static Public Member Functions
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::argv.

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

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
void	check_for_left_over_args ()
	Checks format_parse::argv for unknown options/flags.

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

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 (char const short_id)
	Returns true and removes the short identifier if it is in format_parse::argv.

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

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_option (option_type &value, char const short_id, std::string const &long_id, option_spec const spec, validator_type &&validator)
	Handles command line option retrieval.

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.

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

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.

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

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 input_stream_over<std::istringstream, 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 seqan3::enumeration_names<option_t>.

template<arithmetic option_t> requires input_stream_over<std::istringstream, 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.

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.

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

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

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

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

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

std::vector< std::function< void()> >	option_calls
	Stores get_option 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.

Additional Inherited Members
Protected Member Functions inherited from seqan3::detail::format_base
std::string	escape_special_xml_chars (std::string const &original)
	Escapes certain characters for correct output.

Static Protected Member Functions inherited from seqan3::detail::format_base
static std::string	expand_multiple_flags (std::string const &flag_cluster)
	Expands multiple one character flag identifiers for pretty help output.

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 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	option_type_and_list_info (container_type const &container)
	Formats the container and its value_type for the help page printing.

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.

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.

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, seqan3::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::argv. 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 Argument Parser

Member Enumeration Documentation

◆ option_parse_result

enum class seqan3::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()

seqan3::detail::format_parse::format_parse	(	int const	,
		std::vector< std::string >	argv_
	)

inline

The constructor of the parse format.

Parameters

[in] argv_ The command line arguments to parse.

Member Function Documentation

◆ add_flag()

void seqan3::detail::format_parse::add_flag	(	bool &	value,
		char const	short_id,
		std::string const &	long_id,
		std::string const &	desc,
		option_spec const &	spec
	)

inline

Adds a get_flag call to be evaluated later on.

Parameters

[in,out]	value	The variable which shows whether 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").
[in]	desc	The description of the flag to be shown in the help page.
[in]	spec	Advanced flag specification, see seqan3::option_spec.

Exceptions

seqan3::design_error if value is true.

◆ add_option()

template<typename option_type , typename validator_type >

void seqan3::detail::format_parse::add_option	(	option_type &	value,
		char const	short_id,
		std::string const &	long_id,
		std::string const &	desc,
		option_spec const	spec,
		validator_type &&	option_validator
	)

inline

Adds an seqan3::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 seqan3::validator.

Parameters

[in,out]	value	The variable in which to store the given command line argument.
[in]	short_id	The short identifier for the option (e.g. 'a').
[in]	long_id	The long identifier for the option (e.g. "age").
[in]	desc	The description of the option to be shown in the help page.
[in]	spec	Advanced option specification, see seqan3::option_spec.
[in]	option_validator	A seqan3::validator that verifies the value after parsing (callable).

Exceptions

seqan3::design_error

◆ add_positional_option()

template<typename option_type , typename validator_type >

void seqan3::detail::format_parse::add_positional_option	(	option_type &	value,
		std::string const &	desc,
		validator_type &&	option_validator
	)

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 seqan3::validator.

Parameters

[in,out]	value	The variable in which to store the given command line argument.
[in]	desc	The description of the positional option to be shown in the help page.
[in]	option_validator	A seqan3::validator that verifies the value after parsing (callable).

Exceptions

seqan3::design_error

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

◆ check_for_left_over_args()

void seqan3::detail::format_parse::check_for_left_over_args ( )

inlineprivate

Checks format_parse::argv for unknown options/flags.

Exceptions

seqan3::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 argv. Thus, all remaining non-empty arguments are too much.

◆ check_for_unknown_ids()

void seqan3::detail::format_parse::check_for_unknown_ids ( )

inlineprivate

Checks format_parse::argv for unknown options/flags.

Exceptions

seqan3::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 argv. Thus, all remaining flags/options are unknown.

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

◆ combine_option_names()

std::string seqan3::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 seqan3::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::argv.

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 argv 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 argv to id prepended with two dashes (--) or a prefix of such followed by the equal sign =.

◆ flag_is_set() [1/2]

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

inlineprivate

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

Parameters

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

◆ flag_is_set() [2/2]

bool seqan3::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::argv.

Parameters

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

◆ get_flag()

void seqan3::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 in which to store the given command line argument.
[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_type >

void seqan3::detail::format_parse::get_option	(	option_type &	value,
		char const	short_id,
		std::string const &	long_id,
		option_spec const	spec,
		validator_type &&	validator
	)

inlineprivate

Handles command line option retrieval.

Parameters

[out]	value	The variable in which to store the given command line argument.
[in]	short_id	The short identifier for the option (e.g. 'i').
[in]	long_id	The long identifier for the option (e.g. "integer").
[in]	spec	Advanced option specification, see seqan3::option_spec.
[in]	validator	The validator applied to the value after parsing (callable).

Exceptions

seqan3::option_declared_multiple_times
seqan3::validation_error
seqan3::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 seqan3::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 argv, parsed by parse_option_value.
[in]	id	The option identifier supplied on the command line.

Exceptions

seqan3::option_declared_multiple_times

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

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 seqan3::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 argv, 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 seqan3::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

seqan3::argument_parser_error
seqan3::too_few_arguments
seqan3::validation_error
seqan3::design_error

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

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 argv

◆ identify_and_retrieve_option_value()

template<typename option_type , typename id_type >

bool seqan3::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 argv, 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

seqan3::too_few_arguments	if the option was not followed by a value.
seqan3::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 seqan3::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 seqan3::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 seqan3::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 seqan3::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 seqan3::option_parse_result whether parsing was successful or not.

◆ parse_option_value() [3/5]

template<typename option_t >
requires input_stream_over<std::istringstream, option_t>

option_parse_result seqan3::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 seqan3::input_stream_over.

Parameters

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

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

◆ parse_option_value() [4/5]

template<named_enumeration option_t>

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

inlineprivate

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

Template Parameters

option_t Must model seqan3::named_enumeration.

Parameters

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

Exceptions

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

Returns: seqan3::option_parse_result::success.

◆ parse_option_value() [5/5]

template<arithmetic option_t>
requires input_stream_over<std::istringstream, option_t>

option_parse_result seqan3::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 seqan3::arithmetic.

Parameters

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

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

This function delegates to std::from_chars.

◆ prepend_dash() [1/2]

static std::string seqan3::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 seqan3::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 seqan3::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

seqan3::user_input_error if res was not seqan3::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()