Parses program options. More...

#include <parser.hpp>

Public Member Functions
	parser () noexcept
	Default constructor. More...

	parser (const std::initializer_list< option > &il)
	Construct from an initializer list. More...

template<typename InputIt >
	parser (InputIt first, InputIt last)
	Construct from a sequence. More...

option_group &	group (const std::string &name)
	Returns a reference to a particular group. More...

option &	add_option (const option &opt=option{})
	Add a program option. More...

option &	add_option (const std::string &long_name, char short_name='\0', const std::string &description="", const std::string &arg_name="", bool arg_required=false, const std::string &group_name="")
	Add a program option. More...

template<typename InputIt >
parser_result	parse (InputIt first, InputIt last, bool ignore_first=true) const
	Parse command-line arguments from a sequence of strings. More...

parser_result	parse (int argc, char *argv[], bool ignore_first=true) const
	Parse command-line arguments. More...

parser_result	parse (const std::string &cmd_line, bool ignore_first=false) const
	Parse command-line arguments from a string. More...

void	set_custom_strings (const std::string &delims, const std::string &short_prefix="", const std::string &long_prefix="", const std::string &end_indicator="", const std::string &equals="")
	Change special strings used by the parser. More...

void	sort_groups ()
	Sorts the groups by name. More...

void	sort_options ()
	Sorts all options by name. More...

option &	operator[] (const std::string &long_name)
	Subscript operator. More...

option &	operator[] (char short_name)
	Subscript operator. More...

std::ostream &	print_help (std::ostream &os, int max_line_length=78, int group_indent=0, int option_indent=2, int desc_first_line_indent=30, int desc_multiline_indent=32) const
	Print program help message. More...

Detailed Description

Parses program options.

A parser accepts program option information in the form of option objects, which may be passed to the constructor or added after construction with the add_option method. After all options have been specified, the parse method may then be called with the command-line arguments that were passed to the program. This will produce a parser_result containing the parsed information.

For more information about the argument parsing, refer to the documentation for the parse method.

See also: option; parser_result

Constructor & Destructor Documentation

◆ parser() [1/3]

optionpp::parser::parser ( )

inlinenoexcept

Default constructor.

No program options are accepted by default. Acceptable options can later be specified using the add_option method.

◆ parser() [2/3]

optionpp::parser::parser ( const std::initializer_list< option > & il )

inline

Construct from an initializer list.

Each option provided in the list specifies an acceptable program option that can be given on the command line.

The options are added to the nameless default group.

Parameters

il	The `initializer_list` containing the acceptable program options.

See also: option

◆ parser() [3/3]

template<typename InputIt >

optionpp::parser::parser	(	InputIt	first,
		InputIt	last
	)

inline

Construct from a sequence.

Each option in the sequence specifies an acceptable program option that can be given on the command line.

The options are added to the nameless default group.

Template Parameters

InputIt The iterator type (usually deduced).

Parameters

first	The iterator pointing to the start of the sequence.
last	The iterator pointing to one past the end of the sequence.

Member Function Documentation

◆ add_option() [1/2]

option & optionpp::parser::add_option ( const option & opt = option{} )

Add a program option.

The given option instance (if any) will specify information about a program option that the user can set on the command line, such as the option's long name, short name, description, and so on.

Note that the method returns a reference to the instance of the option that was inserted to allow chaining. For example:

opt_parser.add_option()
          .long_name("verbose")
          .short_name('v')
          .description("Show verbose output.");

Parameters

opt	The `option` to add.

Returns: Reference to the inserted option, for chaining.

◆ add_option() [2/2]

option & optionpp::parser::add_option	(	const std::string &	long_name,
		char	short_name = `'\0'`,
		const std::string &	description = `""`,
		const std::string &	arg_name = `""`,
		bool	arg_required = `false`,
		const std::string &	group_name = `""`
	)

Add a program option.

Parameters

long_name	Long name for the option.
short_name	Short name for the option.
description	Option description (for help message).
arg_name	Argument name, if any (usually uppercase)
arg_required	Set to true if argument is mandatory.
group_name	Name of group option should be added to.

Returns: Reference to the inserted option, for chaining.

◆ group()

option_group & optionpp::parser::group ( const std::string & name )

Returns a reference to a particular group.

The group is created if it does not exist.

Parameters

name	Name of the group.

Returns: Reference to the group.

◆ operator[]() [1/2]

option & optionpp::parser::operator[] ( char short_name )

Subscript operator.

Returns the specified option or creates it if it doesn't exist.

Parameters

short_name Short name for the option.

Returns: Matching option or newly created one if it didn't already exist.

◆ operator[]() [2/2]

option & optionpp::parser::operator[] ( const std::string & long_name )

Subscript operator.

Returns the specified option or creates it if it doesn't exist.

Parameters

long_name Long name for the option.

Returns: Matching option or newly created one if it didn't already exist.

◆ parse() [1/3]

parser_result optionpp::parser::parse	(	const std::string &	cmd_line,
		bool	ignore_first = `false`
	)		const

Parse command-line arguments from a string.

For full details, see the description of the parse(InputIt, InputIt, bool) overload. This version of the function will split the string over whitespace to tokenize the input. Quotes can be used within the string to specify arguments containing whitespace. A backslash can be used to start an escape sequence within an argument.

Parameters

cmd_line	The command-line arguments to parse.
ignore_first	If true, the first argument is ignored.

Returns: parser_result containing the parsed data.

Exceptions

parse_error If an invalid option is entered or a mandatory argument is missing.

See also: parser_result

◆ parse() [2/3]

template<typename InputIt >

parser_result optionpp::parser::parse	(	InputIt	first,
		InputIt	last,
		bool	ignore_first = `true`
	)		const

Parse command-line arguments from a sequence of strings.

Accepts the usual arguments that are normally supplied to main, scans them for program options (these will be arguments starting with a hyphen or double-hyphen) and stores the options together with the non-option arguments in a parser_result object.

Each option can have a short name consisting of a single character (following a hyphen), or a long name (following a double-hyphen), or both. For example, an option called verbose with a short name of v could be specified either as --verbose or as -v.

Multiple short names can be specified in a single argument. For example -abc would specify three options with respective short names a, b, and c.

Some options may accept arguments. Arguments can be supplied in several ways: for long names, the usual form is --long-name=argument and for short names -X argument. The parser will also accept --long-name argument, -X=argument, and -Xargument.

A double-hyphen (--) by itself can be used to indicate the end of program options. Any remaining command line arguments are then interpreted as non-option arguments. A single hyphen (-) by itself is considered a non-option argument (this is often used as a way to specify standard input instead of a filename).

Parameters

first	An iterator pointing to the first argument.
last	An iterator pointing to one past the last argument.
ignore_first	If true, the first argument (typically the program filename) is ignored.

Returns: parser_result containing the parsed data.

Exceptions

parse_error If an invalid option is entered or a mandatory argument is missing.

See also: parser_result

◆ parse() [3/3]

parser_result optionpp::parser::parse	(	int	argc,
		char *	argv[],
		bool	ignore_first = `true`
	)		const

Parse command-line arguments.

Accepts the usual arguments that are normally supplied to main. For further details, see the description of the parse(InputIt, InputIt, bool) overload.

Parameters

argc	The number of arguments given on the command line.
argv	All command-line arguments.
ignore_first	If true, the first argument (typically the program filename) is ignored.

Returns: parser_result containing the parsed data.

Exceptions

parser_error If an invalid option is entered or a mandatory argument is missing.

See also: parser_result

◆ print_help()

std::ostream & optionpp::parser::print_help	(	std::ostream &	os,
		int	max_line_length = `78`,
		int	group_indent = `0`,
		int	option_indent = `2`,
		int	desc_first_line_indent = `30`,
		int	desc_multiline_indent = `32`
	)		const

Print program help message.

This will write all program options, organized by group, to the given output stream. The additional parameters control the formatting.

The options are presented in the order that they were added to each group; if desired, you can call sort_options first to sort the options by name within each group.

Option names and descriptions are displayed in columns, with option names on the left and descriptions on the right. The first line of a description will begin on the same line as the option names, unless there's not enough room, in which case a new line is started.

The indentation levels are not cumulative: each parameter gives the total level of indentation, counted from the leftmost character of the line.

Parameters

os	Output stream.
max_line_length	Text will be wrapped so that each line is at most this many characters.
group_indent	Number of spaces to indent group names.
option_indent	Number of spaces to indent option names.
desc_first_line_indent	Number of spaces to indent first line of each description.
desc_multiline_indent	Number of spaces to indent descriptions after the first line.

Returns: The output stream that was initially given.

◆ set_custom_strings()

void optionpp::parser::set_custom_strings	(	const std::string &	delims,
		const std::string &	short_prefix = `""`,
		const std::string &	long_prefix = `""`,
		const std::string &	end_indicator = `""`,
		const std::string &	equals = `""`
	)

Change special strings used by the parser.

With this method, you can set custom option prefixes and such. For each parameter, a blank string indicates that the old string should be kept.

Parameters

delims	Whitespace delimiters used to separate arguments.
short_prefix	Prefix that indicates a group of short option names.
long_prefix	Prefix that indicates a long option name.
end_indicator	Mark that indicates that all remaining arguments should be interpreted as non-option arguments.
equals	String that indicates an explicit option argument.

◆ sort_groups()

void optionpp::parser::sort_groups ( )

Sorts the groups by name.

By default groups are kept in the order that they were added.

◆ sort_options()

void optionpp::parser::sort_options ( )

Sorts all options by name.

By default, options within each group are kept in the order that they were added. This method will sort all the options in each group so that they are ordered by name (either by their long name, or by their short name if the long name doesn't exist).

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

/home/gkikola/Code/optionpp/include/optionpp/parser.hpp
/home/gkikola/Code/optionpp/src/parser.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ parser() [1/3]

◆ parser() [2/3]

◆ parser() [3/3]

Member Function Documentation

◆ add_option() [1/2]

◆ add_option() [2/2]

◆ group()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ parse() [1/3]

◆ parse() [2/3]

◆ parse() [3/3]

◆ print_help()

◆ set_custom_strings()

◆ sort_groups()

◆ sort_options()