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

#include <ookii/shell_command.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_shell_command used.

using	info_type = shell_command_info< CharType, Traits, Alloc >
	The concrete type of shell_command_info used.

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

using	string_type = typename info_type::string_type
	The concrete string type used.

using	usage_options_type = basic_shell_command_usage_options< CharType, Traits, Alloc >
	The concrete type of basic_shell_command_usage_options used.

Public Member Functions
	basic_shell_command_manager (string_type application_name, bool case_sensitive=false, const std::locale &locale={})
	Initializes a new instance of the basic_shell_command_manager class. More...

template<typename T >
basic_shell_command_manager &	add_command (string_type name={}, string_type description={})
	Adds a command to the basic_shell_command_manager. More...

auto	commands () const noexcept
	Gets a view of all the commands. More...

template<typename Iterator >
std::unique_ptr< command_type >	create_command (const string_type &name, Iterator begin, Iterator end, const usage_options_type &options={}) const
	Creates an instance of the specified command, parsing the specified arguments. More...

template<typename Range >
std::unique_ptr< command_type >	create_command (const string_type &name, Range range, const usage_options_type &options={}) const
	Creates an instance of the specified command, parsing the specified arguments. More...

template<typename T >
std::unique_ptr< command_type >	create_command (const string_type &name, std::initializer_list< T > args, const usage_options_type &options={}) const
	Creates an instance of the specified command, parsing the specified arguments. More...

std::unique_ptr< command_type >	create_command (int argc, const CharType *const argv[], const usage_options_type &options={}) const
	Creates an instance of a command based on the specified arguments. More...

template<typename Iterator >
std::unique_ptr< command_type >	create_command (Iterator begin, Iterator end, const usage_options_type &options={}) const
	Creates an instance of a command based on the specified arguments. More...

template<typename Range >
std::unique_ptr< command_type >	create_command (Range range, const usage_options_type &options={}) const
	Creates an instance of a command based on the specified arguments. More...

template<typename T >
std::unique_ptr< command_type >	create_command (std::initializer_list< T > args, const usage_options_type &options={}) 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 info_type *	get_command (const string_type &name) const
	Gets information about a shell command by name. More...

template<typename Iterator >
int	run_command (const string_type &name, Iterator begin, Iterator end, const usage_options_type &options={}) const
	Creates an instance of the specified command, parsing the specified arguments, and runs the command. More...

template<typename Range >
int	run_command (const string_type &name, Range range, const usage_options_type &options={}) const
	Creates an instance of the specified command, parsing the specified arguments, and runs the command. More...

template<typename T >
int	run_command (const string_type &name, std::initializer_list< T > args, const usage_options_type &options={}) const
	Creates an instance of the specified command, parsing the specified arguments, and runs the command. More...

int	run_command (int argc, const CharType *const argv[], const usage_options_type &options={}) const
	Creates an instance of a command based onthe specified arguments, and runs the command. More...

template<typename Iterator >
int	run_command (Iterator begin, Iterator end, const usage_options_type &options={}) const
	Creates an instance of a command based onthe specified arguments, and runs the command. More...

template<typename Range >
int	run_command (Range range, const usage_options_type &options={}) const
	Creates an instance of a command based onthe specified arguments, and runs the command. More...

template<typename T >
int	run_command (std::initializer_list< T > args, const usage_options_type &options={}) const
	Creates an instance of a command based onthe specified arguments, and runs the command. More...

void	write_usage (const usage_options_type &options={}) const
	Writes usage help about the available commands. More...

Static Public Attributes
static constexpr int	error_return_code = 1
	The error exit code used by run_shell_command() if no command name was supplied or thesupplied command could not be found.

Detailed Description

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

Manages registration, creation and invocation of shell commands for an application.

To use shell commands in your application, you define a class that derives from basic_shell_command for each one. Then, you register each class with the basic_shell_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::shell_command_manager`	`ookii::basic_shell_command_manager<char>`
`ookii::wshell_command_manager`	`ookii::basic_shell_command_manager<wchar_t>`

Template Parameters

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

Constructor & Destructor Documentation

◆ basic_shell_command_manager()

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

ookii::basic_shell_command_manager< CharType, Traits, Alloc >::basic_shell_command_manager	(	string_type	application_name,
		bool	case_sensitive = `false`,
		const std::locale &	locale = `{}`
	)

inline

Initializes a new instance of the basic_shell_command_manager class.

Parameters

application_name	The name of the application containing the command. This name is used when printing usage help.
case_sensitive	Indicates whether command names and argument names are case sensitive. The default is false.
locale	The locale to use when converting argument values. The default is a copy of the current global locale.

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_shell_command_manager& ookii::basic_shell_command_manager< CharType, Traits, Alloc >::add_command	(	string_type	name = `{}`,
		string_type	description = `{}`
	)

inline

Adds a command to the basic_shell_command_manager.

Template Parameters

The	type of the command, which must derive from basic_shell_command<CharType>.

Parameters

name	The 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.
description	The 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.

◆ commands()

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

auto ookii::basic_shell_command_manager< CharType, Traits, Alloc >::commands ( ) const

inlinenoexcept

Gets a view of all the commands.

Warning: Calling this function may cause build errors on certain versions of clang.

◆ create_command() [1/7]

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

template<typename Iterator >

std::unique_ptr<command_type> ookii::basic_shell_command_manager< CharType, Traits, Alloc >::create_command	(	const string_type &	name,
		Iterator	begin,
		Iterator	end,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of the specified command, parsing 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.

Warning: The passed arguments must not include the application name or the command name.

Template Parameters

Iterator The type of iterator for the arguments.

Parameters

name	The name of the shell command.
begin	An iterator to the first argument.
end	An iterator after the last argument.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: An instance of the shell command type, or nullptr if the an error occurred.

◆ create_command() [2/7]

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

template<typename Range >

std::unique_ptr<command_type> ookii::basic_shell_command_manager< CharType, Traits, Alloc >::create_command	(	const string_type &	name,
		Range	range,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of the specified command, parsing 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.

Warning: The passed arguments must not include the application name or the command name.

Template Parameters

Range The type of a range containing the arguments.

Parameters

name	The name of the shell command.
range	A range containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: An instance of the shell command type, or nullptr if the an error occurred.

◆ create_command() [3/7]

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

template<typename T >

std::unique_ptr<command_type> ookii::basic_shell_command_manager< CharType, Traits, Alloc >::create_command	(	const string_type &	name,
		std::initializer_list< T >	args,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of the specified command, parsing 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.

Warning: The passed arguments must not include the application name or the command name.

Template Parameters

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

Parameters

name	The name of the shell command.
args	An initializer list containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: An instance of the shell command type, or nullptr if the an error occurred.

◆ create_command() [4/7]

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_shell_command_manager< CharType, Traits, Alloc >::create_command	(	int	argc,
		const CharType *const	argv[],
		const usage_options_type &	options = `{}`
	)		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

argc	The number of arguments.
argv	The arguments..
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: An instance of the shell command type, or nullptr if the an error occurred.

◆ create_command() [5/7]

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

template<typename Iterator >

std::unique_ptr<command_type> ookii::basic_shell_command_manager< CharType, Traits, Alloc >::create_command	(	Iterator	begin,
		Iterator	end,
		const usage_options_type &	options = `{}`
	)		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 passed arguments must not include the application name, but the first argument must be the command name.

Template Parameters

Iterator The type of iterator for the arguments.

Parameters

begin	An iterator to the first argument.
end	An iterator after the last argument.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: An instance of the shell command type, or nullptr if the an error occurred.

◆ create_command() [6/7]

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

template<typename Range >

std::unique_ptr<command_type> ookii::basic_shell_command_manager< CharType, Traits, Alloc >::create_command	(	Range	range,
		const usage_options_type &	options = `{}`
	)		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 passed arguments must not include the application name, but the first argument must be the command name.

Template Parameters

Range The type of a range containing the arguments.

Parameters

range	A range containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: An instance of the shell command type, or nullptr if the an error occurred.

◆ create_command() [7/7]

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

template<typename T >

std::unique_ptr<command_type> ookii::basic_shell_command_manager< CharType, Traits, Alloc >::create_command	(	std::initializer_list< T >	args,
		const usage_options_type &	options = `{}`
	)		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 passed arguments must not include the application name, but the first argument must be the command name.

Template Parameters

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

Parameters

args	An initializer list containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: An instance of the shell command 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_shell_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_shell_command_manager.

Parameters

command The shell_command_info for the command.

Returns: A parser builder with suitable defaults for the command.

◆ 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_shell_command_manager< CharType, Traits, Alloc >::get_command ( const string_type & name ) const

inline

Gets information about a shell command by name.

Parameters

name	The name of the shell command.

Returns: An instance of shell_command_info describing the command, or nullptr if there is no command with that name.

◆ run_command() [1/7]

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

template<typename Iterator >

int ookii::basic_shell_command_manager< CharType, Traits, Alloc >::run_command	(	const string_type &	name,
		Iterator	begin,
		Iterator	end,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of the specified command, parsing 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.

Warning: The passed arguments must not include the application name or the command name.

Template Parameters

Iterator The type of iterator for the arguments.

Parameters

name	The name of the shell command.
begin	An iterator to the first argument.
end	An iterator after the last argument.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: The exit code of the command, or error_return_code if the command could not be created.

◆ run_command() [2/7]

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

template<typename Range >

int ookii::basic_shell_command_manager< CharType, Traits, Alloc >::run_command	(	const string_type &	name,
		Range	range,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of the specified command, parsing 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.

Warning: The passed arguments must not include the application name or the command name.

Template Parameters

Range The type of a range containing the arguments.

Parameters

name	The name of the shell command.
range	A range containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: The exit code of the command, or error_return_code if the command could not be created.

◆ run_command() [3/7]

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

template<typename T >

int ookii::basic_shell_command_manager< CharType, Traits, Alloc >::run_command	(	const string_type &	name,
		std::initializer_list< T >	args,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of the specified command, parsing 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.

Warning: The passed arguments must not include the application name or the command name.

Template Parameters

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

Parameters

name	The name of the shell command.
args	An initializer list containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: The exit code of the command, or error_return_code if the command could not be created.

◆ run_command() [4/7]

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

int ookii::basic_shell_command_manager< CharType, Traits, Alloc >::run_command	(	int	argc,
		const CharType *const	argv[],
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of a command based onthe 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..
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: The exit code of the command, or error_return_code if the command could not be created.

◆ run_command() [5/7]

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

template<typename Iterator >

int ookii::basic_shell_command_manager< CharType, Traits, Alloc >::run_command	(	Iterator	begin,
		Iterator	end,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of a command based onthe 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 passed arguments must not include the application name, but the first argument must be the command name.

Template Parameters

Iterator The type of iterator for the arguments.

Parameters

begin	An iterator to the first argument.
end	An iterator after the last argument.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: The exit code of the command, or error_return_code if the command could not be created.

◆ run_command() [6/7]

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

template<typename Range >

int ookii::basic_shell_command_manager< CharType, Traits, Alloc >::run_command	(	Range	range,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of a command based onthe 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 passed arguments must not include the application name, but the first argument must be the command name.

Template Parameters

Range The type of a range containing the arguments.

Parameters

range	A range containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: The exit code of the command, or error_return_code if the command could not be created.

◆ run_command() [7/7]

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

template<typename T >

int ookii::basic_shell_command_manager< CharType, Traits, Alloc >::run_command	(	std::initializer_list< T >	args,
		const usage_options_type &	options = `{}`
	)		const

inline

Creates an instance of a command based onthe 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 passed arguments must not include the application name, but the first argument must be the command name.

Template Parameters

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

Parameters

args	An initializer list containing the arguments.
options	A basic_shell_command_usage_options instance that will be used to format errors and usage help.

Returns: The exit code of the command, or error_return_code if the command could not be created.

◆ write_usage()

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

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

inline

Writes usage help about the available commands.

Parameters

options A basic_shell_command_usage_options instance that will be used to format the usage help.

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

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

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

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

Constructor & Destructor Documentation

◆ basic_shell_command_manager()

Member Function Documentation

◆ add_command()

◆ commands()

◆ create_command() [1/7]

◆ create_command() [2/7]

◆ create_command() [3/7]

◆ create_command() [4/7]

◆ create_command() [5/7]

◆ create_command() [6/7]

◆ create_command() [7/7]

◆ create_parser_builder()

◆ get_command()

◆ run_command() [1/7]

◆ run_command() [2/7]

◆ run_command() [3/7]

◆ run_command() [4/7]

◆ run_command() [5/7]

◆ run_command() [6/7]

◆ run_command() [7/7]

◆ write_usage()

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