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

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

Parameters

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

◆ 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

name	name 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.

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

name	option 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

width	maximum length of each line
indent	how 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

arguments vector 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

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

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:

router/src/harness/include/mysql/harness/arg_handler.h
router/src/harness/src/arg_handler.cc

Public Types

Public Member Functions

Public Attributes

Private Attributes

Detailed Description

Member Typedef Documentation

◆ ConfigOverwrites

◆ UsagePredicate

Constructor & Destructor Documentation

◆ CmdArgHandler() [1/2]

◆ CmdArgHandler() [2/2]

Member Function Documentation

◆ add_option() [1/2]

◆ add_option() [2/2]

◆ begin()

◆ clear_options()

◆ debug_check_option_names()

◆ end()

◆ find_option()

◆ get_config_overwrites()

◆ get_options()

◆ get_rest_arguments()

◆ is_valid_option_name()

◆ option_descriptions()

◆ process()

◆ usage_lines()

◆ usage_lines_if()

Member Data Documentation

◆ allow_rest_arguments

◆ config_overwrites_

◆ ignore_unknown_arguments

◆ options_

◆ rest_arguments_