app.cpp File Reference

The application type: the parser itself. More...

#include <cerrno>
import cli11:formatter_fwd;
import std;

Classes
class	cli::app_t
	A command-line parser, a subcommand, or an option group. More...
class	cli::option_group_t
	An application specialised for grouping options. More...
struct	cli::detail::app_friend_t
	Grants the test suite access to cli::app_t's protected members. More...

Typedefs
using	cli::app_ptr_t = std::shared_ptr<app_t>
	Shared handle to an application or subcommand.

Enumerations
enum class	cli::detail::classifier_t : std::uint8_t {   none , positional_mark , short_ , long_ ,   windows_style , subcommand , subcommand_terminator }
	What a single command-line argument looks like. More...
enum class	cli::extras_mode_t : std::uint8_t {   error = 0 , error_immediately , ignore , assume_single_argument ,   assume_multiple_arguments , capture }
	What to do with command-line arguments that match nothing. More...
enum class	cli::config_extras_mode_t : std::uint8_t { error = 0 , ignore , ignore_all , capture }
	What to do with configuration-file entries that match nothing. More...
enum class	cli::prefix_command_mode_t : std::uint8_t { off = 0 , separator_only = 1 , on = 2 }
	When an unrecognised argument should stop parsing entirely. More...

Functions
auto	cli::failure_message::simple (const app_t *app, const error_t &e) -> std::string
	Prints a short one-line error message.
auto	cli::failure_message::help (const app_t *app, const error_t &e) -> std::string
	Prints the full help text alongside the error.
template<typename T> requires (!std::is_integral_v<T> || (sizeof(T) <= 1U))
auto	cli::detail::default_flag_modifiers (option_t *opt) -> option_t *
	Applies the default settings for a flag bound to a non-counting type.
template<typename T> requires (std::is_integral_v<T> && (sizeof(T) > 1U))
auto	cli::detail::default_flag_modifiers (option_t *opt) -> option_t *
	Applies the default settings for a flag bound to a counting type.
auto	cli::trigger_on (app_t *trigger_app, app_t *app_to_enable) -> void
	Enables one subcommand or option group when another is used.
auto	cli::trigger_on (app_t *trigger_app, std::vector< app_t * > apps_to_enable) -> void
	Enables several subcommands or option groups when another is used.
auto	cli::trigger_off (app_t *trigger_app, app_t *app_to_enable) -> void
	Disables one subcommand or option group when another is used.
auto	cli::trigger_off (app_t *trigger_app, std::vector< app_t * > apps_to_enable) -> void
	Disables several subcommands or option groups when another is used.
auto	cli::deprecate_option (option_t *opt, const std::string &replacement="") -> void
	Marks an option as deprecated.
auto	cli::deprecate_option (app_t *app, const std::string &option_name, const std::string &replacement="") -> void
	Marks a named option as deprecated.
auto	cli::deprecate_option (app_t &app, const std::string &option_name, const std::string &replacement="") -> void
	Marks a named option as deprecated.
auto	cli::retire_option (app_t *app, option_t *opt) -> void
	Marks an option as retired.
auto	cli::retire_option (app_t &app, option_t *opt) -> void
	Marks an option as retired.
auto	cli::retire_option (app_t *app, const std::string &option_name) -> void
	Marks a named option as retired.
auto	cli::retire_option (app_t &app, const std::string &option_name) -> void
	Marks a named option as retired.
auto	cli::detail::maybe_narrow (const char *str) -> const char *
	Passes a narrow string through unchanged.
auto	cli::detail::maybe_narrow (const wchar_t *str) -> std::string
	Narrows a wide string.
auto	cli::capture_extras (extras_mode_t mode) -> bool
	Reports whether an extras mode keeps unmatched arguments.

Detailed Description

The application type: the parser itself.

cli::app_t is the entry point. Construct one, describe the interface with add_option, add_flag, and add_subcommand, then call parse:

int main(int argc, char **argv)
{
    cli::app_t app{"my program"};
    std::string file;
    app.add_option("-f,--file", file, "the file to read")->required();
 
    try
    {
        app.parse(argc, argv);
    }
    catch (const cli::parse_error_t &e)
    {
        return app.exit(e);
    }
}

Note

Upstream CLI11 offers a CLI11_PARSE macro for the try/catch above. It has no equivalent here: macros are not exported across module boundaries, so the explicit form is the only one.

Subcommands are themselves app_t instances, so everything that works on the top-level parser works on a subcommand. Option groups are subcommands with no name, which is why one class covers all three roles.

Parsing runs in phases: arguments are classified, matched to options or subcommands, collected, then validated and dispatched to callbacks. The phase helpers are the _-prefixed private members near the end of the class.

Enumeration Type Documentation

classifier_t

enum class cli::detail::classifier_t : std::uint8_t

exportstrong

What a single command-line argument looks like.

Note

short_ and long_ carry trailing underscores because short and long are keywords.

Enumerator
none	Not recognised as any of the forms below.
positional_mark	The -- separator.
short_	A short option, such as -f.
long_	A long option, such as --file.
windows_style	A Windows-style option, such as /file.
subcommand	The name of a subcommand.
subcommand_terminator	The ++ subcommand terminator.

config_extras_mode_t

enum class cli::config_extras_mode_t : std::uint8_t

exportstrong

What to do with configuration-file entries that match nothing.

Note

The original had two enumerations for this, ConfigExtrasMode and config_extras_mode, with identical members. Lowercasing collapsed them into one, which is this.

Enumerator
error	Report an error.
ignore	Ignore the entry.
ignore_all	Ignore the entry and everything nested under it.
capture	Collect it for the caller to inspect.

extras_mode_t

enum class cli::extras_mode_t : std::uint8_t

exportstrong

What to do with command-line arguments that match nothing.

Enumerator
error	Report an error once parsing finishes.
error_immediately	Report an error as soon as one is seen.
ignore	Leave them in the remaining-arguments list.
assume_single_argument	Treat the next argument as this option's value.
assume_multiple_arguments	Treat every following argument as this option's values.
capture	Collect them for the caller to inspect.

prefix_command_mode_t

enum class cli::prefix_command_mode_t : std::uint8_t

exportstrong

When an unrecognised argument should stop parsing entirely.

Prefix-command mode hands everything from that point on to the caller, which is how a program forwards a trailing argument list to another tool.

Enumerator
off	Never stop early.
separator_only	Stop only at a --; anything else is an error.
on	Stop at the first unrecognised argument.

Function Documentation

capture_extras()

auto cli::capture_extras ( extras_mode_t mode ) -> bool

export

Reports whether an extras mode keeps unmatched arguments.

Parameters

mode	The mode to test.

Returns

true if unmatched arguments are retained rather than reported.

default_flag_modifiers() [1/2]

template<typename T>
requires (std::is_integral_v<T> && (sizeof(T) > 1U))

auto cli::detail::default_flag_modifiers ( option_t * opt ) -> option_t *

export

Applies the default settings for a flag bound to a counting type.

An integer wider than a byte is taken to be a counter, so repeated appearances sum rather than overwrite.

Parameters

opt	The option to configure.

Returns

opt, for chaining.

default_flag_modifiers() [2/2]

template<typename T>
requires (!std::is_integral_v<T> || (sizeof(T) <= 1U))

auto cli::detail::default_flag_modifiers ( option_t * opt ) -> option_t *

export

Applies the default settings for a flag bound to a non-counting type.

Parameters

opt	The option to configure.

Returns

opt, for chaining.

deprecate_option() [1/3]

auto cli::deprecate_option ( app_t & app, const std::string & option_name, const std::string & replacement = "" ) -> void

export

Marks a named option as deprecated.

Parameters

app	The application holding the option.
option_name	The option to mark.
replacement	The option to use instead, if there is one.

Exceptions

cli::option_not_found_t

If no option matches.

deprecate_option() [2/3]

auto cli::deprecate_option ( app_t * app, const std::string & option_name, const std::string & replacement = "" ) -> void

export

Marks a named option as deprecated.

Parameters

app	The application holding the option.
option_name	The option to mark.
replacement	The option to use instead, if there is one.

Exceptions

cli::option_not_found_t

If no option matches.

deprecate_option() [3/3]

auto cli::deprecate_option ( option_t * opt, const std::string & replacement = "" ) -> void

export

Marks an option as deprecated.

The option keeps working, but its help text records that it should no longer be used.

Parameters

opt	The option to mark.
replacement	The option to use instead, if there is one.

help()

auto cli::failure_message::help ( const app_t * app, const error_t & e ) -> std::string

export

Prints the full help text alongside the error.

Parameters

app	The application the error came from.
e	The error to describe.

Returns

The message to print.

maybe_narrow() [1/2]

auto cli::detail::maybe_narrow ( const char * str ) -> const char *

export

Passes a narrow string through unchanged.

Parameters

str	The string to pass through.

Returns

str.

maybe_narrow() [2/2]

auto cli::detail::maybe_narrow ( const wchar_t * str ) -> std::string

export

Narrows a wide string.

Parameters

str	The string to narrow.

Returns

The narrowed string.

retire_option() [1/4]

auto cli::retire_option ( app_t & app, const std::string & option_name ) -> void

export

Marks a named option as retired.

Parameters

app	The application holding the option.
option_name	The option to retire.

retire_option() [2/4]

auto cli::retire_option ( app_t & app, option_t * opt ) -> void

export

Marks an option as retired.

Parameters

app	The application holding the option.
opt	The option to retire.

retire_option() [3/4]

auto cli::retire_option ( app_t * app, const std::string & option_name ) -> void

export

Marks a named option as retired.

If no such option exists, a retired placeholder is added under that name.

Parameters

app	The application holding the option.
option_name	The option to retire.

retire_option() [4/4]

auto cli::retire_option ( app_t * app, option_t * opt ) -> void

export

Marks an option as retired.

A retired option is still accepted on the command line, but does nothing.

Parameters

app	The application holding the option.
opt	The option to retire.

simple()

auto cli::failure_message::simple ( const app_t * app, const error_t & e ) -> std::string

export

Prints a short one-line error message.

The default since CLI11 1.5.

Parameters

app	The application the error came from.
e	The error to describe.

Returns

The message to print.

trigger_off() [1/2]

auto cli::trigger_off ( app_t * trigger_app, app_t * app_to_enable ) -> void

export

Disables one subcommand or option group when another is used.

Parameters

trigger_app	The subcommand whose use fires the trigger.
app_to_enable	The subcommand to disable.

trigger_off() [2/2]

auto cli::trigger_off ( app_t * trigger_app, std::vector< app_t * > apps_to_enable ) -> void

export

Disables several subcommands or option groups when another is used.

Parameters

trigger_app	The subcommand whose use fires the trigger.
apps_to_enable	The subcommands to disable.

trigger_on() [1/2]

auto cli::trigger_on ( app_t * trigger_app, app_t * app_to_enable ) -> void

export

Enables one subcommand or option group when another is used.

Parameters

trigger_app	The subcommand whose use fires the trigger.
app_to_enable	The subcommand to enable.

trigger_on() [2/2]

auto cli::trigger_on ( app_t * trigger_app, std::vector< app_t * > apps_to_enable ) -> void

export

Enables several subcommands or option groups when another is used.

Parameters

trigger_app	The subcommand whose use fires the trigger.
apps_to_enable	The subcommands to enable.