Creates usage help for the basic_command_line_parser and basic_command_manager classes. More...

#include <ookii/usage_writer.h>

Collaboration diagram for ookii::basic_usage_writer< CharType, Traits, Alloc >:

[legend]

Classes
struct	defaults
	Provides default values for the fields of basic_usage_writer. More...

Public Types
using	argument_type = command_line_argument_base< CharType, Traits, Alloc >
	The concrete command_line_argument_base type used.

using	command_info_type = command_info< CharType, Traits, Alloc >
	The concrete command_info type used.

using	command_manager_type = basic_command_manager< CharType, Traits, Alloc >
	The concrete basic_command_manager type used.

using	parser_type = basic_command_line_parser< CharType, Traits, Alloc >
	The concrete basic_command_line_parser type used.

using	stream_type = std::basic_ostream< CharType, Traits >
	The concrete stream type used.

using	string_type = std::basic_string< CharType, Traits, Alloc >
	The concrete string type used.

using	string_view_type = std::basic_string_view< CharType, Traits >
	The concrete string_view type used.

Public Member Functions
	basic_usage_writer (std::optional< bool > use_color={})
	Initializes a new instance of the basic_usage_writer class. More...

	basic_usage_writer (stream_type &output, bool use_color=false)
	Initializes a new instance of the basic_usage_writer class with the specified stream. More...

	basic_usage_writer (stream_type &output, stream_type &error, bool use_color=false)
	Initializes a new instance of the basic_usage_writer class with the specified output and error streams. More...

virtual void	write_command_list_usage (const command_manager_type &manager)
	Creates usage help for the specified command manager. More...

void	write_error (string_view_type message)
	Writes an error message to the error stream, using color if enabled.

virtual void	write_parser_usage (const parser_type &parser, usage_help_request request=usage_help_request::full)
	Creates usage help for the specified parser. More...

Public Attributes
size_t	application_description_indent {defaults::application_description_indent}
	The level of indentation to use when writing the application description. More...

const char *	argument_description_color {vt::text_format::foreground_green}
	The color applied by the base implementation of the write_argument_description_header() method. More...

size_t	argument_description_indent {defaults::argument_description_indent}
	The level of indentation to use when writing argument descriptions. More...

description_list_filter_mode	argument_description_list_filter {}
	A value that indicates which arguments should be included in the list of argument descriptions. More...

description_list_sort_mode	argument_description_list_order {}
	A value that indicates the order of the arguments in the list of argument descriptions. More...

bool	blank_line_after_command_description {true}
	Indicates whether to add a blank line after each command's description. More...

bool	blank_line_after_description {true}
	Indicates whether to add a blank line after each argument's description. More...

bool	blank_line_after_syntax {true}
	Indicates whether to add a blank line after the usage syntax. More...

const char *	color_reset {vt::text_format::default_format}
	The sequence used to reset color applied a usage help element. More...

const char *	command_description_color {vt::text_format::foreground_green}
	The color applied by the base implementation of the write_command_description_header() method. More...

int	command_description_indent {defaults::command_description_indent}
	The level of indentation to use when writing the command descriptions. More...

stream_type &	error
	The stream used to write errors to.

const char *	error_color {vt::text_format::foreground_red}
	The color applied by the write_error() method. More...

bool	include_aliases_in_description {true}
	Indicates whether to include the aliases of arguments in the description. More...

bool	include_application_description {true}
	Indicates whether to include the application description in the usage help. More...

bool	include_default_value_in_description {true}
	Indicates whether to include the default value of arguments in the description. More...

string_type	name_separator {defaults::name_separator.data()}
	The separator to use between names of arguments and commands. More...

stream_type &	output
	The stream used to write usage help to.

size_t	syntax_indent {defaults::syntax_indent}
	The level of indentation to use when writing the usage syntax. More...

const char *	usage_prefix_color {vt::text_format::foreground_cyan}
	The color applied by the base implementation of the write_usage_syntax_prefix method. More...

bool	use_abbreviated_syntax {}
	Indicates whether to list only positional arguments in the usage syntax. More...

bool	use_short_names_for_syntax {}
	When using parsing_mode::long_short, use short names in the usage syntax. More...

bool	use_white_space_value_separator {true}
	Indicates whether to use white space as the argument name separator in the usage syntax. More...

Protected Member Functions
const command_manager_type &	command_manager () const
	Gets the basic_command_manager that usage is being written for. More...

template<typename Func >
void	for_each_argument_in_description_order (Func f) const
	Iterates over the arguments in the order set by the argument_description_list_order field, including only the arguments selected by the argument_description_list_filter field. More...

const parser_type &	parser () const
	Gets the basic_command_line_parser that usage is being written for. More...

void	set_color (const char *color)
	Writes the specified color virtual terminal sequence, if color is enabled. More...

bool	use_color () const
	Gets a value that indicates whether color virtual terminal sequences can be used in the output. More...

virtual void	write_abbreviated_remaining_arguments ()
	Writes the string used to indicate there are more arguments if the usage syntax was abbreviated. More...

virtual void	write_alias (string_view_type alias, string_view_type prefix)
	Writes a single alias of an argument for use in the argument description list. More...

virtual void	write_aliases (const std::vector< string_type > &aliases, const std::vector< CharType > &short_aliases, string_view_type prefix, string_view_type short_prefix)
	Writes the aliases of an argument for use in the argument description list. More...

virtual void	write_application_description (string_view_type description)
	Writes the application description, or command description in case of a subcommand. More...

virtual void	write_argument_description (const argument_type &arg)
	Writes the description of a single argument. More...

virtual void	write_argument_description (string_view_type description)
	Writes the actual argument description text. More...

virtual void	write_argument_description_body (const argument_type &arg)
	Writes the body of an argument description, which is usually the description itself with any supplemental information. More...

virtual void	write_argument_description_header (const argument_type &arg)
	Writes the header of an argument's description, which is usually the name and value description. More...

virtual void	write_argument_description_list_header ()
	Writes a header before the list of argument descriptions. More...

virtual void	write_argument_descriptions ()
	Writes the list of argument descriptions. More...

virtual void	write_argument_name (string_view_type name, string_view_type prefix)
	Writes the name of an argument. More...

virtual void	write_argument_name_for_description (string_view_type name, string_view_type prefix)
	Writes the name or alias of an argument for use in the argument description list. More...

virtual void	write_argument_syntax (const argument_type &arg)
	Writes the string used to indicate there are more arguments if the usage syntax was abbreviated. More...

virtual void	write_available_commands_header ()
	Writes the usage syntax for an application using subcommands. More...

virtual void	write_command_description (const command_info_type &command)
	Writes the description of a command. More...

virtual void	write_command_description (string_view_type description)
	Writes the description of a command. More...

virtual void	write_command_description_body (const command_info_type &command)
	Writes the body of a command's description, which is typically the description of the command. More...

virtual void	write_command_description_header (const command_info_type &command)
	Writes the header of a command's description, which is typically the name of the command. More...

virtual void	write_command_descriptions ()
	Writes a list of available commands. More...

virtual void	write_command_list_usage_core ()
	Creates the usage help for a basic_command_manager instance. More...

virtual void	write_command_list_usage_footer ()
	Writes a footer after the list of commands. More...

virtual void	write_command_list_usage_syntax ()
	Writes the usage syntax for an application using subcommands. More...

virtual void	write_command_name (string_view_type name)
	Writes the name of a command. More...

virtual void	write_default_value (const argument_type &arg)
	Writes the default value of an argument. More...

virtual void	write_more_info_message ()
	Writes a message telling to user how to get more detailed help. More...

virtual void	write_multi_value_suffix ()
	Writes a suffix that indicates an argument is a multi-value argument. More...

virtual void	write_optional_argument_syntax (const argument_type &arg)
	Writes the string used to indicate there are more arguments if the usage syntax was abbreviated. More...

virtual void	write_parser_usage_core (usage_help_request request)
	Creates the usage help for a basic_command_line_parser instance. More...

virtual void	write_parser_usage_syntax ()
	Writes the usage syntax for the application or subcommand. More...

virtual void	write_positional_argument_name (string_view_type name, string_view_type prefix, std::optional< CharType > separator)
	Writes the name of a positional argument. More...

virtual void	write_spacing (size_t count)
	Writes the specified amount of spaces. More...

virtual void	write_switch_value_description (string_view_type value_description)
	Writes the value description of a switch argument for use in the argument description list. More...

virtual void	write_usage_syntax_prefix (string_view_type command_name)
	Writes the prefix for the usage syntax, including the executable name and, for subcommands, the command name. More...

virtual void	write_value_description (string_view_type value_description)
	Writes the value description of an argument. More...

virtual void	write_value_description_for_description (string_view_type value_description)
	Writes the value description of an argument for use in the argument description list. More...

Detailed Description

template<typename CharType, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
class ookii::basic_usage_writer< CharType, Traits, Alloc >

Creates usage help for the basic_command_line_parser and basic_command_manager classes.

You can derive from this class to override the formatting of various aspects of the usage help. Pass it to the basic_command_line_parser::parse() method or the methods of the basic_command_manager class to specify a custom instance.

Depending on what methods you override, you can change small parts of the formatting, or completely change how usage looks. Certain methods may not be called if you override the methods that call them.

This class has a number of properties that customize the usage help for the base implementation of this class. It is not guaranteed that a derived class will respect these properties.

Two typedefs for common character types are provided:

Type	Definition
`ookii::usage_writer`	`ookii::basic_usage_writer<char>`
`ookii::wusage_writer`	`ookii::basic_usage_writer<wchar_t>`

Template Parameters

CharType	The character type used for strings.
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>`.

Constructor & Destructor Documentation

◆ basic_usage_writer() [1/3]

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

ookii::basic_usage_writer< CharType, Traits, Alloc >::basic_usage_writer ( std::optional< bool > use_color = {} )

inline

Initializes a new instance of the basic_usage_writer class.

This instance will write to a line_wrapping_ostream for the standard output stream and the standard input stream.

Parameters

use_color true to enable color output using virtual terminal sequences, false to disable it, and std::nullopt to automatically enable it if supported using the ookii::vt::enable_color() method.

◆ basic_usage_writer() [2/3]

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

ookii::basic_usage_writer< CharType, Traits, Alloc >::basic_usage_writer	(	stream_type &	output,
		bool	use_color = `false`
	)

inline

Initializes a new instance of the basic_usage_writer class with the specified stream.

This instance will write both errors and usage to the same stream.

Parameters

output	The stream used for usage help and errors.
use_color	`true` to enable color output using virtual terminal sequences, or `false` to disable it.

◆ basic_usage_writer() [3/3]

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

ookii::basic_usage_writer< CharType, Traits, Alloc >::basic_usage_writer	(	stream_type &	output,
		stream_type &	error,
		bool	use_color = `false`
	)

inline

Initializes a new instance of the basic_usage_writer class with the specified output and error streams.

Parameters

output	The stream used for usage help.
error	The stream used for errors.
use_color	`true` to enable color output using virtual terminal sequences, or `false` to disable it.

Member Function Documentation

◆ command_manager()

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

const command_manager_type& ookii::basic_usage_writer< CharType, Traits, Alloc >::command_manager ( ) const

inlineprotected

Gets the basic_command_manager that usage is being written for.

This method is not safe to call except during an invocation of the write_command_list_usage() method, and the methods it calls.

◆ for_each_argument_in_description_order()

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

template<typename Func >

void ookii::basic_usage_writer< CharType, Traits, Alloc >::for_each_argument_in_description_order ( Func f ) const

inlineprotected

Iterates over the arguments in the order set by the argument_description_list_order field, including only the arguments selected by the argument_description_list_filter field.

Parameters

f	A function to invoke for each argument.

◆ parser()

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

const parser_type& ookii::basic_usage_writer< CharType, Traits, Alloc >::parser ( ) const

inlineprotected

Gets the basic_command_line_parser that usage is being written for.

This method is not safe to call except during an invocation of the write_parser_usage() method, and the methods it calls.

◆ set_color()

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

void ookii::basic_usage_writer< CharType, Traits, Alloc >::set_color ( const char * color )

inlineprotected

Writes the specified color virtual terminal sequence, if color is enabled.

Parameters

color One or more virtual terminal sequences for colors.

◆ use_color()

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::use_color ( ) const

inlineprotected

Gets a value that indicates whether color virtual terminal sequences can be used in the output.

Returns: true if color output is allowed; otherwise, false.

◆ write_abbreviated_remaining_arguments()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_abbreviated_remaining_arguments ( )

inlineprotectedvirtual

Writes the string used to indicate there are more arguments if the usage syntax was abbreviated.

The base implementation returns a string like "[arguments]".

This method is called by the base implementation of the write_parser_usage_syntax() method.

◆ write_alias()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_alias	(	string_view_type	alias,
		string_view_type	prefix
	)

inlineprotectedvirtual

Writes a single alias of an argument for use in the argument description list.

The base implementation calls the write_argument_description() method.

This method is called by the base implementation of the write_aliases() method.

Parameters

alias	The name of the argument.
prefix	The prefix of the argument.

◆ write_aliases()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_aliases	(	const std::vector< string_type > &	aliases,
		const std::vector< CharType > &	short_aliases,
		string_view_type	prefix,
		string_view_type	short_prefix
	)

inlineprotectedvirtual

Writes the aliases of an argument for use in the argument description list.

The base implementation writes a list of the aliases, surrounded by parentheses, and preceded by a single space. For example, " (-Alias1, -Alias2)".

If there are no aliases at all, it writes nothing.

This method is called by the base implementation of the write_argument_description_header() method.

Parameters

aliases	A list of the aliases.
short_aliases	A list of the short aliases.
prefix	The argument name prefix to use.
short_prefix	The prefix to use for short argument names.

◆ write_application_description()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_application_description ( string_view_type description )

inlineprotectedvirtual

Writes the application description, or command description in case of a subcommand.

This method is called by the base implementation of the write_parser_usage_core() method if the parser has a description and the include_application_description field is true.

◆ write_argument_description() [1/2]

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_description ( const argument_type & arg )

inlineprotectedvirtual

Writes the description of a single argument.

The base implementation calls the write_argument_description_header() method, the write_argument_description_body() method, and then adds an extra blank line if the blank_line_after_description field is true.

This method is called by the base implementation of the write_argument_descriptions() method.

Parameters

arg	The argument.

◆ write_argument_description() [2/2]

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_description ( string_view_type description )

inlineprotectedvirtual

Writes the actual argument description text.

The base implementation just writes the description text.

This method is called by the base implementation of the write_argument_description_body() method.

Parameters

description The description of the argument.

◆ write_argument_description_body()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_description_body ( const argument_type & arg )

inlineprotectedvirtual

Writes the body of an argument description, which is usually the description itself with any supplemental information.

The base implementation writes the description text and the default value, followed by two new lines. Which elements are included can be influenced using the fields of this class.

This method is called by the base implementation of the write_argument_description() method.

Parameters

arg	The argument.

◆ write_argument_description_header()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_description_header ( const argument_type & arg )

inlineprotectedvirtual

Writes the header of an argument's description, which is usually the name and value description.

The base implementation writes the name(s), value description, and alias(es), ending with a new line. Which elements are included can be influenced using the fields of this class.

If color is enabled, the base implementation will use the argument_description_color.

This method is called by the base implementation of the write_argument_description() method.

Parameters

arg	The argument.

◆ write_argument_description_list_header()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_description_list_header ( )

inlineprotectedvirtual

Writes a header before the list of argument descriptions.

The base implementation does not write anything, as a header is not used in the default format.

This method is called by the base implementation of the write_argument_descriptions() method before the first argument.

◆ write_argument_descriptions()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_descriptions ( )

inlineprotectedvirtual

Writes the list of argument descriptions.

The default implementation calls the write_argument_description() method on each argument.

This method is called by the base implementation of the write_parser_usage_core() method.

◆ write_argument_name()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_name	(	string_view_type	name,
		string_view_type	prefix
	)

inlineprotectedvirtual

Writes the name of an argument.

The default implementation returns the prefix followed by the name, e.g. "-Name".

This method is called by the base implementation of the write_argument_syntax() and write_positional_argument_name() methods.

Parameters

name	The name of the argument.
prefix	The prefix of the argument.

◆ write_argument_name_for_description()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_name_for_description	(	string_view_type	name,
		string_view_type	prefix
	)

inlineprotectedvirtual

Writes the name or alias of an argument for use in the argument description list.

The default implementation returns the prefix followed by the name, e.g. "-Name".

This method is called by the base implementation of the write_argument_description_header() method.

Parameters

name	The name of the argument.
prefix	The prefix of the argument.

◆ write_argument_syntax()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_argument_syntax ( const argument_type & arg )

inlineprotectedvirtual

Writes the string used to indicate there are more arguments if the usage syntax was abbreviated.

This method is called by the base implementation of the write_parser_usage_syntax() and write_optional_argument_syntax() methods.

Parameters

arg	The argument.

◆ write_available_commands_header()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_available_commands_header ( )

inlineprotectedvirtual

Writes the usage syntax for an application using subcommands.

The base implementation writes a string like "The following commands are available:" followed by a blank line.

This method is called by the base implementation of the write_command_list_usage_core() method.

◆ write_command_description() [1/2]

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_description ( const command_info_type & command )

inlineprotectedvirtual

Writes the description of a command.

The base implementation calls the write_command_description_header() method, the write_command_description_body() method, and then adds an extra blank line if the blank_line_after_command_description field is true.

This method is called by the base implementation of the write_command_descriptions() method.

Parameters

command The command.

◆ write_command_description() [2/2]

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_description ( string_view_type description )

inlineprotectedvirtual

Writes the description of a command.

The base implementation just writes the description.

This method is called by the base implementation of the write_command_description_body() method if the command has a description.

Parameters

description The description of the command.

◆ write_command_description_body()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_description_body ( const command_info_type & command )

inlineprotectedvirtual

Writes the body of a command's description, which is typically the description of the command.

The base implementation writes the command's description, followed by a newline.

This method is called by the base implementation of the write_command_description() method.

Parameters

command The command.

◆ write_command_description_header()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_description_header ( const command_info_type & command )

inlineprotectedvirtual

Writes the header of a command's description, which is typically the name of the command.

The base implementation writes the command's name.

If color is enabled, the base implementation will use the command_description_color.

This method is called by the base implementation of the write_command_description() method.

Parameters

command The command.

◆ write_command_descriptions()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_descriptions ( )

inlineprotectedvirtual

Writes a list of available commands.

The base implementation calls write_command_description() for all commands.

This method is called by the base implementation of the write_command_list_usage_core() method.

◆ write_command_list_usage()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_list_usage ( const command_manager_type & manager )

inlinevirtual

Creates usage help for the specified command manager.

Parameters

manager The basic_command_manager.

◆ write_command_list_usage_core()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_list_usage_core ( )

inlineprotectedvirtual

Creates the usage help for a basic_command_manager instance.

This is the primary method used to generate usage help for the basic_command_manager class. It calls into the various other methods of this class, so overriding this method should not typically be necessary unless you wish to deviate from the order in which usage elements are written.

The base implementation writes the application description, followed by the list of commands, followed by a message indicating how to get help on a command. Which elements are included exactly can be influenced by the properties of this class.

◆ write_command_list_usage_footer()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_list_usage_footer ( )

inlineprotectedvirtual

Writes a footer after the list of commands.

The base implementation writes an instruction on how to get help for a command if the basic_command_manager::common_help_argument() method returns a non-empty string.

◆ write_command_list_usage_syntax()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_list_usage_syntax ( )

inlineprotectedvirtual

Writes the usage syntax for an application using subcommands.

The base implementation calls write_usage_syntax_prefix(), and adds to it a string like " <command> [arguments]".

This method is called by the base implementation of the write_command_list_usage_core() method.

◆ write_command_name()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_command_name ( string_view_type name )

inlineprotectedvirtual

Writes the name of a command.

The base implementation just writes the name.

This method is called by the base implementation of the write_command_description_header() method.

Parameters

name	The name of the command.

◆ write_default_value()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_default_value ( const argument_type & arg )

inlineprotectedvirtual

Writes the default value of an argument.

The base implementation writes a string like " Default value: value.", including the leading space.

This method is called by the base implementation of the write_argument_description_body() method if the include_default_value_in_description field is true and the argument has a default value.

Parameters

arg	The argument.

◆ write_more_info_message()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_more_info_message ( )

inlineprotectedvirtual

Writes a message telling to user how to get more detailed help.

The default implementation writes a message like "Run 'executable -Help' for more information." or "Run 'executable command -Help' for more information."

If the basic_command_line_parser::get_help_argument() method returns nullptr, nothing is written.

This method is called by the base implementation of the write_parser_usage_core() method if the requested help is not usage_help_request::full.

◆ write_multi_value_suffix()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_multi_value_suffix ( )

inlineprotectedvirtual

Writes a suffix that indicates an argument is a multi-value argument.

The default implementation returns a string like "...".

This method is called by the base implementation of the write_argument_syntax() method.

◆ write_optional_argument_syntax()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_optional_argument_syntax ( const argument_type & arg )

inlineprotectedvirtual

Writes the string used to indicate there are more arguments if the usage syntax was abbreviated.

The base implementation surrounds the result of the write_argument_syntax() method in square brackets.

This method is called by the base implementation of the write_parser_usage_syntax() method.

◆ write_parser_usage()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_parser_usage	(	const parser_type &	parser,
		usage_help_request	request = `usage_help_request::full`
	)

inlinevirtual

Creates usage help for the specified parser.

Parameters

parser	The basic_command_line_parser.
request	The parts of usage to write.

◆ write_parser_usage_core()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_parser_usage_core ( usage_help_request request )

inlineprotectedvirtual

Creates the usage help for a basic_command_line_parser instance.

This is the primary method used to generate usage help for the basic_command_line_parser class. It calls into the various other methods of this class, so overriding this method should not typically be necessary unless you wish to deviate from the order in which usage elements are written.

The base implementation writes the application description, followed by the usage syntax, followed by the class validator help messages, followed by a list of argument descriptions.

Parameters

request The parts of usage to write.

◆ write_parser_usage_syntax()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_parser_usage_syntax ( )

inlineprotectedvirtual

Writes the usage syntax for the application or subcommand.

This method is called by the base implementation of the write_parser_usage_core() method.

◆ write_positional_argument_name()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_positional_argument_name	(	string_view_type	name,
		string_view_type	prefix,
		std::optional< CharType >	separator
	)

inlineprotectedvirtual

Writes the name of a positional argument.

The base implementation surrounds the result of the write_argument_name() method in square brackets.

This method is called by the base implementation of the write_argument_syntax() method.

Parameters

name	The name of the argument.
prefix	The prefix of the argument.
separator	The argument name/value separator, or `std::nullopt` if the use_white_space_value_separator field and the basic_command_line_parser::allow_white_space_separator() method are both `true`.

◆ write_spacing()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_spacing ( size_t count )

inlineprotectedvirtual

Writes the specified amount of spaces.

Parameters

count The number of spaces.

◆ write_switch_value_description()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_switch_value_description ( string_view_type value_description )

inlineprotectedvirtual

Writes the value description of a switch argument for use in the argument description list.

The default implementation surrounds the value written by the write_value_description_for_description() method with angle brackets, to indicate that it is optional.

This method is called by the base implementation of the write_argument_description_header() methods.

Parameters

value_description The value description.

◆ write_usage_syntax_prefix()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_usage_syntax_prefix ( string_view_type command_name )

inlineprotectedvirtual

Writes the prefix for the usage syntax, including the executable name and, for subcommands, the command name.

The base implementation returns a string like "Usage: executable" or "Usage: executable command"

If color is enabled, this uses the usage_prefix_color for the "Usage:" portion of the string.

This method is called by the base implementation of the write_parser_usage_syntax() method.

Parameters

command_name The name of the executable or command.

◆ write_value_description()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_value_description ( string_view_type value_description )

inlineprotectedvirtual

Writes the value description of an argument.

The default implementation returns the value description surrounded by angle brackets, e.g. "<string>"

This method is called by the base implementation of the write_argument_syntax() method.

Parameters

value_description The value description of the argument.

◆ write_value_description_for_description()

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

virtual void ookii::basic_usage_writer< CharType, Traits, Alloc >::write_value_description_for_description ( string_view_type value_description )

inlineprotectedvirtual

Writes the value description of an argument for use in the argument description list.

The default implementation returns the value description surrounded by angle brackets, e.g. "<string>"

This method is called by the base implementation of the write_argument_description_header() and write_switch_value_description() methods.

Parameters

value_description The value description.

Member Data Documentation

◆ application_description_indent

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

size_t ookii::basic_usage_writer< CharType, Traits, Alloc >::application_description_indent {defaults::application_description_indent}

The level of indentation to use when writing the application description.

Note that the first line of the description is not indented.

This value has no effect if the output stream is not using a line_wrapping_streambuf.

◆ argument_description_color

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

const char* ookii::basic_usage_writer< CharType, Traits, Alloc >::argument_description_color {vt::text_format::foreground_green}

The color applied by the base implementation of the write_argument_description_header() method.

This should be the virtual terminal sequence for a color. The default value is ookii::vt::text_format::foreground_green.

The color will only be used if the use_color() method returns true.

If the string contains anything other than virtual terminal sequences, those parts will be included in the output, but only when the use_color() method returns true.

The portion of the string that has color will end with the value of color_reset.

With the base implementation, only the description header has color.

◆ argument_description_indent

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

size_t ookii::basic_usage_writer< CharType, Traits, Alloc >::argument_description_indent {defaults::argument_description_indent}

The level of indentation to use when writing argument descriptions.

Note that the first line of each argument is not indented.

This value has no effect if the output stream is not using a line_wrapping_streambuf.

◆ argument_description_list_filter

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

description_list_filter_mode ookii::basic_usage_writer< CharType, Traits, Alloc >::argument_description_list_filter {}

A value that indicates which arguments should be included in the list of argument descriptions.

The default value is description_list_filter_mode::information.

◆ argument_description_list_order

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

description_list_sort_mode ookii::basic_usage_writer< CharType, Traits, Alloc >::argument_description_list_order {}

A value that indicates the order of the arguments in the list of argument descriptions.

The default value is description_list_sort_mode::usage_order.

◆ blank_line_after_command_description

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::blank_line_after_command_description {true}

Indicates whether to add a blank line after each command's description.

The default value is true.

◆ blank_line_after_description

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::blank_line_after_description {true}

Indicates whether to add a blank line after each argument's description.

The default value is true.

◆ blank_line_after_syntax

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::blank_line_after_syntax {true}

Indicates whether to add a blank line after the usage syntax.

The default value is true.

◆ color_reset

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

const char* ookii::basic_usage_writer< CharType, Traits, Alloc >::color_reset {vt::text_format::default_format}

The sequence used to reset color applied a usage help element.

This is the virtual terminal sequence used to reset color. The default value is ookii::vt::text_format::default_format.

This value will only be used if the use_color() method returns true.

If the string contains anything other than virtual terminal sequences, those parts will be included in the output, but only when the use_color() method returns true.

◆ command_description_color

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

const char* ookii::basic_usage_writer< CharType, Traits, Alloc >::command_description_color {vt::text_format::foreground_green}

The color applied by the base implementation of the write_command_description_header() method.

This should be the virtual terminal sequence for a color. The default value is ookii::vt::text_format::foreground_green.

The color will only be used if the use_color() method returns true.

If the string contains anything other than virtual terminal sequences, those parts will be included in the output, but only when the use_color() method returns true.

The portion of the string that has color will end with the value of color_reset.

With the base implementation, only the description header has color.

◆ command_description_indent

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

int ookii::basic_usage_writer< CharType, Traits, Alloc >::command_description_indent {defaults::command_description_indent}

The level of indentation to use when writing the command descriptions.

Note that the first line of the syntax is not indented.

This value has no effect if the output stream is not using a line_wrapping_streambuf.

◆ error_color

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

const char* ookii::basic_usage_writer< CharType, Traits, Alloc >::error_color {vt::text_format::foreground_red}

The color applied by the write_error() method.

This should be the virtual terminal sequence for a color. The default value is ookii::vt::text_format::foreground_red.

The color will only be used if the use_color() method returns true.

If the string contains anything other than virtual terminal sequences, those parts will be included in the output, but only when the use_color() method returns true.

The portion of the string that has color will end with the value of color_reset.

◆ include_aliases_in_description

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::include_aliases_in_description {true}

Indicates whether to include the aliases of arguments in the description.

The default value is true.

◆ include_application_description

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::include_application_description {true}

Indicates whether to include the application description in the usage help.

The default value is true.

◆ include_default_value_in_description

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::include_default_value_in_description {true}

Indicates whether to include the default value of arguments in the description.

The default value is true.

◆ name_separator

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

string_type ookii::basic_usage_writer< CharType, Traits, Alloc >::name_separator {defaults::name_separator.data()}

The separator to use between names of arguments and commands.

The default value is ", ".

◆ syntax_indent

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

size_t ookii::basic_usage_writer< CharType, Traits, Alloc >::syntax_indent {defaults::syntax_indent}

The level of indentation to use when writing the usage syntax.

Note that the first line of the syntax is not indented.

This value has no effect if the output stream is not using a line_wrapping_streambuf.

◆ usage_prefix_color

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

const char* ookii::basic_usage_writer< CharType, Traits, Alloc >::usage_prefix_color {vt::text_format::foreground_cyan}

The color applied by the base implementation of the write_usage_syntax_prefix method.

This should be the virtual terminal sequence for a color. The default value is ookii::vt::text_format::foreground_cyan.

The color will only be used if the use_color() method returns true.

If the string contains anything other than virtual terminal sequences, those parts will be included in the output, but only when the use_color() method returns true.

The portion of the string that has color will end with the value of color_reset.

With the base implementation, only the "Usage:" portion of the string has color; the executable name does not.

◆ use_abbreviated_syntax

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::use_abbreviated_syntax {}

Indicates whether to list only positional arguments in the usage syntax.

The default value is false.

Abbreviated usage syntax only lists the positional arguments explicitly. After that, if there are any more arguments, it will just call the write_abbreviated_remaining_arguments() method. The user will have to refer to the description list to see the remaining possible arguments.

◆ use_short_names_for_syntax

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::use_short_names_for_syntax {}

When using parsing_mode::long_short, use short names in the usage syntax.

This has no effect when not using parsing_mode::long_short.

◆ use_white_space_value_separator

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

bool ookii::basic_usage_writer< CharType, Traits, Alloc >::use_white_space_value_separator {true}

Indicates whether to use white space as the argument name separator in the usage syntax.

If false, the separator specified in basic_parser_builder::argument_name_separator() is used instead. The default value is true.

If basic_parser_builder::allow_white_space_separator() is set to false, this value has no effect and the basic_parser_builder::argument_name_separator() is always used.

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

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

Classes

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

template<typename CharType, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>> class ookii::basic_usage_writer< CharType, Traits, Alloc >

Constructor & Destructor Documentation

◆ basic_usage_writer() [1/3]

◆ basic_usage_writer() [2/3]

◆ basic_usage_writer() [3/3]

Member Function Documentation

◆ command_manager()

◆ for_each_argument_in_description_order()

◆ parser()

◆ set_color()

◆ use_color()

◆ write_abbreviated_remaining_arguments()

◆ write_alias()

◆ write_aliases()

◆ write_application_description()

◆ write_argument_description() [1/2]

◆ write_argument_description() [2/2]

◆ write_argument_description_body()

◆ write_argument_description_header()

◆ write_argument_description_list_header()

◆ write_argument_descriptions()

◆ write_argument_name()

◆ write_argument_name_for_description()

◆ write_argument_syntax()

◆ write_available_commands_header()

◆ write_command_description() [1/2]

◆ write_command_description() [2/2]

◆ write_command_description_body()

◆ write_command_description_header()

◆ write_command_descriptions()

◆ write_command_list_usage()

◆ write_command_list_usage_core()

◆ write_command_list_usage_footer()

◆ write_command_list_usage_syntax()

◆ write_command_name()

◆ write_default_value()

◆ write_more_info_message()

◆ write_multi_value_suffix()

◆ write_optional_argument_syntax()

◆ write_parser_usage()

◆ write_parser_usage_core()

◆ write_parser_usage_syntax()

◆ write_positional_argument_name()

◆ write_spacing()

◆ write_switch_value_description()

◆ write_usage_syntax_prefix()

◆ write_value_description()

◆ write_value_description_for_description()

Member Data Documentation

◆ application_description_indent

◆ argument_description_color

◆ argument_description_indent

◆ argument_description_list_filter

◆ argument_description_list_order

◆ blank_line_after_command_description

◆ blank_line_after_description

◆ blank_line_after_syntax

◆ color_reset

◆ command_description_color

◆ command_description_indent

◆ error_color

◆ include_aliases_in_description

◆ include_application_description

◆ include_default_value_in_description

◆ name_separator

◆ syntax_indent

◆ usage_prefix_color

◆ use_abbreviated_syntax

◆ use_short_names_for_syntax

◆ use_white_space_value_separator

template<typename CharType, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
class ookii::basic_usage_writer< CharType, Traits, Alloc >