kaycxx::cli::command_handle Class Reference

Handle for a registered command. More...

#include <kaycxx/cli/command_handle.hpp>

Public Member Functions
std::string const &	name () const noexcept
	Returns the command name.
std::optional< std::string > const &	description () const noexcept
	Returns this command's configured description.
command_handle	command (std::string_view name, std::optional< std::string_view > description=std::nullopt)
	Registers a child command.
flag_handle	flag (std::string_view name, std::optional< std::string_view > description=std::nullopt)
	Registers a flag without a short alias.
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>
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>
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>
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>
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>
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>
parameters_handle< T >	parameters (std::string_view name, std::optional< std::string_view > description=std::nullopt)
	Registers a positional parameter list.
args	parse (int argc, char *argv[]) const
	Parses command-line arguments from this command as the starting command.
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.

Friends
class	args
class	command

Detailed Description

Handle for a registered command.

The handle does not own the command definition. It references data owned by the application and remains valid while that application exists.

Member Function Documentation

command()

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

inline

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_handle::description ( ) const

inlinenoexcept

Returns this command's configured description.

Returns

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

flag() [1/2]

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

inline

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]

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

inline

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_handle::name ( ) const

inlinenoexcept

Returns the command name.

Returns

Command name.

option() [1/2]

template<parseable_value T>

option_handle< T > kaycxx::cli::command_handle::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>

option_handle< T > kaycxx::cli::command_handle::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>

parameter_handle< T > kaycxx::cli::command_handle::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>

parameters_handle< T > kaycxx::cli::command_handle::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()

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

inline

Parses command-line arguments from this command as the starting command.

Parameters

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

Returns

Parsed command-line arguments.

print_help()

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

inline

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_handle::print_version ( std::ostream &  out = std::cout ) const

inline

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>

repeatable_option_handle< T > kaycxx::cli::command_handle::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>

repeatable_option_handle< T > kaycxx::cli::command_handle::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_handle.hpp