Ookii.CommandLine for C++  2.0.0
Classes | Public Types | Public Member Functions | List of all members
ookii::basic_command_manager< CharType, Traits, Alloc > Class Template Reference

Manages registration, creation and invocation of subcommands for an application. More...

#include <ookii/subcommand.h>

Public Types

using builder_type = typename info_type::builder_type
 The concrete type of basic_parser_builder used.
 
using command_type = typename info_type::command_type
 The concrete type of basic_command used.
 
using command_with_custom_parsing_type = typename info_type::command_with_custom_parsing_type
 The concrete type of basic_command_with_custom_parsing used.
 
using configure_function = std::function< void(builder_type &)>
 The type of a function used to configure parser options for every command.
 
using info_type = command_info< CharType, Traits, Alloc >
 The concrete type of command_info used.
 
using stream_type = std::basic_ostream< CharType, Traits >
 The concrete type of output stream used.
 
using string_provider_type = basic_localized_string_provider< CharType, Traits, Alloc >
 The specialized type of basic_localized_string_provider used.
 
using string_type = typename info_type::string_type
 The concrete string type used.
 
using usage_writer_type = basic_usage_writer< CharType, Traits, Alloc >
 The concrete type of basic_usage_writer used.
 
using version_function = std::function< void()>
 The type of a function that displays version information.
 

Public Member Functions

 basic_command_manager (string_type application_name, bool case_sensitive=false, const std::locale &locale={}, const string_provider_type *string_provider=nullptr)
 Initializes a new instance of the basic_command_manager class. More...
 
template<typename T >
basic_command_manageradd_command (string_type name={}, string_type description={})
 Adds a command to the basic_command_manager. More...
 
basic_command_manageradd_version_command (version_function function)
 Adds the standard version command. More...
 
basic_command_manageradd_win32_version_command ()
 Adds the standard version argument, using version information from the VERSIONINFO resource. More...
 
const string_typeapplication_name () const noexcept
 Gets the name of the application containing the command.
 
bool case_sensitive () const noexcept
 Gets a value that indicates whether command names are case sensitive. More...
 
auto commands () const noexcept
 Gets a view of all the commands.
 
const string_typecommon_help_argument () const
 Gets the name of a help argument, including prefix, that is used by all subcommands.
 
basic_command_managercommon_help_argument (string_type name_with_prefix)
 Sets the name of a help argument, including prefix, that is used by all subcommands. More...
 
basic_command_managerconfigure_parser (configure_function function)
 Sets a function that can be used to configure parser options for every command. More...
 
std::unique_ptr< command_typecreate_command (const string_type &name, std::span< const CharType *const > args, usage_writer_type *usage=nullptr) const
 Creates an instance of a command based on the specified arguments. More...
 
std::unique_ptr< command_typecreate_command (int argc, const CharType *const argv[], usage_writer_type *usage=nullptr) const
 Creates an instance of a command based on the specified arguments. More...
 
std::unique_ptr< command_typecreate_command (std::span< const CharType *const > args, usage_writer_type *usage=nullptr) const
 Creates an instance of a command based on the specified arguments. More...
 
builder_type create_parser_builder (const info_type &command) const
 Creates a basic_parser_builder for a specified command. More...
 
const string_typedescription () const
 Gets the description that will be shown before the command list usage help.
 
basic_command_managerdescription (string_type description)
 Sets a description that will be shown before the command list usage help. More...
 
const info_typeget_command (const string_type &name) const
 Gets information about a subcommand by name. More...
 
const std::locale & locale () const noexcept
 Gets the locale used to parse argument values and to format strings.
 
std::optional< int > run_command (const string_type &name, std::span< const CharType *const > args, usage_writer_type *usage=nullptr) const
 Creates an instance of a command based on the specified arguments, and runs the command. More...
 
std::optional< int > run_command (int argc, const CharType *const argv[], usage_writer_type *usage=nullptr) const
 Creates an instance of a command based on the specified arguments, and runs the command. More...
 
std::optional< int > run_command (std::span< const CharType *const > args, usage_writer_type *usage=nullptr) const
 Creates an instance of a command based on the specified arguments, and runs the command. More...
 
const string_provider_typestring_provider () const noexcept
 Gets the basic_localized_string_provider implementation used to get strings for error messages etc. More...
 
void write_usage (usage_writer_type *usage=nullptr) const
 Writes usage help about the available commands. 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_manager< CharType, Traits, Alloc >

Manages registration, creation and invocation of subcommands for an application.

To use subcommands in your application, you define a class that derives from basic_command for each one. Then, you register each class with the basic_command_manager using the add_command() method.

You can then invoke create_command() to create an instance of a command type based on the provided arguments, or run_command() to create a command and immediately run it.

Several typedefs for common character types are provided:

Type Definition
ookii::command_manager ookii::basic_command_manager<char>
ookii::wcommand_manager ookii::basic_command_manager<wchar_t>
Template Parameters
CharTypeThe 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.
TraitsThe character traits to use for strings. Defaults to std::char_traits<CharType>.
AllocThe allocator to use for strings. Defaults to std::allocator<CharType>.

Constructor & Destructor Documentation

◆ basic_command_manager()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
ookii::basic_command_manager< CharType, Traits, Alloc >::basic_command_manager ( string_type  application_name,
bool  case_sensitive = false,
const std::locale &  locale = {},
const string_provider_type string_provider = nullptr 
)
inline

Initializes a new instance of the basic_command_manager class.

Parameters
application_nameThe name of the application containing the command. This name is used when printing usage help.
case_sensitiveIndicates whether command names and argument names are case sensitive. The default is false.
localeThe locale to use when converting argument values. The default is a copy of the current global locale.
string_providerA pointer to an implementation of the basic_localized_string_provider class that will be used to get strings for error messages etc., or nullptr to use the default string provider. If not nullptr, this pointer must remain valid as long as the basic_command_manager exists.

Member Function Documentation

◆ add_command()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename T >
basic_command_manager& ookii::basic_command_manager< CharType, Traits, Alloc >::add_command ( string_type  name = {},
string_type  description = {} 
)
inline

Adds a command to the basic_command_manager.

Template Parameters
Thetype of the command, which must derive from basic_command<CharType>.
Parameters
nameThe name used to invoke the command. If left blank, it will be determined by the static name() method of the command type, or the type name if there is no such method.
descriptionThe description of the command, used for usage help. If left blank, it will be determined by the static description() method of the command type. If no such method exist, the description will be blank.
Returns
A reference to the basic_command_manager.

◆ add_version_command()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
basic_command_manager& ookii::basic_command_manager< CharType, Traits, Alloc >::add_version_command ( version_function  function)
inline

Adds the standard version command.

This method adds a command with the default name "version", which invokes the specified function when invoked.

You can specify a different name, as well as a custom description, using the basic_localized_string_provider class.

Parameters
functionA function that displays version information. This will be called when the command is invoked.
Returns
A reference to the basic_command_manager.

◆ add_win32_version_command()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
basic_command_manager& ookii::basic_command_manager< CharType, Traits, Alloc >::add_win32_version_command ( )
inline

Adds the standard version argument, using version information from the VERSIONINFO resource.

Warning
This function is only available when compiling for Windows.

This method adds a command with the default name "version", which when invoked will read the VERSION_INFO resource of the current executable, and print the product name, version and optionally copyright information to the standard output. If these resources don't exist, the text "Unknown version" is shown.

You can specify a different name, as well as a custom description, using the basic_localized_string_provider class.

Returns
A reference to the basic_command_manager.

◆ case_sensitive()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
bool ookii::basic_command_manager< CharType, Traits, Alloc >::case_sensitive ( ) const
inlinenoexcept

Gets a value that indicates whether command names are case sensitive.

Returns
true if command names are case sensitive; otherwise, false.

If command names are case sensitive, argument names for the commands are too unless this is overridden by the command.

◆ common_help_argument()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
basic_command_manager& ookii::basic_command_manager< CharType, Traits, Alloc >::common_help_argument ( string_type  name_with_prefix)
inline

Sets the name of a help argument, including prefix, that is used by all subcommands.

When set, the command list usage help will include an instruction for the user to invoke a command with this argument to get information about that command.

This must be set manually because the command manager cannot know the name, capitalization or prefix used by each command without instantiating every command. Keep in mind that the automatically added help argument will adjust its name based on the capitalization of the other arguments.

Parameters
name_with_prefixThe name of the argument, including its prefix. For example, "-Help".
Returns
A reference to the basic_command_manager.

◆ configure_parser()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
basic_command_manager& ookii::basic_command_manager< CharType, Traits, Alloc >::configure_parser ( configure_function  function)
inline

Sets a function that can be used to configure parser options for every command.

The configure parser function, if set, is invoked on the basic_parser_builder instance created before that instance is passed to the command class's constructor.

Use this to configure global options (such as parsing mode) that apply to all commands.

While this could be used to define global arguments shared by every command, generally it's recommended to use a common base class for that.

Parameters
functionThe function to invoke to configure the parser.
Returns
A reference to the basic_command_manager.

◆ create_command() [1/3]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
std::unique_ptr<command_type> ookii::basic_command_manager< CharType, Traits, Alloc >::create_command ( const string_type name,
std::span< const CharType *const >  args,
usage_writer_type usage = nullptr 
) const
inline

Creates an instance of a command based on the specified arguments.

If the command could not be found, a list of commands will be written. If an error occurred parsing the arguments, an error message and usage help for the command will be written.

The args span must contain only the arguments for the command; the application name and command name are assumed to be stripped already.

Parameters
nameThe name of the command.
argsA span containing the arguments for the command.
usageA basic_usage_writer instance that will be used to format errors and usage help.
Returns
An instance of the subcommand type, or nullptr if the an error occurred.

◆ create_command() [2/3]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
std::unique_ptr<command_type> ookii::basic_command_manager< CharType, Traits, Alloc >::create_command ( int  argc,
const CharType *const  argv[],
usage_writer_type usage = nullptr 
) const
inline

Creates an instance of a command based on the specified arguments.

If no command was specified or the command could not be found, a list of commands will be written. If an error occurred parsing the arguments, an error message and usage help for the command will be written.

Warning
The first argument is assumed to be the application executable name, and is skipped. The second argument must be the command name.
Parameters
argcThe number of arguments.
argvThe arguments.
usageA basic_usage_writer instance that will be used to format errors and usage help.
Returns
An instance of the subcommand type, or nullptr if the an error occurred.

◆ create_command() [3/3]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
std::unique_ptr<command_type> ookii::basic_command_manager< CharType, Traits, Alloc >::create_command ( std::span< const CharType *const >  args,
usage_writer_type usage = nullptr 
) const
inline

Creates an instance of a command based on the specified arguments.

If no command was specified or the command could not be found, a list of commands will be written. If an error occurred parsing the arguments, an error message and usage help for the command will be written.

Warning
The args span must not contain the application name; the first argument must be the command name.
Parameters
argsA span containing the arguments.
usageA basic_usage_writer instance that will be used to format errors and usage help.
Returns
An instance of the subcommand type, or nullptr if the an error occurred.

◆ create_parser_builder()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
builder_type ookii::basic_command_manager< CharType, Traits, Alloc >::create_parser_builder ( const info_type command) const
inline

Creates a basic_parser_builder for a specified command.

The parser builder will be initialized with the name and description of the command, as well the locale and case sensitive value of the basic_command_manager.

Parameters
commandThe command_info for the command.
Returns
A parser builder with suitable defaults for the command.

◆ description()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
basic_command_manager& ookii::basic_command_manager< CharType, Traits, Alloc >::description ( string_type  description)
inline

Sets a description that will be shown before the command list usage help.

Parameters
descriptionThe description.
Returns
A reference to the basic_command_manager.

◆ get_command()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
const info_type* ookii::basic_command_manager< CharType, Traits, Alloc >::get_command ( const string_type name) const
inline

Gets information about a subcommand by name.

Parameters
nameThe name of the subcommand.
Returns
An instance of command_info describing the command, or nullptr if there is no command with that name.

◆ run_command() [1/3]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
std::optional<int> ookii::basic_command_manager< CharType, Traits, Alloc >::run_command ( const string_type name,
std::span< const CharType *const >  args,
usage_writer_type usage = nullptr 
) const
inline

Creates an instance of a command based on the specified arguments, and runs the command.

If the command could not be found, a list of commands will be written. If an error occurred parsing the arguments, an error message and usage help for the command will be written.

The args span must contain only the arguments for the command; the application name and command name are assumed to be stripped already.

Parameters
nameThe name of the command.
argsA span containing the arguments for the command.
usageA basic_usage_writer instance that will be used to format errors and usage help.
Returns
The exit code of the command, or std::nullopt if the command could not be created.

◆ run_command() [2/3]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
std::optional<int> ookii::basic_command_manager< CharType, Traits, Alloc >::run_command ( int  argc,
const CharType *const  argv[],
usage_writer_type usage = nullptr 
) const
inline

Creates an instance of a command based on the specified arguments, and runs the command.

If no command was specified or the command could not be found, a list of commands will be written. If an error occurred parsing the arguments, an error message and usage help for the command will be written.

Warning
The first argument is assumed to be the application executable name, and is skipped. The second argument must be the command name.
Parameters
argcThe number of arguments.
argvThe arguments.
usageA basic_usage_writer instance that will be used to format errors and usage help.
Returns
The exit code of the command, or std::nullopt if the command could not be created.

◆ run_command() [3/3]

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
std::optional<int> ookii::basic_command_manager< CharType, Traits, Alloc >::run_command ( std::span< const CharType *const >  args,
usage_writer_type usage = nullptr 
) const
inline

Creates an instance of a command based on the specified arguments, and runs the command.

If no command was specified or the command could not be found, a list of commands will be written. If an error occurred parsing the arguments, an error message and usage help for the command will be written.

Warning
The args span must not contain the application name; the first argument must be the command name.
Parameters
argsA span containing the arguments.
usageA basic_usage_writer instance that will be used to format errors and usage help.
Returns
The exit code of the command, or std::nullopt if the command could not be created.

◆ string_provider()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
const string_provider_type& ookii::basic_command_manager< CharType, Traits, Alloc >::string_provider ( ) const
inlinenoexcept

Gets the basic_localized_string_provider implementation used to get strings for error messages etc.

Returns
An instance of a class derived from the basic_localized_string_provider class.

◆ write_usage()

template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
void ookii::basic_command_manager< CharType, Traits, Alloc >::write_usage ( usage_writer_type usage = nullptr) const
inline

Writes usage help about the available commands.

Parameters
usageA basic_usage_writer instance that will be used to format the usage help.

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