Handles command line parsing. More...

Public Member Functions
	option_parser ()=default
	Default constructor.

	option_parser (option_set options)
	Constructs an option_parser from an option_set.

	option_parser (std::initializer_list< option > options)
	Constructs an option_parser from a list of options.

template<typename... Args>
void	add (Args &&...args)
	Adds an option to the option_parser. More...

option_parser &	add_subcommand (subcommand sub)
	Registers a subcommand for parsing. More...

template<typename Formatter >
void	help_formatter (const Formatter &form)
	Sets the help formatter of the parser. More...

template<typename ForwardIt >
arguments	raw_parse (ForwardIt begin, ForwardIt end)
	Parses command line arguments without handling errors. More...

void	notify ()
	Checks if required arguments are active. More...

template<typename ForwardIt >
arguments	parse (ForwardIt begin, ForwardIt end, std::ostream &out=std::cout, std::ostream &err=std::cerr)
	Parses the command line arguments while handling errors. More...

std::string	format_description () const noexcept
	Returns the formatted description message. More...

std::string	format_epilogue () const noexcept
	Returns the formatted epilogue message. More...

std::string	format_usage () const noexcept
	Returns the formatted usage message. More...

std::string	format_subcommands () const noexcept
	Returns the formatted subcommands message. More...

std::string	format_options () const noexcept
	Returns the formatted options message. More...

std::string	format_help () const noexcept
	Returns the formatted help message. More...

void	error (const std::string &message, std::ostream &err=std::cerr)
	Utility to show a formatted error message. More...

Public Attributes
std::string	description
	A brief paragraph giving an overview of the program.

std::string	epilogue
	A paragraph printed after the help message.

std::string	program_name
	The program name, if not provided it's argv[0].

std::string	usage = "[options...]"
	The usage string.

Detailed Description

This class is mainly used for handling the command line parsing of the command line arguments. It is also used for registering subcommands, errors, and other general program utilities.

Definition at line 40 of file option_parser.hpp.

Member Function Documentation

template<typename... Args>

void gears::optparse::option_parser::add ( Args &&... args )

inline

Adds an option to the option_parser. This function is equivalent to the option_set::add function. The option is added to the list of options when no subcommand is specified.

Parameters

args	The arguments to pass to option_set::add.

Definition at line 237 of file option_parser.hpp.

option_parser& gears::optparse::option_parser::add_subcommand ( subcommand sub )

inline

Registers a subcommand for parsing.

Parameters

sub	The subcommand to register.

Returns: A reference to the option_parser.

Definition at line 248 of file option_parser.hpp.

void gears::optparse::option_parser::error	(	const std::string &	message,
		std::ostream &	err = `std::cerr`
	)

inline

Utility to show a formatted error message. The error string shows the formatted usage message first and the string "{program}: error: {message}" wrapped using the current formatter's wrap member function. The function exits the program with std::exit(EXIT_FAILURE).

Definition at line 503 of file option_parser.hpp.

std::string gears::optparse::option_parser::format_description ( ) const

inlinenoexcept

Returns the formatted description message. This delegates the work to the optparse::formatter currently active.

Returns: The formatted message.

Definition at line 413 of file option_parser.hpp.

std::string gears::optparse::option_parser::format_epilogue ( ) const

inlinenoexcept

Returns the formatted epilogue message. This delegates the work to the optparse::formatter currently active.

Returns: The formatted message.

Definition at line 423 of file option_parser.hpp.

std::string gears::optparse::option_parser::format_help ( ) const

inlinenoexcept

Returns the formatted help message. The help message is done as if calling the formatter's member functions in the following order:

usage
description
subcommands
options
epilogue

If a different order is needed, you may call the individual member functions that handle the formatting, i.e. the format_* functions.

Returns: The help message.

Definition at line 478 of file option_parser.hpp.

std::string gears::optparse::option_parser::format_options ( ) const

inlinenoexcept

Returns the formatted options message. This delegates the work to the optparse::formatter currently active. Note that this passes the current option_set that is currently active.

Returns: The formatted message.

Definition at line 456 of file option_parser.hpp.

std::string gears::optparse::option_parser::format_subcommands ( ) const

inlinenoexcept

Returns the formatted subcommands message. This delegates the work to the optparse::formatter currently active.

Returns: The formatted message.

Definition at line 445 of file option_parser.hpp.

std::string gears::optparse::option_parser::format_usage ( ) const

inlinenoexcept

Returns the formatted usage message. This delegates the work to the optparse::formatter currently active.

Returns: The formatted message.

Definition at line 433 of file option_parser.hpp.

template<typename Formatter >

void gears::optparse::option_parser::help_formatter ( const Formatter & form )

inline

Sets the help formatter of the parser. The formatter must inherit from optparse::formatter.

Parameters

form	The formatter to use.

Definition at line 261 of file option_parser.hpp.

void gears::optparse::option_parser::notify ( )

inline

Checks if required arguments are active. If a required option is not active then an exception is thrown. Otherwise nothing is thrown. Note that this only checks for required arguments in the active option_set. For example, if a non-subcommand option_set has required options but a subcommand is used and active then this function will check the option_set of the underlying subcommand for required options and skip the required options of the non-subcommand option_set.

Exceptions

missing_required_option Thrown when a required option is inactive.

Definition at line 347 of file option_parser.hpp.

template<typename ForwardIt >

arguments gears::optparse::option_parser::parse	(	ForwardIt	begin,
		ForwardIt	end,
		std::ostream &	out = `std::cout`,
		std::ostream &	err = `std::cerr`
	)

inline

Parses the command line arguments while handling errors. All exceptions are thrown and sent to the error stream provided. If the help command line option is active, then the help message is sent to the output stream provided. Required options are checked and the thrown exceptions are also caught and output to the error stream. The assumptions of the arguments are the same as the ones provided by raw_parse. If exceptions are caught then the program exits as if calling std::exit(EXIT_FAILURE). If the help message is active while no errors are spotted, then the program exits as if calling std::exit(EXIT_SUCCESS). The help message is output as if calling format_help. Required options are checked after checking for the existence of the help option.

Parameters

begin	A ForwardIterator pointing to the first element to parse.
end	A ForwardIterator pointing to one past the last element to parse.
out	The output stream to output the help message to.
err	The error stream to output the errors to.

Returns: An optparse::argument object storing the result.

Definition at line 377 of file option_parser.hpp.

template<typename ForwardIt >

arguments gears::optparse::option_parser::raw_parse	(	ForwardIt	begin,
		ForwardIt	end
	)

inline

Parses command line arguments without handling errors. Exceptions derived by optparse::error are thrown when an error is spotted and all parsing stops. The following assumptions are made:

The first element is the program name.
The second element is the subcommand if available. Skipped if unavailable.
Dereferencing the iterators is implicitly convertible to std::string.

Along with not checking for errors, this function does not check if required arguments are present. This function should only be used if you want to provide your own error handling mechanism.

Parameters

begin	A ForwardIterator pointing to the first element to parse.
end	A ForwardIterator pointing to one past the last element to parse.

Returns: An optparse::arguments object storing the result.

Definition at line 285 of file option_parser.hpp.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation