SeqAn3 3.4.0-rc.1
The Modern C++ library for sequence analysis.
|
The format that organizes the actual parsing of command line arguments. More...
#include <seqan3/argument_parser/detail/format_parse.hpp>
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. | |
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.
|
strongprivate |
Describes the result of parsing the user input string given the respective option value type.
|
inline |
The constructor of the parse format.
[in] | argv_ | The command line arguments to parse. |
|
inline |
Adds a get_flag call to be evaluated later on.
[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. |
seqan3::design_error | if value is true. |
|
inline |
Adds an seqan3::detail::get_option call to be evaluated later on.
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. |
[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). |
seqan3::design_error |
|
inline |
Adds a get_positional_option call to be evaluated later on.
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. |
[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). |
seqan3::design_error |
The validator must be applicable to the given output variable (value
).
|
inlineprivate |
Checks format_parse::argv for unknown options/flags.
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.
|
inlineprivate |
Checks format_parse::argv for unknown options/flags.
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.
|
inlineprivate |
Returns "-[short_id]/--[long_id]" if both are non-empty or just one of them if the other is empty.
[in] | short_id | The name of the short identifier. |
[in] | long_id | The name of the long identifier. |
|
inlinestatic |
Finds the position of a short/long identifier in format_parse::argv.
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. |
[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). |
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 =
.
|
inlineprivate |
Returns true and removes the short identifier if it is in format_parse::argv.
[in] | short_id | The short identifier of the flag to check. |
|
inlineprivate |
Returns true and removes the long identifier if it is in format_parse::argv.
[in] | long_id | The long identifier of the flag to check. |
|
inlineprivate |
Handles command line flags, whether they are set or not.
[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"). |
|
inlineprivate |
Handles command line option retrieval.
[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). |
seqan3::option_declared_multiple_times | |
seqan3::validation_error | |
seqan3::required_option_missing |
This function
|
inlineprivate |
Handles value retrieval (non container type) options.
[out] | value | Stores the value found in argv, parsed by parse_option_value. |
[in] | id | The option identifier supplied on the command line. |
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.
|
inlineprivate |
Handles value retrieval (container type) options.
[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.
|
inlineprivate |
Handles command line positional option retrieval.
[out] | value | The variable in which to store the given command line argument. |
[in] | validator | The validator applied to the value after parsing (callable). |
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
|
inlineprivate |
Handles value retrieval for options based on different key-value pairs.
[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. |
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.
|
inlineprivate |
Tries to parse an input string into a boolean value.
[out] | value | Stores the parsed value. |
[in] | in | The input argument to be parsed. |
This function accepts the strings "0" or "false" which sets sets value
to false
or "1" or "true" which sets value
to true
.
|
inlineprivate |
Parses the given option value and appends it to the target container.
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. |
[out] | value | The container that stores the parsed value. |
[in] | in | The input argument to be parsed. |
|
inlineprivate |
Tries to parse an input string into a value using the stream operator>>
.
option_t | Must model seqan3::input_stream_over. |
[out] | value | Stores the parsed value. |
[in] | in | The input argument to be parsed. |
in
could not be parsed via the stream operator and otherwise seqan3::option_parse_result::success.
|
inlineprivate |
Sets an option value depending on the keys found in seqan3::enumeration_names<option_t>.
option_t | Must model seqan3::named_enumeration. |
[out] | value | Stores the parsed value. |
[in] | in | The input argument to be parsed. |
seqan3::user_input_error | if in is not a key in seqan3::enumeration_names<option_t>. |
|
inlineprivate |
Tries to parse an input string into an arithmetic value.
option_t | The option value type; must model seqan3::arithmetic. |
[out] | value | Stores the parsed value. |
[in] | in | The input argument to be parsed. |
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.
|
inlinestaticprivate |
Appends a double dash to a short identifier and returns it.
[in] | short_id | The name of the short identifier. |
|
inlinestaticprivate |
Appends a double dash to a long identifier and returns it.
[in] | long_id | The name of the long identifier. |
|
inlineprivate |
Tries to parse an input string into boolean value.
[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. |
seqan3::user_input_error | if res was not seqan3::option_parse_result::success. |