Sharg 1.1.2-rc.1
The argument parser for bio-c++ tools.
|
The format that organizes the actual parsing of command line arguments. More...
#include <sharg/detail/format_parse.hpp>
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. | |
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.
|
strongprivate |
Describes the result of parsing the user input string given the respective option value type.
|
inline |
The constructor of the parse format.
[in] | cmd_arguments | The command line arguments to parse. |
|
inline |
Adds a get_flag call to be evaluated later on.
[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. |
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. |
|
inline |
Adds an sharg::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 sharg::validator. |
[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
).
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. |
|
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 sharg::validator. |
[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. |
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
).
|
inlineprivate |
Checks format_parse::arguments for unknown options/flags.
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.
|
inlineprivate |
Checks format_parse::arguments for unknown options/flags.
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.
|
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::arguments.
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 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 =
.
|
inlineprivate |
Returns true and removes the short identifier if it is in format_parse::arguments.
[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::arguments.
[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 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"). |
|
inlineprivate |
Handles command line option retrieval.
[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. |
sharg::option_declared_multiple_times | |
sharg::validation_error | |
sharg::required_option_missing |
This function
|
inlineprivate |
Handles value retrieval (non container type) options.
[out] | value | Stores the value found in arguments, parsed by parse_option_value. |
[in] | id | The option identifier supplied on the command line. |
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.
|
inlineprivate |
Handles value retrieval (container type) options.
[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.
|
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). |
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
|
inlineprivate |
Handles value retrieval for options based on different key-value pairs.
[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. |
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.
|
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 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. |
[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 sharg::istreamable. |
[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 sharg::option_parse_result::success.
|
inlineprivate |
Sets an option value depending on the keys found in sharg::enumeration_names<option_t>.
option_t | Must model sharg::named_enumeration. |
[out] | value | Stores the parsed value. |
[in] | in | The input argument to be parsed. |
sharg::user_input_error | if in is not a key in sharg::enumeration_names<option_t>. |
|
inlineprivate |
Tries to parse an input string into an arithmetic value.
option_t | The option value type; must model std::is_arithmetic_v. |
[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, 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.
|
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. |
sharg::user_input_error | if res was not sharg::option_parse_result::success. |