MySQL 8.4.3
Source Code Documentation
|
Handles command line arguments. More...
#include <arg_handler.h>
Public Types | |
using | UsagePredicate = std::function< std::pair< bool, CmdOption >(const CmdOption &)> |
using | ConfigOverwrites = std::map< std::pair< std::string, std::string >, std::map< std::string, std::string > > |
The key is a section identificator (section name and optional section key), the value is a map of all the overrides for a given section (option/value pairs) More... | |
Public Member Functions | |
CmdArgHandler (bool allow_rest_arguments_, bool ignore_unknown_arguments_=false) | |
Constructor. More... | |
CmdArgHandler () | |
Default constructor. More... | |
void | add_option (const CmdOption::OptionNames &names, const std::string &description, const CmdOptionValueReq &value_req, const std::string &metavar, CmdOption::ActionFunc action, CmdOption::AtEndActionFunc at_end_action=[](const std::string &) { }) noexcept |
Adds a command line option. More... | |
void | add_option (const CmdOption &other) noexcept |
void | process (const std::vector< std::string > &arguments) |
Processes given command line arguments. More... | |
bool | debug_check_option_names (const CmdOption::OptionNames &names) const |
bool | is_valid_option_name (const std::string &name) const noexcept |
Checks whether given name is a valid option name. More... | |
OptionContainer::const_iterator | find_option (const std::string &name) const noexcept |
Finds the option by name. More... | |
std::vector< std::string > | usage_lines (const std::string &prefix, const std::string &rest_metavar, size_t width) const noexcept |
Produces lines of text suitable to show usage. More... | |
std::vector< std::string > | usage_lines_if (const std::string &prefix, const std::string &rest_metavar, size_t width, UsagePredicate predicate) const noexcept |
std::vector< std::string > | option_descriptions (const size_t width, const size_t indent) const noexcept |
Produces description of all options. More... | |
OptionContainer::const_iterator | begin () |
Returns an iterator to first option. More... | |
OptionContainer::const_iterator | end () |
Returns an iterator to end of the option container. More... | |
void | clear_options () |
Clears registered options. More... | |
const std::vector< CmdOption > & | get_options () const noexcept |
Gets all registered options. More... | |
const std::vector< std::string > & | get_rest_arguments () const noexcept |
Returns the rest arguments. More... | |
const ConfigOverwrites & | get_config_overwrites () const noexcept |
Public Attributes | |
bool | allow_rest_arguments |
Whether to allow rest arguments or not. More... | |
bool | ignore_unknown_arguments |
Whether to ignore unknown arguments. More... | |
Private Attributes | |
std::vector< CmdOption > | options_ |
Vector with registered options. More... | |
std::vector< std::string > | rest_arguments_ |
Vector with arguments as strings not processed as options. More... | |
ConfigOverwrites | config_overwrites_ |
Keeps configuration options overwrites. More... | |
Handles command line arguments.
The CmdArgHandler class handles command line arguments. It is a replacement and supports most of the POSIX GNU getopt library.
Command line options can have multiple aliases. For example, the typical --help
can be also called -h
, or even --help-me
. Long names starting with one dash are not supported.
Command line options are added through the add_option()
method and can be given 1 or more names and a description. It is also possible to require the option to have a value, or make the value optional.
During processing of the command line arguments, actions will be executed when the option (and it's potential value) was found.
Usage example:
#include "arg_handler.h" void MyApp::prepare_command_line_options() { // CmdArgHandler handler_; handler_.add_option(OptionNames({"-h", "--help", "--sos"}), "Show help
screen", CmdOptionValueReq::none, "", [this](const string &) { this->show_help(); } handler_.add_option(OptionNames({"–config"}), "Configuration file", CmdOptionValueReq::none, "", [this](const string &value) { this->set_config_file(value); }, []{});
void MyApp::init(const vector<string> arguments) { prepare_command_line_options(); handler_.process(arguments); }
All arguments which are not valid option names are are not values of options are considered rest arguments. By default, rest arguments are not allowed and will raise a std::invalid_argument exception. It is possible to allow them through the constructor.
The CmdArgHandler class also provides functionality to help creating help screen or show how to use the the command line application. The method usage_lines()
produces a usage line showing all the option names, their required or optional value with a meta variable. Similar, method option_descriptions()
will get all options and their descriptions. All this is text wrapped at a configurable margin as well as, if needed, indented.
using CmdArgHandler::ConfigOverwrites = std::map<std::pair<std::string, std::string>, std::map<std::string, std::string> > |
The key is a section identificator (section name and optional section key), the value is a map of all the overrides for a given section (option/value pairs)
using CmdArgHandler::UsagePredicate = std::function<std::pair<bool, CmdOption>(const CmdOption &)> |
|
inlineexplicit |
Constructor.
allow_rest_arguments_ | whether we allow rest arguments or not |
ignore_unknown_arguments_ | whether we ignore unknown arguments or give an error |
|
inline |
Default constructor.
By default, rest arguments are not allowed and unknown arguments are not ignored.
|
noexcept |
|
noexcept |
Adds a command line option.
Adds a command line option given names, description, value requirement and optional action.
names
is a vector of strings which contains names starting with either a single or double dash, -
or --
. It is possible to add more than one name for an option.
The description text will be used in the help output. Note that this can be a very long as text will be wrapped (and optionally indented). New lines in the description will be respected.
The metavar
argument is used in the usage text as a placeholder for the (optional) value of the option, for example, when metavar
is set to path
, the usage would show:
--config=<path>
The value_req argument should be either:
CmdOptionValueReq::none
: option has no valueCmdOptionValueReq::required
: option requires valueCmdOptionValueReq::optional
: option has optional valueThe action
argument should be a std::function
and is called with the (optional) value of the option. The function should accept only a const std::string
.
The at_end_action
argument should be a std::function
. This is optional argument, if not provided then []{} is used as at_end_action. The at_end_action
is meant to be used for additional validation, if particular set of options has to be used together, or if particular set of options cannot be used together.
Example usage:
handler_.add_option(OptionNames({"--config"}), "Configuration file", CmdOptionValueReq::none, "", [this](const string &value) {
this->set_config_file(value); }, []{});
names | vector of string with option names, each starting with - or – |
description | descriptive text explaining the option |
value_req | value requirement of the option |
metavar | for formatting help text when option accepts a value |
action | action to perform when the option was found |
at_end_action | task to perform after all actions have been done |
|
inline |
Returns an iterator to first option.
Returns an iterator to the first option.
|
inline |
Clears registered options.
Clears the registered options.
bool CmdArgHandler::debug_check_option_names | ( | const CmdOption::OptionNames & | names | ) | const |
|
inline |
Returns an iterator to end of the option container.
Returns an iterator to the end of the option container.
|
noexcept |
Finds the option by name.
Finds the option by one of its name. The name should include the the dash prefix.
Example usage: // check if option name is already present assert(end() == find_option(name))
name | name of the option as string |
|
inlinenoexcept |
|
inlinenoexcept |
Gets all registered options.
Returns as a reference to a vector of CmdOption objects.
|
inlinenoexcept |
Returns the rest arguments.
Returns the rest arguments.
If rest arguments are not allow or there were no rest arguments, an empty vector is returned.
|
noexcept |
Checks whether given name is a valid option name.
Checks whether the given name is a valid option name.
A valid option name should:
It is allowed to use the equal sign when giving value. Following options are equal: –config /path/to/mysqlrouter.conf –config=/path/to/mysqlrouter.conf
Throws std::invalid_argument when option name is not valid or option was not registered.
Examples of valid option names:
-h --with-ham --with_spam
Example of invalid option names:
-help ---spam --x-ham
name | option name to check |
|
noexcept |
Produces description of all options.
Produces description of all options. The result is typically shown when the help screen is requested, for example when the --help
option is given.
The width
argument is used to set the maximum length of the lines. Text is wrapped accordingly.
Each description can be indented using space. The amount is given by indent
option.
Example output when lines are printed:
-v, --version Show version -h, --help Show help -c <path>, --config <path> Path to the configuration file
width | maximum length of each line |
indent | how much the description should be indented. |
void CmdArgHandler::process | ( | const std::vector< std::string > & | arguments | ) |
Processes given command line arguments.
Processes given command line argument provided as a vector of strings. It uses the stored option information added through the add_option()
method.
Typically, the vector passed to process() are the argc and argv arguments of the main() function:
process({argv + 1, argv + argc})
When an option is found which requires an argument, optional or not, process() will exit the application with an error message.
If the option has an action defined, the function will be executed with the (optional) value as argument.
arguments | vector of strings |
|
inlinenoexcept |
Produces lines of text suitable to show usage.
Produces lines of text suitable to show usage of the command line appliation. Each option is shown with all its names and with optional or required value.
The prefix
argument can be used to add text, usually the name of the command, in front of the options. The lines are indented using the size of the prefix.
The rest_metavar
can be used to name non-options arguments.
The width
argument is used to set the maximum length of the lines.
Example output when all lines are printed:
usage: mysqlrouter [-v|--version] [-h|--help] [-c|--config=<path>] [-a=[<foo>]] [rest..]
prefix | text in front of options (usually command name) |
rest_metavar | name of rest arguments (empty if not needed) |
width | maximum length of each line |
|
noexcept |
bool CmdArgHandler::allow_rest_arguments |
Whether to allow rest arguments or not.
|
private |
Keeps configuration options overwrites.
bool CmdArgHandler::ignore_unknown_arguments |
Whether to ignore unknown arguments.
|
private |
Vector with registered options.
|
private |
Vector with arguments as strings not processed as options.