Sharg 1.1.2-rc.1
The argument parser for bio-c++ tools.
Loading...
Searching...
No Matches
sharg::detail::format_parse Class Reference

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_parseoperator= (format_parse const &pf)=default
 Defaulted.
 
 format_parse (format_parse &&)=default
 Defaulted.
 
format_parseoperator= (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::stringarguments
 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

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_argumentsThe 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]valueThe variable which shows if the flag is turned off (default) or on.
[in]configA configuration object to customise the sharg::parser behaviour. See sharg::config.
Exceptions
sharg::design_errorif sharg::parser::parse was already called.
sharg::design_errorif value is true.
sharg::design_errorif the option identifier was already used.
sharg::design_errorif 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_typeMust 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_typeThe type of validator to be applied to the option value. Must model sharg::validator.
Parameters
[in,out]valueThe variable in which to store the given command line argument.
[in]configA 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_errorif sharg::parser::parse was already called.
sharg::design_errorif the option is required and has a default_message.
sharg::design_errorif the option identifier was already used.
sharg::design_errorif 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_typeMust 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_typeThe type of validator to be applied to the option value. Must model sharg::validator.
Parameters
[in,out]valueThe variable in which to store the given command line argument.
[in]configCustomise the sharg::parser behaviour. See sharg::positional_config.
Exceptions
sharg::design_errorif sharg::parser::parse was already called.
sharg::design_errorif the option has a short or long identifier.
sharg::design_errorif the option is advanced or hidden.
sharg::design_errorif the option has a default_message.
sharg::design_errorif there already is a positional list option.
sharg::design_errorif 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_idThe name of the short identifier.
[in]long_idThe 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_typeThe type of iterator that defines the range to search in.
id_typeThe 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_itThe iterator where to start the search of the identifier.
[in]end_itThe iterator one past the end of where to search the identifier.
[in]idThe 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_idThe 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_idThe 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]valueThe variable which shows if the flag is turned off (default) or on.
[in]short_idThe short identifier for the flag (e.g. 'i').
[in]long_idThe 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]valueThe variable in which to store the given command line argument.
[in]configA 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]valueStores the value found in arguments, parsed by parse_option_value.
[in]idThe 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]valueStores all values found in arguments, parsed by parse_option_value.
[in]idThe 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]valueThe variable in which to store the given command line argument.
[in]validatorThe 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]valueStores the value found in arguments, parsed by parse_option_value.
[in]option_itThe iterator where the option identifier was found.
[in]idThe option identifier supplied on the command line.
Exceptions
sharg::too_few_argumentsif the option was not followed by a value.
sharg::user_input_errorif 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]valueStores the parsed value.
[in]inThe 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_tMust model sharg::detail::is_container_option and its value_type must be parseable via parse_option_value
format_parse_tNeeded 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]valueThe container that stores the parsed value.
[in]inThe 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_tMust model sharg::istreamable.
Parameters
[out]valueStores the parsed value.
[in]inThe 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_tMust model sharg::named_enumeration.
Parameters
[out]valueStores the parsed value.
[in]inThe input argument to be parsed.
Exceptions
sharg::user_input_errorif 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_tThe option value type; must model std::is_arithmetic_v.
Parameters
[out]valueStores the parsed value.
[in]inThe 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_idThe 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_idThe 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]resA result value of parsing an input string to the respective option value type.
[in]option_nameThe name of the option whose input was parsed.
[in]input_valueThe original user input in question.
Exceptions
sharg::user_input_errorif res was not sharg::option_parse_result::success.

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