Manages registration, creation and invocation of subcommands for an application.
More...
|
| 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_manager & | add_command (string_type name={}, string_type description={}) |
| Adds a command to the basic_command_manager. More...
|
|
basic_command_manager & | add_version_command (version_function function) |
| Adds the standard version command. More...
|
|
basic_command_manager & | add_win32_version_command () |
| Adds the standard version argument, using version information from the VERSIONINFO resource. More...
|
|
const string_type & | application_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_type & | common_help_argument () const |
| Gets the name of a help argument, including prefix, that is used by all subcommands.
|
|
basic_command_manager & | common_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_manager & | configure_parser (configure_function function) |
| Sets a function that can be used to configure parser options for every command. More...
|
|
std::unique_ptr< command_type > | create_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_type > | create_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_type > | create_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_type & | description () const |
| Gets the description that will be shown before the command list usage help.
|
|
basic_command_manager & | description (string_type description) |
| Sets a description that will be shown before the command list usage help. More...
|
|
const info_type * | get_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_type & | string_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...
|
|
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:
- Template Parameters
-
CharType | The character type used for arguments and other strings. Only char and wchar_t are supported. Defaults to wchar_t if _UNICODE is defined, otherwise to char . |
Traits | The character traits to use for strings. Defaults to std::char_traits<CharType> . |
Alloc | The allocator to use for strings. Defaults to std::allocator<CharType> . |
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
function | A function that displays version information. This will be called when the command is invoked. |
- Returns
- A reference to the basic_command_manager.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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_prefix | The name of the argument, including its prefix. For example, "-Help". |
- Returns
- A reference to the basic_command_manager.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
function | The function to invoke to configure the parser. |
- Returns
- A reference to the basic_command_manager.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
name | The name of the command. |
args | A span containing the arguments for the command. |
usage | A 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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
argc | The number of arguments. |
argv | The arguments. |
usage | A 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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
args | A span containing the arguments. |
usage | A 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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
name | The name of the command. |
args | A span containing the arguments for the command. |
usage | A 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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
argc | The number of arguments. |
argv | The arguments. |
usage | A 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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
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
-
args | A span containing the arguments. |
usage | A 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.