MySQL 8.0.29
Source Code Documentation
CmdArgHandler Class Reference

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 ConfigOverwritesget_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< CmdOptionoptions_
 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...
 

Detailed Description

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.

Member Typedef Documentation

◆ ConfigOverwrites

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)

◆ UsagePredicate

using CmdArgHandler::UsagePredicate = std::function<std::pair<bool, CmdOption>(const CmdOption &)>

Constructor & Destructor Documentation

◆ CmdArgHandler() [1/2]

CmdArgHandler::CmdArgHandler ( bool  allow_rest_arguments_,
bool  ignore_unknown_arguments_ = false 
)
inlineexplicit

Constructor.

Parameters
allow_rest_arguments_whether we allow rest arguments or not
ignore_unknown_arguments_whether we ignore unknown arguments or give an error

◆ CmdArgHandler() [2/2]

CmdArgHandler::CmdArgHandler ( )
inline

Default constructor.

By default, rest arguments are not allowed and unknown arguments are not ignored.

Member Function Documentation

◆ add_option() [1/2]

void CmdArgHandler::add_option ( const CmdOption other)
noexcept

◆ add_option() [2/2]

void CmdArgHandler::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.

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 value
  • CmdOptionValueReq::required : option requires value
  • CmdOptionValueReq::optional : option has optional value

The 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 ment 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); }, []{});

Parameters
namesvector of string with option names, each starting with - or –
descriptiondescriptive text explaining the option
value_reqvalue requirement of the option
metavarfor formatting help text when option accepts a value
actionaction to perform when the option was found
at_end_actiontask to perform after all actions have been done

◆ begin()

OptionContainer::const_iterator CmdArgHandler::begin ( )
inline

Returns an iterator to first option.

Returns an iterator to the first option.

Returns
iterator

◆ clear_options()

void CmdArgHandler::clear_options ( )
inline

Clears registered options.

Clears the registered options.

◆ debug_check_option_names()

bool CmdArgHandler::debug_check_option_names ( const CmdOption::OptionNames names) const

◆ end()

OptionContainer::const_iterator CmdArgHandler::end ( )
inline

Returns an iterator to end of the option container.

Returns an iterator to the end of the option container.

Returns
iterator

◆ find_option()

OptionContainer::const_iterator CmdArgHandler::find_option ( const std::string &  name) const
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))

Parameters
namename of the option as string
Returns
iterator object

◆ get_config_overwrites()

const ConfigOverwrites & CmdArgHandler::get_config_overwrites ( ) const
inlinenoexcept

◆ get_options()

const std::vector< CmdOption > & CmdArgHandler::get_options ( ) const
inlinenoexcept

Gets all registered options.

Returns as a reference to a vector of CmdOption objects.

Returns
std::vector<CmdOption>

◆ get_rest_arguments()

const std::vector< std::string > & CmdArgHandler::get_rest_arguments ( ) const
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.

Returns
vector of strings

◆ is_valid_option_name()

bool CmdArgHandler::is_valid_option_name ( const std::string &  name) const
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:

  • have at least consist of 2 characters
  • start with a dash '-'
  • match the reqular expression ^–[A-Za-z]{2}[A-Za-z_-]+$

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
Parameters
nameoption name to check
Returns
true if name is valid; false otherwise

◆ option_descriptions()

std::vector< std::string > CmdArgHandler::option_descriptions ( const size_t  width,
const size_t  indent 
) const
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
Parameters
widthmaximum length of each line
indenthow much the description should be indented.
Returns
vector of strings

◆ process()

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.

Parameters
argumentsvector of strings

◆ usage_lines()

std::vector< std::string > CmdArgHandler::usage_lines ( const std::string &  prefix,
const std::string &  rest_metavar,
size_t  width 
) const
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..]
Parameters
prefixtext in front of options (usually command name)
rest_metavarname of rest arguments (empty if not needed)
widthmaximum length of each line
Returns
vector of strings

◆ usage_lines_if()

std::vector< std::string > CmdArgHandler::usage_lines_if ( const std::string &  prefix,
const std::string &  rest_metavar,
size_t  width,
UsagePredicate  predicate 
) const
noexcept

Member Data Documentation

◆ allow_rest_arguments

bool CmdArgHandler::allow_rest_arguments

Whether to allow rest arguments or not.

◆ config_overwrites_

ConfigOverwrites CmdArgHandler::config_overwrites_
private

Keeps configuration options overwrites.

◆ ignore_unknown_arguments

bool CmdArgHandler::ignore_unknown_arguments

Whether to ignore unknown arguments.

◆ options_

std::vector<CmdOption> CmdArgHandler::options_
private

Vector with registered options.

◆ rest_arguments_

std::vector<std::string> CmdArgHandler::rest_arguments_
private

Vector with arguments as strings not processed as options.


The documentation for this class was generated from the following files: