ookii Namespace Reference

Namespace containing the core Ookii.CommandLine.Cpp types. More...

Namespaces
	format
	Namespace containing helper functions for formatting.
	vt
	Namespace containing functions and types for working with virtual terminal sequences.

Classes
class	action_command_line_argument
	Class that provides information about action arguments. More...
class	basic_command
	Abstract base class for all subcommands. More...
class	basic_command_line_parser
	Parses command line arguments into strongly-typed values. More...
class	basic_command_manager
	Manages registration, creation and invocation of subcommands for an application. More...
class	basic_command_with_custom_parsing
	Abstract base class for subcommands that do their own argument parsing. More...
class	basic_line_wrapping_ostream
	Output stream that wraps lines on white-space characters at the specified line length, and with support for indentation. More...
class	basic_line_wrapping_ostringstream
	Output string stream that wraps lines on white-space characters at the specified line length, and with support for indentation. More...
class	basic_line_wrapping_streambuf
	Stream buffer that wraps lines on white-space characters at the specified line length, and with support for indentation. More...
class	basic_localized_string_provider
	Provides custom localized strings. More...
class	basic_parser_builder
	Provides functionality to specify options and arguments to create a new basic_command_line_parser. More...
class	basic_usage_writer
	Creates usage help for the basic_command_line_parser and basic_command_manager classes. More...
struct	char_less
	A version of the std::less predicate for characters that supports case insensitive comparison. More...
class	command_info
	Provides information about a subcommand. More...
class	command_line_argument
	Class that provides information about arguments that are not multi-value arguments. More...
class	command_line_argument_base
	Abstract base class for regular and multi-value arguments. More...
struct	console_stream
	Template to determine the correct console streams based on the character type. More...
struct	console_stream< char >
	Specialization of console_stream for char. More...
struct	console_stream< wchar_t >
	Specialization of console_stream for wchar_t. More...
struct	lexical_convert
	Template class used to convert strings to strongly typed argument values. More...
struct	lexical_convert< bool, CharType, Traits, Alloc >
	Specialization of the lexical_convert template for conversion from string to bool. More...
struct	lexical_convert< std::basic_string< CharType, Traits, Alloc >, CharType, Traits, Alloc >
	Specialization of lexical_convert for strings. More...
class	multi_value_command_line_argument
	Class that provides information about arguments that are not multi-value arguments. More...
struct	parse_result
	Provides the result, success or error, of a command line argument parsing operation. More...
struct	string_convert
	Performs a simple conversion of a narrow character string to a specified character type. More...
struct	string_convert< char, Traits, Alloc >
	Specialization of string_convert where the target type is also char. More...
struct	string_less
	A version of the std::less predicate for strings that supports case insensitive comparison. More...
class	tokenize
	A pseudo-range for string tokenization. More...
struct	value_description
	Template used to specify the default value description for a type. More...
struct	value_description< std::basic_string< CharType2, Traits2, Alloc2 >, CharType, Traits, Alloc >
	Specialization of value_description for strings. More...
struct	value_description< std::optional< T >, CharType, Traits, Alloc >
	Specialization of value_description for std::optional<T>. More...

Typedefs
using	command = basic_command< char >
	Typedef for basic_command using char as the character type.
using	command_line_parser = basic_command_line_parser< char >
	Typedef for basic_command_line_parser using char as the character type.
using	command_manager = basic_command_manager< char >
	Typedef for basic_command_manager using char as the character type.
using	command_with_custom_parsing = basic_command_with_custom_parsing< char >
	Typedef for basic_command_with_custom_parsing using char as the character type.
using	line_wrapping_ostream = basic_line_wrapping_ostream< char >
	A line wrapping stream for use with the char type.
using	line_wrapping_ostringstream = basic_line_wrapping_ostringstream< char >
	A line wrapping string stream for use with the char type.
using	line_wrapping_streambuf = basic_line_wrapping_streambuf< char >
	A line wrapping stream buffer for use with the char type.
using	localized_string_provider = basic_localized_string_provider< char >
	Typedef for basic_localized_string_provider using char as the character type.
using	parser_builder = basic_parser_builder< char >
	Typedef for basic_command using char as the character type.
using	usage_writer = basic_usage_writer< char >
	Typedef for basic_usage_writer using char as the character type.
using	wcommand = basic_command< wchar_t >
	Typedef for basic_command using wchar_t as the character type.
using	wcommand_line_parser = basic_command_line_parser< wchar_t >
	Typedef for basic_command_line_parser using wchar_t as the character type.
using	wcommand_manager = basic_command_manager< wchar_t >
	Typedef for basic_command_manager using wchar_t as the character type.
using	wcommand_with_custom_parsing = basic_command_with_custom_parsing< wchar_t >
	Typedef for basic_command_with_custom_parsing using wchar_t as the character type.
using	wline_wrapping_ostream = basic_line_wrapping_ostream< wchar_t >
	A line wrapping stream for use with the wchar_t type.
using	wline_wrapping_ostringstream = basic_line_wrapping_ostringstream< wchar_t >
	A line wrapping string stream for use with the wchar_t type.
using	wline_wrapping_streambuf = basic_line_wrapping_streambuf< wchar_t >
	A line wrapping stream buffer for use with the wchar_t type.
using	wlocalized_string_provider = basic_localized_string_provider< wchar_t >
	Typedef for basic_localized_string_provider using wchar_t as the character type.
using	wparser_builder = basic_parser_builder< wchar_t >
	Typedef for basic_command using wchar_t as the character type.
using	wusage_writer = basic_usage_writer< wchar_t >
	Typedef for basic_usage_writer using wchar_t as the character type.

Enumerations
enum class	description_list_filter_mode { information , descripion , all , none }
	Indicates which arguments should be included in the description list when printing usage. More...
enum class	description_list_sort_mode {   usage_order , alphabetical , alphabetical_descending , alphabetical_short_name ,   alphabetical_short_name_descending }
	Indicates how the arguments in the description list should be sorted. More...
enum class	on_parsed_action { none , cancel_parsing , always_continue }
	Value to be returned from the callback passed to the basic_command_line_parser::on_parsed() method. More...
enum class	parse_error {   none , parsing_cancelled , invalid_value , unknown_argument ,   missing_value , duplicate_argument , too_many_arguments , missing_required_argument ,   combined_short_name_non_switch }
	The type of error that occurred while parsing the command line. More...
enum class	parsing_mode { default_mode , long_short }
	Indicates what argument parsing rules should be used to interpret the command line. More...
enum class	set_value_result { success , error , cancel }
	The result of attempting to set a value for an argument. More...
enum class	standard_stream { input , output , error }
	Represents one of the standard console streams. More...
enum class	usage_help_request { full , syntax_only , none }
	Indicates if and how usage is shown if an error occurred parsing the command line. More...
enum class	vt_result { failed , no_change , success }
	Indicates the result of the set_console_vt_support operation. More...

Functions
details::flush_helper	flush (bool flush_last_line)
	IO manipulator that flushes a stream using a basic_line_wrapping_streambuf, optionally flushing the last unterminated line. More...
short	get_console_width (short default_width=80) noexcept
	Determines the width of the console. More...
template<typename T , typename CharType = char, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
auto	get_short_type_name ()
	Gets the name of a type excluding the namespace name. More...
template<typename CharType = char, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
auto	get_short_type_name (const std::type_info &type)
	Gets the name of a type excluding the namespace name. More...
template<typename T , typename CharType = char, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
auto	get_type_name ()
	Gets the name of a type. More...
template<typename CharType = char, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
auto	get_type_name (const std::type_info &type)
	Gets the name of a type. More...
template<typename CharType , size_t Length>
constexpr const std::array< CharType, Length >	literal_cast (const char(&value)[Length])
	Converts a simple ASCII string literal to the specified character type at compile time. More...
basic_command_manager< details::default_char_type >	register_commands (std::basic_string< details::default_char_type > application_name, basic_localized_string_provider< details::default_char_type > *string_provider=nullptr, const std::locale &locale={})
	Function that registers all the subcommands generated by New-Subcommand.ps1. More...
template<typename CharType , typename Traits >
std::basic_ostream< CharType, Traits > &	reset_indent (std::basic_ostream< CharType, Traits > &stream)
	IO manipulator that lets the next line start at the beginning of the line, without indenting it. More...
vt_result	set_console_vt_support ([[maybe_unused]] standard_stream stream, [[maybe_unused]] bool enable) noexcept
	Enables or disables console support for virtual terminal sequences. More...
details::set_indent_helper	set_indent (size_t indent)
	IO manipulator that changes the number of spaces that each line is indented with for a line wrapping stream. More...
template<typename CharType , typename Traits >
std::tuple< std::basic_string_view< CharType, Traits >, std::optional< std::basic_string_view< CharType, Traits > > >	split_once (std::basic_string_view< CharType, Traits > value, CharType separator)
	Splits a string on the first occurrence of a separator. More...
template<typename CharType , typename Traits >
bool	string_equal_case_insensitive (std::basic_string_view< CharType, Traits > string1, std::basic_string_view< CharType, Traits > string2, const std::locale &locale={})
	Compares two strings, ignoring their case. More...
template<typename CharType , typename Traits >
std::optional< std::basic_string_view< CharType, Traits > >	strip_prefix (std::basic_string_view< CharType, Traits > value, std::basic_string_view< CharType, Traits > prefix)
	Removes a prefix from a string. More...

Variables
constexpr size_t	use_console_width = std::numeric_limits<size_t>::max()
	Indicates that the basic_line_wrapping_streambuf should use the console width as the line length.

Detailed Description

Namespace containing the core Ookii.CommandLine.Cpp types.

This namespace defines all the types needed to use Ookii.CommandLine.Cpp, including basic_command_line_parser and basic_parser_builder. It also defines utility types such as basic_line_wrapping_ostream.

Enumeration Type Documentation

description_list_filter_mode

enum ookii::description_list_filter_mode

strong

Indicates which arguments should be included in the description list when printing usage.

Enumerator
information	Include arguments that have any information that is not included in the syntax, such as aliases, a default value, or a description.
descripion	Include only arguments that have a description.
all	Include all arguments.
none	Omit the description list entirely.

description_list_sort_mode

enum ookii::description_list_sort_mode

strong

Indicates how the arguments in the description list should be sorted.

Enumerator
usage_order	The descriptions are listed in the same order as the usage syntax: first the positional arguments, then the required named arguments sorted by name, then the remaining arguments sorted by name.
alphabetical	The descriptions are listed in alphabetical order by argument name. If the parsing mode is parsing_mode::long_short, this uses the long name of the argument, unless the argument has no long name, in which case the short name is used.
alphabetical_descending	The same as alphabetical, but in reverse order.
alphabetical_short_name	The descriptions are listed in alphabetical order by the short argument name. If the argument has no short name, the long name is used. If the parsing mode is not parsing_mode::long_short, this has the same effect as alphabetical.
alphabetical_short_name_descending	The same as alphabetical_short_name, but in reverse order.

on_parsed_action

enum ookii::on_parsed_action

strong

Value to be returned from the callback passed to the basic_command_line_parser::on_parsed() method.

Enumerator
none	Don't take any special action.
cancel_parsing	Cancel parsing immediately, disregarding the rest of the command line. Parsing will return with parse_error::parsing_cancelled.
always_continue	Continue parsing even if command_line_argument::cancel_parsing() returns true.

parse_error

enum ookii::parse_error

strong

The type of error that occurred while parsing the command line.

Enumerator
none	No error occurred.
parsing_cancelled	Parsing was cancelled by an argument using basic_parser_builder::argument_builder_common::cancel_parsing(), or the by the basic_command_line_parser::on_parsed() callback. While this is treated as a parsing failure, this is not technically an error, and no error message is associated with it.
invalid_value	A supplied value could not be converted to the argument's type.
unknown_argument	An argument name was supplied that doesn't exist.
missing_value	A named argument, other than a switch argument, was supplied without a value.
duplicate_argument	An argument, other than a multi-value argument, was supplied more than once, and basic_parser_builder::allow_duplicate_arguments() was not enabled.
too_many_arguments	More positional arguments were supplied than were defined.
missing_required_argument	One of the required arguments was not supplied.
combined_short_name_non_switch	A combined short argument contains an argument that is not a switch.

parsing_mode

enum ookii::parsing_mode

strong

Indicates what argument parsing rules should be used to interpret the command line.

To set the parsing mode, use the basic_parser_builder::mode() method.

Enumerator
default_mode	Use the normal Ookii.CommandLine parsing rules.
long_short	Use POSIX-like rules where arguments have separate long and short names.

set_value_result

enum ookii::set_value_result

strong

The result of attempting to set a value for an argument.

Enumerator
success	The operation was successful.
error	There was an error converting the value to the element type of the argument.
cancel	The operation was successful, but has requested that parsing will be cancelled.

standard_stream

enum ookii::standard_stream

strong

Represents one of the standard console streams.

Enumerator
input	The standard input stream.
output	The standard output stream.
error	The standard error stream.

usage_help_request

enum ookii::usage_help_request

strong

Indicates if and how usage is shown if an error occurred parsing the command line.

Enumerator
full	Full usage help is shown, including the argument descriptions.
syntax_only	Only the usage syntax is shown; the argument descriptions are not. In addition, the basic_usage_writer::write_more_info_message() message is shown.
none	No usage help is shown. Instead, the basic_usage_writer::write_more_info_message() message is shown.

vt_result

enum ookii::vt_result

strong

Indicates the result of the set_console_vt_support operation.

Enumerator
failed	Virtual terminal sequences could not be enabled.
no_change	No action was taken, because the value already matched the requested setting.
success	Virtual terminal sequences were successfully enabled.

Function Documentation

flush()

details::flush_helper ookii::flush ( bool  flush_last_line )

inline

IO manipulator that flushes a stream using a basic_line_wrapping_streambuf, optionally flushing the last unterminated line.

If the basic_line_wrapping_streambuf contains a line that's shorter than the maximum and was not terminated by a line break, the normal std::flush manipulator will not flush that final line, because doing so would make it impossible to find the correct place to wrap the line later if that place was already flushed.

This manipulator offers the ability to flush the buffer including the last line. If there is a non-empty, non-terminated line in the buffer, that line will be flushed, followed by a line break.

Sample:

stream << ookii::flush;

Attention

If the stream does not use a basic_line_wrapping_streambuf, the effect is the same as using std::flush.

Warning

This IO manipulator uses dynamic_cast and may require RTTI.

Parameters

flush_last_line

true to flush the final non-terminated line; false to leave that line in the buffer.

get_console_width()

short ookii::get_console_width ( short  default_width = 80 )

inlinenoexcept

Determines the width of the console.

This function returns the width of the console attached to stdout. If stdout is redirected to a file, it's platform dependent whether the width is still returned.

Parameters

default_width

The width to assume if the actual width can't be determined.

get_short_type_name() [1/2]

template<typename T , typename CharType = char, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

auto ookii::get_short_type_name ( )

inline

Gets the name of a type excluding the namespace name.

On g++, this demangles the type name before returning it. On VC++, it also strips the "class" or "struct" prefix.

Template Parameters

T	The type whose name to return.
CharType	The character type to use for the returned string.
Traits	The character traits to use.
Alloc	The allocator to use.

get_short_type_name() [2/2]

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

auto ookii::get_short_type_name ( const std::type_info &  type )

inline

Gets the name of a type excluding the namespace name.

On g++, this demangles the type name before returning it. On VC++, it also strips the "class" or "struct" prefix.

Template Parameters

CharType	The character type to use for the returned string.
Traits	The character traits to use.
Alloc	The allocator to use.

Parameters

type	The type_info for the type.

get_type_name() [1/2]

template<typename T , typename CharType = char, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>

auto ookii::get_type_name ( )

inline

Gets the name of a type.

On g++, this demangles the type name before returning it.

Template Parameters

T	The type whose name to return.
CharType	The character type to use for the returned string.
Traits	The character traits to use.
Alloc	The allocator to use.

get_type_name() [2/2]

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

auto ookii::get_type_name ( const std::type_info &  type )

inline

Gets the name of a type.

On g++, this demangles the type name before returning it.

Template Parameters

CharType	The character type to use for the returned string.
Traits	The character traits to use.
Alloc	The allocator to use.

Parameters

type	The type_info for the type.

literal_cast()

template<typename CharType , size_t Length>

constexpr const std::array<CharType, Length> ookii::literal_cast ( const char(&)  value[Length] )

constexpr

Converts a simple ASCII string literal to the specified character type at compile time.

This function is intended to be used on simple literals, to allow template functions to use string literals where the character type depends on the template parameters.

Warning

This function simply copies the source array to the target array, and will not work correctly if the source array contains multi-byte characters.

Template Parameters

CharType	The target character type.
Length	The length of the string.

Parameters

value

The character sequence to convert.

Returns

A std::array holding the converted character sequence.

register_commands()

basic_command_manager<details::default_char_type> ookii::register_commands	(	std::basic_string< details::default_char_type >	application_name,
		basic_localized_string_provider< details::default_char_type > *	string_provider = nullptr,
		const std::locale &	locale = {}
	)

Function that registers all the subcommands generated by New-Subcommand.ps1.

When using New-Subcommand.ps1, the definition of this method will be generated.

This method will be declared for use with wchar_t if _UNICODE is defined; otherwise, it uses char.

Parameters

application_name	The name of the application's executable, for use with the usage help.
string_provider	The basic_localized_string_provider to use for error messages and other strings, or nullptr to use the default.
locale	The locale to use when converting argument values. The default is a copy of the current global locale.

reset_indent()

template<typename CharType , typename Traits >

std::basic_ostream<CharType, Traits>& ookii::reset_indent

(

std::basic_ostream< CharType, Traits > &

stream

)

IO manipulator that lets the next line start at the beginning of the line, without indenting it.

Attention

If the last character written to the buffer was not a new line, one is inserted.

This has no effect if the stream does not use a basic_line_wrapping_streambuf.

Warning

This IO manipulator uses dynamic_cast and may require RTTI.

Sample:

stream << ookii::reset_indent;

Template Parameters

CharType	The character type of the stream.
Traits	The character traits type of the stream.

Parameters

stream

The stream to write to.

set_console_vt_support()

vt_result ookii::set_console_vt_support ( [[maybe_unused] ] standard_stream  stream, [[maybe_unused] ] bool  enable  )

inlinenoexcept

Enables or disables console support for virtual terminal sequences.

Attention

You may want to use ookii::vt::enable_virtual_terminal_sequences() or ookii::vt::enable_color() instead.

On Windows, this enables virtual terminal support using SetConsoleMode(). If this function returns vt_result::failed, use GetLastError() to get more information.

On other platforms, this function does nothing, and always returns vt_result::no_change.

Parameters

stream	The standard stream to enable/disable VT support for.
enable	true to enable VT support, otherwise, false.

Returns

One of the values of the vt_result enumeration.

set_indent()

details::set_indent_helper ookii::set_indent ( size_t  indent )

inline

IO manipulator that changes the number of spaces that each line is indented with for a line wrapping stream.

Attention

This has no effect if the stream does not use a basic_line_wrapping_streambuf.

Warning

This IO manipulator uses dynamic_cast and may require RTTI.

Sample:

stream << ookii::set_indent(4);

Parameters

indent

The new indentation size.

split_once()

template<typename CharType , typename Traits >

std::tuple<std::basic_string_view<CharType, Traits>, std::optional<std::basic_string_view<CharType, Traits> > > ookii::split_once	(	std::basic_string_view< CharType, Traits >	value,
		CharType	separator
	)

Splits a string on the first occurrence of a separator.

Template Parameters

CharType	The character type used.
Traits	The character traits to use.

Parameters

value	The string to split.
separator	The separator to split on.

Returns

If the string contains the separator, both segments are returned, excluding the separator; otherwise, the first segment is the entire string and the second one is std::nullopt.

string_equal_case_insensitive()

template<typename CharType , typename Traits >

bool ookii::string_equal_case_insensitive	(	std::basic_string_view< CharType, Traits >	string1,
		std::basic_string_view< CharType, Traits >	string2,
		const std::locale &	locale = {}
	)

Compares two strings, ignoring their case.

Template Parameters

CharType	The character type used.
Traits	The character traits used.

Parameters

string1	The first string.
string2	The second string.
locale	The locale to use for case conversion.

Returns

true if the strings are equal, ignoring case; otherwise, false.

strip_prefix()

template<typename CharType , typename Traits >

std::optional<std::basic_string_view<CharType, Traits> > ookii::strip_prefix	(	std::basic_string_view< CharType, Traits >	value,
		std::basic_string_view< CharType, Traits >	prefix
	)

Removes a prefix from a string.

Template Parameters

CharType	The character type used.
Traits	The character traits to use.

Parameters

value	The string to remove the prefix from.
prefix	The prefix to remove.

Returns

If the value parameter starts with the prefix parameter, a string view of the value parameter with the prefix removed; otherwise, std::nullopt.