Sharg 1.1.2-rc.1
The argument parser for bio-c++ tools.
|
The Sharg command line parser. More...
#include <sharg/parser.hpp>
Public Member Functions | |
void | parse () |
Initiates the actual command line parsing. | |
parser & | get_sub_parser () |
Returns a reference to the sub-parser instance if subcommand parsing was enabled. | |
template<typename id_type > requires std::same_as<id_type, char> || std::constructible_from<std::string, id_type> | |
bool | is_option_set (id_type const &id) const |
Checks whether the option identifier (id ) was set on the command line by the user. | |
Constructors, destructor and assignment | |
parser ()=delete | |
Deleted. | |
parser (parser const &)=delete | |
Deleted. | |
parser & | operator= (parser const &)=delete |
Deleted. | |
parser (parser &&)=default | |
Defaulted. | |
parser & | operator= (parser &&)=default |
Defaulted. | |
parser (std::string const &app_name, std::vector< std::string > const &arguments, update_notifications version_updates=update_notifications::on, std::vector< std::string > subcommands={}) | |
Initializes an sharg::parser object from the command line arguments. | |
parser (std::string const &app_name, int const argc, char const *const *const argv, update_notifications version_updates=update_notifications::on, std::vector< std::string > subcommands={}) | |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
~parser () | |
The destructor. | |
Adding options | |
Add (positional) options and flags to the parser. | |
template<typename option_type , typename validator_type > requires (parsable<option_type> || parsable<std::ranges::range_value_t<option_type>>) && std::invocable<validator_type, option_type> | |
void | add_option (option_type &value, config< validator_type > const &config) |
Adds an option to the sharg::parser. | |
template<typename validator_type > requires std::invocable<validator_type, bool> | |
void | add_flag (bool &value, config< validator_type > const &config) |
Adds a flag to the sharg::parser. | |
template<typename option_type , typename validator_type > requires (parsable<option_type> || parsable<std::ranges::range_value_t<option_type>>) && std::invocable<validator_type, option_type> | |
void | add_positional_option (option_type &value, config< validator_type > const &config) |
Adds a positional option to the sharg::parser. | |
Structuring the Help Page | |
void | add_section (std::string const &title, bool const advanced_only=false) |
Adds an help page section to the sharg::parser. | |
void | add_subsection (std::string const &title, bool const advanced_only=false) |
Adds an help page subsection to the sharg::parser. | |
void | add_line (std::string const &text, bool is_paragraph=false, bool const advanced_only=false) |
Adds an help page text line to the sharg::parser. | |
void | add_list_item (std::string const &key, std::string const &desc, bool const advanced_only=false) |
Adds an help page list item (key-value) to the sharg::parser. | |
void | add_subcommands (std::vector< std::string > const &subcommands) |
Adds subcommands to the parser. | |
Public Attributes | |
parser_meta_data | info |
Aggregates all parser related meta data (see sharg::parser_meta_data struct). | |
Private Member Functions | |
void | determine_format_and_subcommand () |
Handles format and subcommand detection. | |
template<typename id_type > | |
bool | id_exists (id_type const &id) |
Checks whether the long identifier has already been used before. | |
void | verify_identifiers (char const short_id, std::string const &long_id) |
Verifies that the short and the long identifiers are correctly formatted. | |
template<typename validator_t > | |
void | verify_option_config (config< validator_t > const &config) |
brief Verify the configuration given to a sharg::parser::add_option call. | |
template<typename validator_t > | |
void | verify_flag_config (config< validator_t > const &config) |
brief Verify the configuration given to a sharg::parser::add_flag call. | |
template<typename validator_t > | |
void | verify_positional_option_config (config< validator_t > const &config) const |
brief Verify the configuration given to a sharg::parser::add_positional_option call. | |
void | check_parse_not_called (std::string_view const function_name) const |
Throws a sharg::design_error if parse() was already called. | |
void | verify_app_and_subcommand_names () const |
Verifies that the app and subcommand names are correctly formatted. | |
void | run_version_check () |
Runs the version check if the user has not disabled it. | |
void | parse_format () |
Parses the command line arguments according to the format. | |
Private Attributes | |
bool | parse_was_called {false} |
Keeps track of whether the parse function has been called already. | |
bool | has_positional_list_option {false} |
Keeps track of whether the user has added a positional list option to check if this was the very last. | |
update_notifications | version_check_dev_decision {} |
Set on construction and indicates whether the developer deactivates the version check calls completely. | |
std::optional< bool > | version_check_user_decision |
Whether the user specified to perform the version check (true) or not (false), default unset. | |
std::future< bool > | version_check_future |
The future object that keeps track of the detached version check call thread. | |
std::regex | app_name_regex {"^[a-zA-Z0-9_-]+$"} |
Validates the application name to ensure an escaped server call. | |
std::unique_ptr< parser > | sub_parser {nullptr} |
Stores the sub-parser in case subcommand parsing is enabled. | |
std::vector< std::string > | subcommands {} |
Stores the sub-parser names in case subcommand parsing is enabled. | |
std::variant< detail::format_parse, detail::format_help, detail::format_short_help, detail::format_version, detail::format_html, detail::format_man, detail::format_tdl, detail::format_copyright > | format {detail::format_short_help{}} |
The format of the parser that decides the behavior when calling the sharg::parser::parse function. | |
std::unordered_set< std::string > | used_ids {"h", "hh", "help", "advanced-help", "export-help", "version", "copyright"} |
List of option/flag identifiers (excluding -/–) that are already used. | |
std::vector< std::string > | format_arguments {} |
The command line arguments that will be passed to the format. | |
std::vector< std::string > | arguments {} |
The original command line arguments. | |
std::vector< std::string > | executable_name {} |
The command that lead to calling this parser, e.g. [./build/bin/raptor, build]. | |
std::unordered_set< std::string > | options {} |
Set of option identifiers (including -/–) that have been added via add_option . | |
std::vector< std::function< void()> > | operations |
Vector of functions that stores all calls. | |
Static Private Attributes | |
static constexpr std::string_view const | option_end_identifier {"--"} |
Signals the parser that no options follow this string but only positional arguments. | |
Friends | |
struct | ::sharg::detail::test_accessor |
Befriend sharg::detail::test_accessor to grant access to version_check_future and format. | |
The Sharg command line parser.
The sharg::parser is a general purpose argument parser that provides convenient access to the command line arguments passed to the program. It automatically generates a help page and can export manual-pages as well as HTML documentation.
Since the terms option and arguments are frequently used in different contexts we want to first clarify our usage:
-i myfile
, --infile myfile
] refer to key-value pairs. The key is either a short indentifier, restricted to a single character -i
, or a long identifier --infile
.arg1
] refers to command line arguments that are specified without an identifier/key, are always required and are identified by their position.-b
] refers to identifiers that are not followed by a value (booleans) and therefore only indicate whether they are set or not.Adding an option is done in a single call. You simply need to provide a predeclared variable and some additional information like the identifier, description or advanced restrictions. To actually retrieve the value from the command line and enable every other mechanism you need to call the sharg::parser::parse function in the end.
Now you can call your application via the command line:
You can also display the help page automatically:
The sharg::parser follows the POSIX conventions. Note that this means among others:
-a -b
is equivalent to -ab
.-c foo
is equivalent to -cfoo
.--
terminates the options and signals that only positional options follow. This enables the user to use a positional option beginning with -
without it being misinterpreted as an option identifier.There are two different kinds of errors: Developer errors and user errors.
Developer errors are those that violate the sharg::parser design (e.g. calling the sharg::parser::parse function twice or specifying two different options with the same identifier.) In this case, a sharg::design_error is thrown.
The second kind are user errors, due to invalid command line calls. In this case a sharg::parser_error is thrown.
For example:
See the sharg::parser::parse documentation for a detailed list of which exceptions are caught.
SeqAn applications that are using the sharg::parser can check SeqAn servers for version updates. The functionality helps getting new versions out to users faster. It is also used to inform application developers of new versions of the SeqAn library which means that applications ship with less bugs. For privacy implications, please see: https://docs.seqan.de/sharg/main_user/about_update_notifications.html.
Developers that wish to disable this feature permanently can pass an extra constructor argument:
Users of applications that have this feature activated can opt-out, by either:
--version-check false/0
orSHARG_NO_VERSION_CHECK
environment variable.Note that in case there is no --version-check
option (display available options with -h/--help)
, then the developer already disabled the version check functionality.
|
inline |
Initializes an sharg::parser object from the command line arguments.
[in] | app_name | The name of the app that is displayed on the help page. |
[in] | arguments | The command line arguments to parse. |
[in] | version_updates | Notify users about version updates (default sharg::update_notifications::on). |
[in] | subcommands | A list of subcommands (see subcommand parsing ). |
The application name must only contain alpha-numeric characters, _
or -
, i.e. the following regex must evaluate to true: "^[a-zA-Z0-9_-]+$"
.
See the parser tutorial for more information about the version check functionality.
|
inline |
Adds a flag to the sharg::parser.
[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 help page text line to the sharg::parser.
[in] | text | The text to print. |
[in] | is_paragraph | Whether to insert as paragraph or just a line (Default: false). |
[in] | advanced_only | If set to true, the section only shows when the user requested the advanced help page. |
sharg::design_error | if sharg::parser::parse was already called. |
If the line is not a paragraph (false), only one line break is appended, otherwise two line breaks are appended. This only affects the help page and other output formats.
|
inline |
Adds an help page list item (key-value) to the sharg::parser.
[in] | key | The key of the key-value pair of the list item. |
[in] | desc | The value of the key-value pair of the list item. |
[in] | advanced_only | If set to true, the section only shows when the user requested the advanced help page. |
sharg::design_error | if sharg::parser::parse was already called. |
Note: This only affects the help page and other output formats.
A list item is composed of a key (key
) and value (desc
) and usually used for option identifier-description-pairs. E.g.:
|
inline |
Adds an option to the sharg::parser.
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 positional option to the sharg::parser.
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
).
|
inline |
Adds an help page section to the sharg::parser.
[in] | title | The title of the section. |
[in] | advanced_only | If set to true, the section only shows when the user requested the advanced help page. |
sharg::design_error | if sharg::parser::parse was already called. |
This only affects the help page and other output formats.
|
inline |
Adds subcommands to the parser.
[in] | subcommands | A list of subcommands. |
Adds subcommands to the current parser. The list of subcommands is sorted and duplicates are removed.
|
inline |
Adds an help page subsection to the sharg::parser.
[in] | title | The title of the subsection. |
[in] | advanced_only | If set to true, the section only shows when the user requested the advanced help page. |
sharg::design_error | if sharg::parser::parse was already called. |
This only affects the help page and other output formats.
|
inlineprivate |
Throws a sharg::design_error if parse() was already called.
[in] | function_name | The name of the function that was called after parse(). |
sharg::design_error | if parse() was already called |
This function is used when calling functions which have no effect (add_line, add_option, ...) or unexpected behavior (add_subcommands) after parse() was called. Has no effect when parse() encounters a special format (help, version, ...), since those will terminate the program.
|
inlineprivate |
Handles format and subcommand detection.
sharg::too_few_arguments | if option –export-help was specified without a value |
sharg::too_few_arguments | if option –version-check was specified without a value |
sharg::validation_error | if the value passed to option –export-help was invalid. |
sharg::validation_error | if the value passed to option –version-check was invalid. |
sharg::user_input_error | if the subcommand is unknown. |
This function adds all command line parameters to the format_arguments member variable to take advantage of the vector functionality later on. Additionally, the format member variable is set, depending on which parameters are given by the user:
true
.If --export-help
is specified with a value other than html, man, cwl or ctd, an sharg::parser_error is thrown.
|
inline |
Returns a reference to the sub-parser instance if subcommand parsing was enabled.
|
inlineprivate |
Checks whether the long identifier has already been used before.
[in] | id | The long identifier of the command line option/flag. |
true
if an option or flag with the long identifier exists or false
otherwise.
|
inline |
Checks whether the option identifier (id
) was set on the command line by the user.
id_type | Either type char or a type that a std::string is constructible from. |
[in] | id | The short (char ) or long (std::string ) option identifier to search for. |
true
if option identifier id
was set on the command line by the user. sharg::design_error | if the function is used incorrectly (see details below). |
You can only ask for option identifiers that were added to the parser beforehand via sharg::parser::add_option
. As in the sharg::parser::add_option
call, pass short identifiers as a char
and long identifiers as a std::string
or a type that a std::string
is constructible from (e.g. a const char *
).
This function throws a sharg::design_error if
sharg::parser::parse()
was not called before.std::string
) that only consists of a single character. If you mean to pass a short identifier, please pass it as a char
not a std::string
.sharg::parser::add_option()
calls beforehand.
|
inline |
Initiates the actual command line parsing.
sharg::design_error | if this function was already called before. |
sharg::design_error | if the application name or subcommands contain illegal characters. |
sharg::option_declared_multiple_times | if an option that is not a list was declared multiple times. |
sharg::user_input_error | if an incorrect argument is given as (positional) option value. |
sharg::required_option_missing | if the user did not provide a required option. |
sharg::too_many_arguments | if the command line call contained more arguments than expected. |
sharg::too_few_arguments | if the command line call contained less arguments than expected. |
sharg::validation_error | if the argument was not excepted by the provided validator. |
When no specific key words are supplied, the sharg::parser starts to process the command line for specified options, flags and positional options.
If the given command line input (argv
) contains the following keywords (in order of checking), the parser will exit (std::exit) with error code 0 after doing the following:
Example:
The code above gives the following output when calling --help
:
If the user does something wrong, it looks like this:
|
inlineprivate |
Parses the command line arguments according to the format.
sharg::option_declared_multiple_times | if an option that is not a list was declared multiple times. |
sharg::user_input_error | if an incorrect argument is given as (positional) option value. |
sharg::required_option_missing | if the user did not provide a required option. |
sharg::too_many_arguments | if the command line call contained more arguments than expected. |
sharg::too_few_arguments | if the command line call contained less arguments than expected. |
sharg::validation_error | if the argument was not excepted by the provided validator. |
This function calls the parse function of the format member variable.
|
inlineprivate |
Runs the version check if the user has not disabled it.
If the user has not disabled the version check, the function will start a detached thread that will call the sharg::detail::version_checker and print a message if a new version is available.
|
inlineprivate |
Verifies that the app and subcommand names are correctly formatted.
sharg::design_error | if the app name is not correctly formatted. |
sharg::design_error | if the subcommand names are not correctly formatted. |
The app name must only contain alphanumeric characters, '_', or '-'. The subcommand names must only contain alphanumeric characters, '_', or '-'.
|
inlineprivate |
Verifies that the short and the long identifiers are correctly formatted.
[in] | short_id | The short identifier of the command line option/flag. |
[in] | long_id | The long identifier of the command line option/flag. |
sharg::design_error |
Specifically, checks that identifiers haven't been used before, the length of long IDs is either empty or longer than one char, the characters used in the identifiers are all valid, and at least one of short_id or long_id is given.
private |
The format of the parser that decides the behavior when calling the sharg::parser::parse function.
The format is set in the function parser::init.
parser_meta_data sharg::parser::info |
Aggregates all parser related meta data (see sharg::parser_meta_data struct).
The meta information is assembled in a struct to provide a central access point that can be easily extended.
You can access the members directly: (see sharg::parser_meta_data for a list of the info members)
This will produce a nice help page when the user calls -h
or --help
: