Common base class for an application and its commands. More...

#include <kaycxx/cli/command.hpp>

Inheritance diagram for kaycxx::cli::command:

Public Member Functions
	command (command const &)=delete
	Prevents copying command definitions.

command &	operator= (command const &)=delete
	Prevents copy-assigning command definitions.

virtual	~command ()=default
	Destroys this command and all definitions owned by it.

std::string const &	name () const noexcept
	Returns the command name.

std::optional< std::string > const &	description () const noexcept
	Returns this command's configured description.

cli::flag_handle	flag (std::string_view name, std::optional< std::string_view > description=std::nullopt)
	Registers a flag without a short alias.

cli::flag_handle	flag (std::string_view name, char alias, std::optional< std::string_view > description=std::nullopt)
	Registers a flag with a short alias.

template<parseable_value T>
cli::option_handle< T >	option (std::string_view name, std::string_view value_name, std::optional< std::string_view > description=std::nullopt)
	Registers an option without a short alias.

template<parseable_value T>
cli::option_handle< T >	option (std::string_view name, char alias, std::string_view value_name, std::optional< std::string_view > description=std::nullopt)
	Registers an option with a short alias.

template<parseable_value T>
cli::repeatable_option_handle< T >	repeatable_option (std::string_view name, std::string_view value_name, std::optional< std::string_view > description=std::nullopt)
	Registers a repeatable option without a short alias.

template<parseable_value T>
cli::repeatable_option_handle< T >	repeatable_option (std::string_view name, char alias, std::string_view value_name, std::optional< std::string_view > description=std::nullopt)
	Registers a repeatable option with a short alias.

template<parseable_value T>
cli::parameter_handle< T >	parameter (std::string_view name, std::optional< std::string_view > description=std::nullopt)
	Registers a single positional parameter.

template<parseable_value T>
cli::parameters_handle< T >	parameters (std::string_view name, std::optional< std::string_view > description=std::nullopt)
	Registers a positional parameter list.

cli::args	parse (int argc, char *argv[]) const
	Parses command line arguments.

int	print_help (std::ostream &out=std::cout) const
	Writes generated help output.

int	print_version (std::ostream &out=std::cout) const
	Writes generated version output.

Protected Member Functions
	command (std::string_view name, std::optional< std::string_view > description, command *parent)
	Creates a command definition.

	command (command &&other) noexcept
	Moves a command definition.

command_handle	add_command (std::string_view name, std::optional< std::string_view > description=std::nullopt)
	Registers a child command.

Friends
class	command_handle

Detailed Description

Common base class for an application and its commands.

A command owns all registered flags, options, positional parameters and child commands. Registration methods return lightweight handles to these owned definitions.

This class cannot be instantiated directly. Create an app and register commands through app::command() or command_handle::command().

Constructor & Destructor Documentation

◆ command() [1/2]

kaycxx::cli::command::command	(	std::string_view	name,
		std::optional< std::string_view >	description,
		command *	parent
	)

protected

Creates a command definition.

Parameters

name	Command name.
description	Optional command description.
parent	Parent command or null for the application.

◆ command() [2/2]

kaycxx::cli::command::command ( command && other )

protectednoexcept

Moves a command definition.

Parameters

other Command definition to move from.

Member Function Documentation

◆ add_command()

command_handle kaycxx::cli::command::add_command	(	std::string_view	name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

protected

Registers a child command.

Parameters

name	Command name.
description	Optional command description used by generated help output.

Returns: Handle for configuring and identifying the registered command.

Exceptions

std::invalid_argument When the name is already registered or this command has positional parameters.

◆ description()

std::optional< std::string > const & kaycxx::cli::command::description ( ) const

noexcept

Returns this command's configured description.

Returns: Command description or an empty optional if no description was configured.

◆ flag() [1/2]

cli::flag_handle kaycxx::cli::command::flag	(	std::string_view	name,
		char	alias,
		std::optional< std::string_view >	description = `std::nullopt`
	)

Registers a flag with a short alias.

Parameters

name	Long flag name without the leading `--`.
alias	Short flag alias without the leading `-`.
description	Optional human-readable flag description used by generated help output.

Returns: Handle used to query the parsed flag state.

Exceptions

std::invalid_argument When the long name or short alias conflicts with a switch on this command, an ancestor, or a descendant.

◆ flag() [2/2]

cli::flag_handle kaycxx::cli::command::flag	(	std::string_view	name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

Registers a flag without a short alias.

Parameters

name	Long flag name without the leading `--`.
description	Optional human-readable flag description used by generated help output.

Returns: Handle used to query the parsed flag state.

Exceptions

std::invalid_argument When the long name conflicts with a switch on this command, an ancestor, or a descendant.

◆ name()

std::string const & kaycxx::cli::command::name ( ) const

noexcept

Returns the command name.

Returns: Command name.

◆ option() [1/2]

template<parseable_value T>

cli::option_handle< T > kaycxx::cli::command::option	(	std::string_view	name,
		char	alias,
		std::string_view	value_name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

inline

Registers an option with a short alias.

Template Parameters

T	Parsed option value type.

Parameters

name	Long option name without the leading `--`.
alias	Short option alias without the leading `-`.
value_name	Placeholder name for the option value used by generated help output.
description	Optional human-readable option description used by generated help output.

Returns: Handle used to configure the option and query the parsed option value.

Exceptions

std::invalid_argument When the long name or short alias conflicts with a switch on this command, an ancestor, or a descendant.

◆ option() [2/2]

template<parseable_value T>

cli::option_handle< T > kaycxx::cli::command::option	(	std::string_view	name,
		std::string_view	value_name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

inline

Registers an option without a short alias.

Template Parameters

T	Parsed option value type.

Parameters

name	Long option name without the leading `--`.
value_name	Placeholder name for the option value used by generated help output.
description	Optional human-readable option description used by generated help output.

Returns: Handle used to configure the option and query the parsed option value.

Exceptions

std::invalid_argument When the long name conflicts with a switch on this command, an ancestor, or a descendant.

◆ parameter()

template<parseable_value T>

cli::parameter_handle< T > kaycxx::cli::command::parameter	(	std::string_view	name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

inline

Registers a single positional parameter.

Template Parameters

T	Parsed parameter value type.

Parameters

name	Placeholder name used by generated help output and parse errors.
description	Optional human-readable parameter description used by generated help output.

Returns: Handle used to configure the parameter and query the parsed parameter value.

◆ parameters()

template<parseable_value T>

cli::parameters_handle< T > kaycxx::cli::command::parameters	(	std::string_view	name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

inline

Registers a positional parameter list.

Template Parameters

T	Parsed parameter value type.

Parameters

name	Placeholder name used by generated help output and parse errors.
description	Optional human-readable parameter description used by generated help output.

Returns: Handle used to configure the parameter list and query the parsed values.

◆ parse()

cli::args kaycxx::cli::command::parse	(	int	argc,
		char *	argv[]
	)		const

Parses command line arguments.

Parameters

argc	Argument count as received by `main`.
argv	Argument values as received by `main`.

Positional arguments are stored without validation. They are validated and converted when first accessed through the returned argument collection or when args::validate() is called explicitly.

Returns: Parsed command-line arguments.

Exceptions

parse_error When a subcommand or switch is unknown, an option value is missing or invalid, or multiple actions are specified.

◆ print_help()

int kaycxx::cli::command::print_help ( std::ostream & out = std::cout ) const

Writes generated help output.

Parameters

out	Output stream receiving the generated help text. Defaults to standard output.

Returns: Suggested success exit code.

◆ print_version()

int kaycxx::cli::command::print_version ( std::ostream & out = std::cout ) const

Writes generated version output.

Parameters

out	Output stream receiving the generated version text. Defaults to standard output.

Returns: Suggested success exit code.

◆ repeatable_option() [1/2]

template<parseable_value T>

cli::repeatable_option_handle< T > kaycxx::cli::command::repeatable_option	(	std::string_view	name,
		char	alias,
		std::string_view	value_name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

inline

Registers a repeatable option with a short alias.

Template Parameters

T	Parsed option value type.

Parameters

name	Long option name without the leading `--`.
alias	Short option alias without the leading `-`.
value_name	Placeholder name for each option value used by generated help output.
description	Optional human-readable option description used by generated help output.

Returns: Handle used to configure the option and query all parsed option values.

Exceptions

std::invalid_argument When the long name or short alias conflicts with a switch on this command, an ancestor, or a descendant.

◆ repeatable_option() [2/2]

template<parseable_value T>

cli::repeatable_option_handle< T > kaycxx::cli::command::repeatable_option	(	std::string_view	name,
		std::string_view	value_name,
		std::optional< std::string_view >	description = `std::nullopt`
	)

inline

Registers a repeatable option without a short alias.

Template Parameters

T	Parsed option value type.

Parameters

name	Long option name without the leading `--`.
value_name	Placeholder name for each option value used by generated help output.
description	Optional human-readable option description used by generated help output.

Returns: Handle used to configure the option and query all parsed option values.

Exceptions

std::invalid_argument When the long name conflicts with a switch on this command, an ancestor, or a descendant.

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

kaycxx/cli/command.hpp

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ command() [1/2]

◆ command() [2/2]

Member Function Documentation

◆ add_command()

◆ description()

◆ flag() [1/2]

◆ flag() [2/2]

◆ name()

◆ option() [1/2]

◆ option() [2/2]

◆ parameter()

◆ parameters()

◆ parse()

◆ print_help()

◆ print_version()

◆ repeatable_option() [1/2]

◆ repeatable_option() [2/2]