Parses command line arguments into strongly-typed values. More...

#include <ookii/command_line_core.h>

Public Types
using	argument_base_type = command_line_argument_base< CharType, Traits, Alloc >
	The specialized type of command_line_argument_base used.

template<typename T >
using	argument_type = command_line_argument< T, CharType, Traits, Alloc >
	The specialized type of command_line_argument used. More...

template<typename T >
using	converter_type = typename argument_type< T >::typed_storage_type::converter_type
	The specialized type of the custom command line converter function used. More...

using	on_parsed_callback = std::function< on_parsed_action(argument_base_type &, string_view_type value)>
	The callback function type for on_parsed().

using	result_type = parse_result< CharType, Traits, Alloc >
	The specialized type of parse_result used.

using	storage_type = details::parser_storage< CharType, Traits, Alloc >
	The specialized type of parser parameter storage used. For internal use.

using	string_type = typename argument_base_type::string_type
	The specialized type of `std::basic_string` used.

using	string_view_type = std::basic_string_view< CharType, Traits >
	The specialized type of `std::basic_string_view` used.

using	usage_options_type = basic_usage_options< CharType, Traits, Alloc >
	The specialized type of basic_usage_options used.

Public Member Functions
template<typename Range >
	basic_command_line_parser (const Range &arguments, storage_type &&storage, bool case_sensitive)
	Creates a new instance of the basic_command_line_parser class. More...

bool	allow_duplicate_arguments () const noexcept
	Indicates whether duplicate arguments are allowed. More...

bool	allow_white_space_separator () const noexcept
	Indicates whether argument names and values can be separated by white space. More...

CharType	argument_value_separator () const noexcept

auto	arguments () const
	Gets a view of all the arguments defined by the parser. More...

const string_type &	command_name () const noexcept
	Returns the command name used when generating usage help. More...

const string_type &	description () const noexcept
	Returns the description used when generating usage help. More...

template<typename Func >
bool	for_each_argument_in_usage_order (Func f) const
	Invokes the specified function on each argument in the order they are shown in in the usage help. More...

const argument_base_type &	get_argument (const string_type &name) const
	Gets an argument by name. More...

const argument_base_type &	get_argument (size_t pos) const
	Gets an argument by position. More...

const std::locale &	locale () const noexcept
	Gets the locale used to parse argument values and to format strings. More...

void	on_parsed (on_parsed_callback callback)
	Sets a callback that will be invoked every time an argument is parsed. More...

template<typename Range >
result_type	parse (const Range &range)
	Parses the arguments in the specified range. More...

result_type	parse (int argc, const CharType *const argv[])
	Parses the provided arguments. More...

result_type	parse (int argc, const CharType *const argv[], const usage_options_type &options)
	Parses the provided arguments, and writes error and usage information to the console if a parsing error occurs. More...

template<typename Iterator >
result_type	parse (Iterator begin, Iterator end)
	Parses the arguments in the range specified by the iterators. More...

template<typename Iterator >
result_type	parse (Iterator begin, Iterator end, const usage_options_type &options)
	Parses the arguments in the range specified by the iterators, and writes error and usage information to the console if a parsing error occurs. More...

template<typename Range >
result_type	parse (Range range, const usage_options_type &options)
	Parses the arguments in the specified range, and writes error and usage information to the console if a parsing error occurs. More...

template<typename T >
result_type	parse (std::initializer_list< T > args)
	Parses the arguments in the specified initializer list. More...

template<typename T >
result_type	parse (std::initializer_list< T > args, const usage_options_type &options)
	Parses the arguments in the specified initializer list, and writes error and usage information to the console if a parsing error occurs. More...

size_t	positional_argument_count () const
	Gets the number of positional arguments. More...

const std::vector< string_type > &	prefixes () const noexcept
	Gets a list of all the argument name prefixes accepted by the parser. More...

void	write_usage (const usage_options_type &options={})
	Writes usage help for this parser's arguments. More...

Static Public Member Functions
static constexpr std::vector< string_type >	get_default_prefixes ()
	Gets the default prefixes accepted by the parser. More...

Detailed Description

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
class ookii::basic_command_line_parser< CharType, Traits, Alloc >

Parses command line arguments into strongly-typed values.

The basic_command_line_parser class can parse a set of command line arguments in string form into a set of typed values. Which arguments are accepted and where their values will be stored is defined by the basic_parser_builder that created the basic_command_line_parser instance.

In addition, this class can generate detailed usage help for the defined arguments, which can be shown to the user in case an argument parsing error happens or help is requested.

To parse arguments, call one of the overloads of the parse() method. Those overloads taking a basic_usage_options will handle any errors and print the error as well as usage information to the console. Most commonly, the overload you'll want to use is parse(int argc, const CharType *const argv[], const usage_options_type &options).

Two typedefs for common character types are provided:

Type	Definition
`ookii::command_line_parser`	`ookii::basic_command_line_parser<char>`
`ookii::wcommand_line_parser`	`ookii::basic_command_line_parser<wchar_t>`

Template Parameters

CharType	The character type used for arguments and other strings. Only `char` and `wchar_t` are supported. Defaults to `wchar_t` if `_UNICODE` is defined, otherwise to `char`.
Traits	The character traits to use for strings. Defaults to `std::char_traits<CharType>`.
Alloc	The allocator to use for strings. Defaults to `std::allocator<CharType>`.

Member Typedef Documentation

◆ argument_type

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename T >

using ookii::basic_command_line_parser< CharType, Traits, Alloc >::argument_type = command_line_argument<T, CharType, Traits, Alloc>

The specialized type of command_line_argument used.

Template Parameters

T	The type of the argument.

◆ converter_type

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename T >

using ookii::basic_command_line_parser< CharType, Traits, Alloc >::converter_type = typename argument_type<T>::typed_storage_type::converter_type

The specialized type of the custom command line converter function used.

Template Parameters

T	The type of the argument.

Constructor & Destructor Documentation

◆ basic_command_line_parser()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename Range >

ookii::basic_command_line_parser< CharType, Traits, Alloc >::basic_command_line_parser	(	const Range &	arguments,
		storage_type &&	storage,
		bool	case_sensitive
	)

inline

Creates a new instance of the basic_command_line_parser class.

Warning: This constructor should not be used directly; instead, use the basic_parser_builder class to create instances.

Template Parameters

Range The type of a range containing basic_parser_builder::argument_builder instances.

Parameters

arguments	A range containing basic_parser_builder::argument_builder instances.
storage	Parameters for the basic_command_line_parser.
case_sensitive	Indicates whether command line argument names are case sensitive.

Member Function Documentation

◆ allow_duplicate_arguments()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

bool ookii::basic_command_line_parser< CharType, Traits, Alloc >::allow_duplicate_arguments ( ) const

inlinenoexcept

Indicates whether duplicate arguments are allowed.

This value is set by basic_parser_builder::allow_duplicate_arguments()

◆ allow_white_space_separator()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

bool ookii::basic_command_line_parser< CharType, Traits, Alloc >::allow_white_space_separator ( ) const

inlinenoexcept

Indicates whether argument names and values can be separated by white space.

This value is set by basic_parser_builder::allow_white_space_separator()

◆ argument_value_separator()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

CharType ookii::basic_command_line_parser< CharType, Traits, Alloc >::argument_value_separator ( ) const

inlinenoexcept

Indicates the non-whitespace separator used to separaet argument names and values.

This value is set by basic_parser_builder::argument_value_separator()

◆ arguments()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

auto ookii::basic_command_line_parser< CharType, Traits, Alloc >::arguments ( ) const

inline

Gets a view of all the arguments defined by the parser.

Warning: On some versions of Clang, calling this function may cause compiler errors.

The arguments will be returned in alphabetical order.

◆ command_name()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

const string_type& ookii::basic_command_line_parser< CharType, Traits, Alloc >::command_name ( ) const

inlinenoexcept

Returns the command name used when generating usage help.

This value is set by the basic_parser_builder::basic_parser_builder() constructor.

◆ description()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

const string_type& ookii::basic_command_line_parser< CharType, Traits, Alloc >::description ( ) const

inlinenoexcept

Returns the description used when generating usage help.

This value is set by basic_parser_builder::description().

◆ for_each_argument_in_usage_order()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename Func >

bool ookii::basic_command_line_parser< CharType, Traits, Alloc >::for_each_argument_in_usage_order ( Func f ) const

inline

Invokes the specified function on each argument in the order they are shown in in the usage help.

Template Parameters

Func	The type of the function.

Parameters

f	The function to call.

Usage help order is as follows:

The positional arguments, in their specified order.
Any required non-positional arguments, in alphabetical order.
All remaining arguments, in alphabetical order.

◆ get_argument() [1/2]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

const argument_base_type& ookii::basic_command_line_parser< CharType, Traits, Alloc >::get_argument ( const string_type & name ) const

inline

Gets an argument by name.

Parameters

name	The argument's name or alias.

Both the argument's main name and any of its aliases can be used.

Exceptions

std::out_of_range There is no argument with the specified name or alias.

◆ get_argument() [2/2]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

const argument_base_type& ookii::basic_command_line_parser< CharType, Traits, Alloc >::get_argument ( size_t pos ) const

inline

Gets an argument by position.

Parameters

pos	The argument's position.

Only positional arguments can be retrieved using this method.

Positional arguments are created using basic_parser_builder::argument_builder::positional().

Exceptions

std::out_of_range There is no argument at the specified position.

◆ get_default_prefixes()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

static constexpr std::vector<string_type> ookii::basic_command_line_parser< CharType, Traits, Alloc >::get_default_prefixes ( )

inlinestaticconstexpr

Gets the default prefixes accepted by the parser.

By default, the parser accepts '/' and '-' on Windows, and only '-' on other systems.

Which prefixes are accepted can be changed using basic_parser_builder::prefixes().

◆ locale()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

const std::locale& ookii::basic_command_line_parser< CharType, Traits, Alloc >::locale ( ) const

inlinenoexcept

Gets the locale used to parse argument values and to format strings.

This value is set by basic_parser_builder::locale()

◆ on_parsed()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

void ookii::basic_command_line_parser< CharType, Traits, Alloc >::on_parsed ( on_parsed_callback callback )

inline

Sets a callback that will be invoked every time an argument is parsed.

Parameters

callback The callback to be invoked.

The callback must have the signature on_parsed_action(argument_base_type &arg, string_view_type value).

The callback will be invoked after the argument's value has been set. If the argument's value was invalid, it will not be invoked. The value may be an empty string if this is a switch argument.

The callback can control whether parsing continues with the returned on_parsed_action value.

Only one callback can be registered. Calling this function again will replace the previous callback.

◆ parse() [1/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename Range >

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse ( const Range & range )

inline

Parses the arguments in the specified range.

Warning: The range should not include the application name.

Template Parameters

Range The type of the range. This type must define global begin() and end() functions.

Parameters

range A range containing the arguments.

Returns: A parse_result that indicates whether the operation was successful.

◆ parse() [2/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse	(	int	argc,
		const CharType *const	argv[]
	)

inline

Parses the provided arguments.

Warning: It's assumed that argv[0] contains the application name, so this value is skipped when parsing.

Parameters

argc	The number of arguments.
argv	An array containing the arguments.

Returns: A parse_result that indicates whether the operation was successful.

◆ parse() [3/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse	(	int	argc,
		const CharType *const	argv[],
		const usage_options_type &	options
	)

inline

Parses the provided arguments, and writes error and usage information to the console if a parsing error occurs.

Warning: It's assumed that argv[0] contains the application name, so this value is skipped when parsing.

Parameters

argc	The number of arguments.
argv	An array containing the arguments.
options	Options that indicate where errors and usage help are writting in the case of an error, and how they are formatted. Use `{}` to specify default options.

Returns: A parse_result that indicates whether the operation was successful.

◆ parse() [4/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename Iterator >

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse	(	Iterator	begin,
		Iterator	end
	)

inline

Parses the arguments in the range specified by the iterators.

Warning: The range indicated by begin, end should not include the application name.

Template Parameters

Iterator The type of the iterator. This type must meet the requirements of a forward_iterator.

Parameters

begin	An iterator pointing to the first argument.
end	An iterator pointing to directly after the last argument.

Returns: A parse_result that indicates whether the operation was successful.

◆ parse() [5/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename Iterator >

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse	(	Iterator	begin,
		Iterator	end,
		const usage_options_type &	options
	)

inline

Parses the arguments in the range specified by the iterators, and writes error and usage information to the console if a parsing error occurs.

Warning: The range indicated by begin, end should not include the application name.

Template Parameters

Iterator The type of the iterator. This type must meet the requirements of a forward_iterator.

Parameters

begin	An iterator pointing to the first argument.
end	An iterator pointing to directly after the last argument.
options	Options that indicate where errors and usage help are writting in the case of an error, and how they are formatted. Use `{}` to specify default options.

Returns: A parse_result that indicates whether the operation was successful.

◆ parse() [6/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename Range >

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse	(	Range	range,
		const usage_options_type &	options
	)

inline

Parses the arguments in the specified range, and writes error and usage information to the console if a parsing error occurs.

Warning: The range should not include the application name.

Template Parameters

Range The type of the range. This type must define global begin() and end() functions.

Parameters

range	A range containing the arguments.
options	Options that indicate where errors and usage help are writting in the case of an error, and how they are formatted. Use `{}` to specify default options.

Returns: A parse_result that indicates whether the operation was successful.

◆ parse() [7/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename T >

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse ( std::initializer_list< T > args )

inline

Parses the arguments in the specified initializer list.

Warning: The list should not include the application name.

Template Parameters

T	The type of the elements in the initializer list. This must be a string type that can be converted to std::basic_string<CharType, Traits, Alloc>.

Parameters

args	The arguments.

Returns: A parse_result that indicates whether the operation was successful.

◆ parse() [8/8]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

template<typename T >

result_type ookii::basic_command_line_parser< CharType, Traits, Alloc >::parse	(	std::initializer_list< T >	args,
		const usage_options_type &	options
	)

inline

Parses the arguments in the specified initializer list, and writes error and usage information to the console if a parsing error occurs.

Warning: The list should not include the application name.

Template Parameters

T	The type of the elements in the initializer list. This must be a string type that can be converted to std::basic_string<CharType, Traits, Alloc>.

Parameters

args	The arguments.
options	Options that indicate where errors and usage help are writting in the case of an error, and how they are formatted. Use `{}` to specify default options.

Returns: A parse_result that indicates whether the operation was successful.

◆ positional_argument_count()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

size_t ookii::basic_command_line_parser< CharType, Traits, Alloc >::positional_argument_count ( ) const

inline

Gets the number of positional arguments.

Positional arguments are created using basic_parser_builder::argument_builder::positional().

◆ prefixes()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

const std::vector<string_type>& ookii::basic_command_line_parser< CharType, Traits, Alloc >::prefixes ( ) const

inlinenoexcept

Gets a list of all the argument name prefixes accepted by the parser.

By default, the parser accepts '/' and '-' on Windows, and only '-' on other systems.

Which prefixes are accepted can be changed using basic_parser_builder::prefixes().

◆ write_usage()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

void ookii::basic_command_line_parser< CharType, Traits, Alloc >::write_usage ( const usage_options_type & options = {} )

inline

Writes usage help for this parser's arguments.

Parameters

options The basic_usage_options used to format the usage help.

Usage will be written to basic_usage_options::output. In the default basic_usage_options, this is a basic_line_wrapping_ostream for the standard output stream.

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

/mnt/d/Sven/Documents/Code/Ookii.CommandLine.Cpp/include/ookii/command_line_core.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>> class ookii::basic_command_line_parser< CharType, Traits, Alloc >

Member Typedef Documentation

◆ argument_type

◆ converter_type

Constructor & Destructor Documentation

◆ basic_command_line_parser()

Member Function Documentation

◆ allow_duplicate_arguments()

◆ allow_white_space_separator()

◆ argument_value_separator()

◆ arguments()

◆ command_name()

◆ description()

◆ for_each_argument_in_usage_order()

◆ get_argument() [1/2]

◆ get_argument() [2/2]

◆ get_default_prefixes()

◆ locale()

◆ on_parsed()

◆ parse() [1/8]

◆ parse() [2/8]

◆ parse() [3/8]

◆ parse() [4/8]

◆ parse() [5/8]

◆ parse() [6/8]

◆ parse() [7/8]

◆ parse() [8/8]

◆ positional_argument_count()

◆ prefixes()

◆ write_usage()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
class ookii::basic_command_line_parser< CharType, Traits, Alloc >