kaycxx::cli::command Class Reference

Defines and parses a command line interface. More...

#include <kaycxx/cli/command.hpp>

Public Member Functions
	command (std::string_view name, command_options options=command_options())
	Creates a command definition.
	command (command const &)=delete
	Prevents copying command definitions.
command &	operator= (command const &)=delete
	Prevents copy-assigning command definitions.
	command (command &&other) noexcept=default
	Moves a command definition.
command &	operator= (command &&other) noexcept=default
	Move-assigns a command definition.
std::string const &	name () const noexcept
	Returns the command name.
std::optional< std::string > const &	version () const noexcept
	Returns the configured command version.
std::optional< std::string > const &	author () const noexcept
	Returns the configured author name.
std::optional< std::string > const &	email () const noexcept
	Returns the configured author email address.
std::optional< std::string > const &	bugs () const noexcept
	Returns the email address or URL to which to report bugs to.
std::optional< std::string > const &	copyright () const noexcept
	Returns the configured copyright notice.
std::optional< std::string > const &	license () const noexcept
	Returns the configured license text.
std::optional< std::string > const &	description () const noexcept
	Returns the configured command 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 () const
	Writes generated help output to standard output.
int	print_help (std::ostream &out) const
	Writes generated help output.
int	print_version () const
	Writes generated version output to standard output.
int	print_version (std::ostream &out) const
	Writes generated version output.

Detailed Description

Defines and parses a command line interface.

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

The handles remain valid as long as the command object exists.

Constructor & Destructor Documentation

command() [1/2]

kaycxx::cli::command::command ( std::string_view  name, command_options  options = command_options()  )

explicit

Creates a command definition.

Parameters

name	Program name used in generated output and error messages.
options	Optional command metadata.

command() [2/2]

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

defaultnoexcept

Moves a command definition.

Parameters

other

Command definition to move from.

Member Function Documentation

author()

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

noexcept

Returns the configured author name.

Returns

Author name or an empty optional if no author was configured.

bugs()

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

noexcept

Returns the email address or URL to which to report bugs to.

Returns

Email address or URL to which to report bugs to.

copyright()

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

noexcept

Returns the configured copyright notice.

Returns

Copyright notice or an empty optional if no copyright notice was configured.

description()

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

noexcept

Returns the configured command description.

Returns

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

email()

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

noexcept

Returns the configured author email address.

Returns

Email address or an empty optional if no email address 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 is already registered.

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 is already registered.

license()

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

noexcept

Returns the configured license text.

Returns

License text or an empty optional if no license text was configured.

name()

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

noexcept

Returns the command name.

Returns

Command name.

operator=()

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

defaultnoexcept

Move-assigns a command definition.

Parameters

other

Command definition to move from.

Returns

This command definition.

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 is already registered.

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 is already registered.

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 switch is unknown, an option value is missing or invalid, or multiple actions are specified.

print_help() [1/2]

int kaycxx::cli::command::print_help

(

)

const

Writes generated help output to standard output.

Returns

Exit code suitable for returning from main.

print_help() [2/2]

int kaycxx::cli::command::print_help

(

std::ostream &

out

)

const

Writes generated help output.

Parameters

out	Output stream receiving the generated help text.

Returns

Exit code suitable for returning from main.

print_version() [1/2]

int kaycxx::cli::command::print_version

(

)

const

Writes generated version output to standard output.

Returns

Exit code suitable for returning from main.

print_version() [2/2]

int kaycxx::cli::command::print_version

(

std::ostream &

out

)

const

Writes generated version output.

Parameters

out	Output stream receiving the generated version text.

Returns

Exit code suitable for returning from main.

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 is already registered.

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 is already registered.

version()

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

noexcept

Returns the configured command version.

Returns

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

---

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

• kaycxx/cli/command.hpp