Represents a command in the command-line interface. More...

#include <command.h>

Classes
struct	string_hash

Public Types
using	result_t = Result

using	option_t = option_t<result_t>

using	argument_t = argument_t<result_t>

using	handle_t = std::function<void(std::span<const char* const>, result_t&)>
	Function handle type for command execution.

Public Member Functions
template<void_handle< std::span< const char *const >, result_t & > Handle>
	command_t (std::string_view name, std::string_view description, Handle &&handle)
	Constructs a command with a name, description, and handler.

	command_t (std::string_view name, std::string_view description)
	Constructs a command with a name and description, without a handler.

std::string_view	name () const
	Gets the command name.

std::string_view	description () const
	Gets the command description.

const auto &	arguments () const
	Gets the list of positional arguments.

const auto &	options () const
	Gets the list of options.

const auto &	commands () const
	Gets the list of subcommands.

const std::string &	path () const
	Returns the full path of parent commands, excluding this command’s name.

bool	add_command (command_t &&command)
	Adds a subcommand.

bool	add_option (const option_t &option)
	Adds an option to the command.

void	add_argument (const argument_t &argument)
	Adds a positional argument.

void	process (const char const args, std::uint32_t argc, result_t &result)
	Processes command-line arguments.

void	process (std::span< const char *const > args, result_t &result)
	Processes command-line arguments.

void	show_help (std::ostream &out, std::size_t terminal_size=80) const
	Displays help text for this command.

void	clear_used ()
	Clears state.

Private Member Functions
std::uint32_t	process_option (std::string_view name, std::span< const char *const > args, std::uint32_t index, result_t &result)

void	check_options (result_t &result)

Private Attributes
std::string	m_path

std::string_view	m_name

std::string_view	m_description

handle_t	m_handle

std::vector< argument_t >	m_arguments

std::vector< option_t >	m_options

std::vector< command_t >	m_commands

std::unordered_map< std::string_view, std::uint32_t, string_hash >	m_cmd_map

std::unordered_map< std::string_view, std::uint32_t, string_hash >	m_long_options

std::unordered_map< char, std::uint32_t >	m_short_options

Detailed Description

template<extends_result>
class koutil::args::command_t< extends_result >

Represents a command in the command-line interface.

A command can contain subcommands, options, and arguments.

The order in which options, arguments, and subcommands are added determines their order in the help text. The order of arguments also defines the order in which they are expected on the command line.

Member Typedef Documentation

◆ argument_t

template<extends_result >

using koutil::args::command_t< extends_result >::argument_t = argument_t<result_t>

◆ handle_t

template<extends_result >

using koutil::args::command_t< extends_result >::handle_t = std::function<void(std::span<const char* const>, result_t&)>

Function handle type for command execution.

The handle is called when the parser encounters this command, and it runs before processing the command’s arguments, options, or subcommands.

◆ option_t

template<extends_result >

using koutil::args::command_t< extends_result >::option_t = option_t<result_t>

◆ result_t

template<extends_result >

using koutil::args::command_t< extends_result >::result_t = Result

Constructor & Destructor Documentation

◆ command_t() [1/2]

template<extends_result >

template<void_handle< std::span< const char *const >, result_t & > Handle>

koutil::args::command_t< extends_result >::command_t	(	std::string_view	name,
		std::string_view	description,
		Handle &&	handle )

inlineexplicit

Constructs a command with a name, description, and handler.

Template Parameters

Handle Callable matching void_handle<std::span<const char* const>, result_t&>.

Parameters

name	Command name.
description	Description shown in help.
handle	Function to execute when the command is invoked.

◆ command_t() [2/2]

template<extends_result >

koutil::args::command_t< extends_result >::command_t	(	std::string_view	name,
		std::string_view	description )

inlineexplicit

Constructs a command with a name and description, without a handler.

Parameters

name	Command name.
description	Command description.

Member Function Documentation

◆ add_argument()

template<extends_result Result>

void koutil::args::command_t< Result >::add_argument ( const argument_t & argument )

Adds a positional argument.

Parameters

argument Argument to add.

Note: The order of added arguments defines their expected order on the command line and their order in the help text.

◆ add_command()

template<extends_result Result>

bool koutil::args::command_t< Result >::add_command ( command_t< extends_result > && command )

Adds a subcommand.

Parameters

command Command to add.

Returns: True if added successfully.

Note: The order of added commands affects their order in the help text.

◆ add_option()

template<extends_result Result>

bool koutil::args::command_t< Result >::add_option ( const option_t & option )

Adds an option to the command.

Parameters

option Option to add.

Returns: True if added successfully.

Note: The order of added options affects their order in the help text.

◆ arguments()

template<extends_result >

const auto & koutil::args::command_t< extends_result >::arguments ( ) const

inlinenodiscard

Gets the list of positional arguments.

Returns: Arguments.

◆ check_options()

template<extends_result Result>

void koutil::args::command_t< Result >::check_options ( result_t & result )

private

◆ clear_used()

template<extends_result Result>

void koutil::args::command_t< Result >::clear_used ( )

Clears state.

◆ commands()

template<extends_result >

const auto & koutil::args::command_t< extends_result >::commands ( ) const

inlinenodiscard

Gets the list of subcommands.

Returns: Commands.

◆ description()

template<extends_result >

std::string_view koutil::args::command_t< extends_result >::description ( ) const

inlinenodiscard

Gets the command description.

Returns: Command description.

◆ name()

template<extends_result >

std::string_view koutil::args::command_t< extends_result >::name ( ) const

inlinenodiscard

Gets the command name.

Returns: Command name.

◆ options()

template<extends_result >

const auto & koutil::args::command_t< extends_result >::options ( ) const

inlinenodiscard

Gets the list of options.

Returns: Options.

◆ path()

template<extends_result >

const std::string & koutil::args::command_t< extends_result >::path ( ) const

inline

Returns the full path of parent commands, excluding this command’s name.

For example:

If this command is "library" under "program build", path() returns "program build".
For a top-level command, it returns an empty string.

◆ process() [1/2]

template<extends_result Result>

void koutil::args::command_t< Result >::process	(	const char const	args,
		std::uint32_t	argc,
		result_t &	result )

Processes command-line arguments.

Parameters

args	Argument array.
argc	Number of arguments.
result	Result object to update.

◆ process() [2/2]

template<extends_result Result>

void koutil::args::command_t< Result >::process	(	std::span< const char *const >	args,
		result_t &	result )

Processes command-line arguments.

Parameters

args	Argument span.
result	Result object to update.

◆ process_option()

template<extends_result Result>

std::uint32_t koutil::args::command_t< Result >::process_option	(	std::string_view	name,
		std::span< const char *const >	args,
		std::uint32_t	index,
		result_t &	result )

private

◆ show_help()

template<extends_result Result>

void koutil::args::command_t< Result >::show_help	(	std::ostream &	out,
		std::size_t	terminal_size = 80 ) const

Displays help text for this command.

Parameters

out	Output stream.
terminal_size	Terminal width for formatting.

Member Data Documentation

◆ m_arguments

template<extends_result >

std::vector<argument_t> koutil::args::command_t< extends_result >::m_arguments

private

◆ m_cmd_map

template<extends_result >

std::unordered_map<std::string_view, std::uint32_t, string_hash> koutil::args::command_t< extends_result >::m_cmd_map

private

◆ m_commands

template<extends_result >

std::vector<command_t> koutil::args::command_t< extends_result >::m_commands

private

◆ m_description

template<extends_result >

std::string_view koutil::args::command_t< extends_result >::m_description

private

◆ m_handle

template<extends_result >

handle_t koutil::args::command_t< extends_result >::m_handle

private

◆ m_long_options

template<extends_result >

std::unordered_map<std::string_view, std::uint32_t, string_hash> koutil::args::command_t< extends_result >::m_long_options

private

◆ m_name

template<extends_result >

std::string_view koutil::args::command_t< extends_result >::m_name

private

◆ m_options

template<extends_result >

std::vector<option_t> koutil::args::command_t< extends_result >::m_options

private

◆ m_path

template<extends_result >

std::string koutil::args::command_t< extends_result >::m_path

private

◆ m_short_options

template<extends_result >

std::unordered_map<char, std::uint32_t> koutil::args::command_t< extends_result >::m_short_options

private

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

include/koutil/args/command.h
include/koutil/args/help.h
include/koutil/args/command_impl.h

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ argument_t

◆ handle_t

◆ option_t

◆ result_t

Constructor & Destructor Documentation

◆ command_t() [1/2]

◆ command_t() [2/2]

Member Function Documentation

◆ add_argument()

◆ add_command()

◆ add_option()

◆ arguments()

◆ check_options()

◆ clear_used()

◆ commands()

◆ description()

◆ name()

◆ options()

◆ path()

◆ process() [1/2]

◆ process() [2/2]

◆ process_option()

◆ show_help()

Member Data Documentation

◆ m_arguments

◆ m_cmd_map

◆ m_commands

◆ m_description

◆ m_handle

◆ m_long_options

◆ m_name

◆ m_options

◆ m_path

◆ m_short_options