cli::app_t Class Reference

A command-line parser, a subcommand, or an option group. More...

Inheritance diagram for cli::app_t:

Public Member Functions
auto	_move_option (option_t *opt, app_t *app) -> void
	Moves an option from one application to another.
Basic
	app_t (std::string app_description="", std::string app_name="")
	Constructs a top-level application.
	app_t (const app_t &)=delete
auto	operator= (const app_t &) -> app_t &=delete
auto	ensure_utf8 (char **argv) -> char **
	Converts argv to UTF-8 on Windows; does nothing elsewhere.
auto	callback (std::function< void()> app_callback) -> app_t *
	Sets the callback run once everything has been parsed and processed.
auto	final_callback (std::function< void()> app_callback) -> app_t *
	Sets the callback run once everything has been processed.
auto	parse_complete_callback (std::function< void()> pc_callback) -> app_t *
	Sets the callback run once parsing has finished.
auto	preparse_callback (std::function< void(std::size_t)> pp_callback) -> app_t *
	Sets the callback run before parsing starts.
auto	name (std::string app_name="") -> app_t *
	Sets the application or subcommand name.
auto	alias (std::string app_name) -> app_t *
	Adds an alternative name this subcommand answers to.
auto	allow_extras (bool allow=true) -> app_t *
	Accepts unmatched arguments instead of reporting them.
auto	allow_extras (extras_mode_t allow) -> app_t *
	Sets what happens to unmatched arguments.
auto	required (bool require=true) -> app_t *
	Requires this subcommand to be used.
auto	disabled (bool disable=true) -> app_t *
	Disables this subcommand or option group.
auto	silent (bool silence=true) -> app_t *
	Hides this subcommand from the processed subcommand list.
auto	allow_non_standard_option_names (bool allowed=true) -> app_t *
	Accepts non-standard option names such as -single_dash_flag.
auto	allow_subcommand_prefix_matching (bool allowed=true) -> app_t *
	Lets a subcommand be matched by a unique prefix of its name.
auto	disabled_by_default (bool disable=true) -> app_t *
	Makes clear leave this subcommand disabled.
auto	enabled_by_default (bool enable=true) -> app_t *
	Makes clear leave this subcommand enabled.
auto	immediate_callback (bool immediate=true) -> app_t *
	Runs this subcommand's callback as soon as it finishes parsing.
auto	validate_positionals (bool validate=true) -> app_t *
	Validates positionals before assigning them.
auto	validate_optional_arguments (bool validate=true) -> app_t *
	Validates optional vector arguments before assigning them.
auto	allow_config_extras (bool allow=true) -> app_t *
	Accepts unmatched configuration entries instead of reporting them.
auto	allow_config_extras (config_extras_mode_t mode) -> app_t *
	Sets what happens to unmatched configuration entries.
auto	prefix_command (bool is_prefix=true) -> app_t *
	Stops parsing at the first unrecognised argument.
auto	prefix_command (prefix_command_mode_t mode) -> app_t *
	Sets when parsing stops early.
auto	ignore_case (bool value=true) -> app_t *
	Makes name matching case-insensitive. Subcommands inherit this.
auto	allow_windows_style_options (bool value=true) -> app_t *
	Accepts Windows-style options such as /opt.
auto	positionals_at_end (bool value=true) -> app_t *
	Requires positionals to appear after every option.
auto	configurable (bool value=true) -> app_t *
	Lets this subcommand be triggered from a configuration file.
auto	ignore_underscore (bool value=true) -> app_t *
	Makes name matching ignore underscores. Subcommands inherit this.
auto	formatter (std::shared_ptr< formatter_base_t > fmt) -> app_t *
	Replaces the help formatter.
auto	formatter_fn (std::function< std::string(const app_t *, std::string, app_format_mode_t)> fmt) -> app_t *
	Replaces the help formatter with a callable.
auto	config_formatter (std::shared_ptr< config_t > fmt) -> app_t *
	Replaces the configuration reader and writer.
auto	parsed () const -> bool
	Reports whether this subcommand appeared on the command line.
auto	option_defaults () -> option_defaults_t *
	Returns the settings newly added options inherit.
Extras for subclassing
virtual auto	pre_callback () -> void
	Hook run after parsing but before the callbacks.
Post parsing
auto	count (std::string option_name) const -> std::size_t
	Returns how many times an option was used.
auto	get_subcommands () const -> const std::vector< app_t * > &
	Returns the subcommands that were used, in command-line order.
auto	get_subcommands (const std::function< bool(const app_t *)> &filter) const -> std::vector< const app_t * >
	Returns the subcommands matching a filter, as defined.
auto	get_subcommands (const std::function< bool(app_t *)> &filter) -> std::vector< app_t * >
	Returns the subcommands matching a filter, as defined.
auto	got_subcommand (const app_t *subcom) const -> bool
	Reports whether a subcommand was used.
auto	got_subcommand (std::string subcommand_name) const noexcept -> bool
	Reports whether a named subcommand was used.
auto	excludes (option_t *opt) -> app_t *
	Forbids an option from being used alongside this subcommand.
auto	excludes (app_t *app) -> app_t *
	Forbids a subcommand from being used alongside this one.
auto	needs (option_t *opt) -> app_t *
	Requires an option to be used alongside this subcommand.
auto	needs (app_t *app) -> app_t *
	Requires a subcommand to be used alongside this one.
auto	remove_excludes (option_t *opt) -> bool
	Drops an option exclusion.
auto	remove_excludes (app_t *app) -> bool
	Drops a subcommand exclusion.
auto	remove_needs (option_t *opt) -> bool
	Drops an option requirement.
auto	remove_needs (app_t *app) -> bool
	Drops a subcommand requirement.

Protected Member Functions
	app_t (std::string app_description, std::string app_name, app_t *parent)
	Constructs a subcommand.
auto	_validate () const -> void
	Checks the option set for conflicts.
auto	_configure () -> void
	Prepares the subcommand tree for parsing.
auto	run_callback (bool final_mode=false, bool suppress_final_callback=false) -> void
	Runs this application's callback, and its subcommands', bottom up.
auto	_valid_subcommand (const std::string &current, bool ignore_used=true) const -> bool
	Reports whether a token names a usable subcommand.
auto	_recognize (const std::string &current, bool ignore_used_subcommands=true) const -> detail::classifier_t
	Classifies one command-line argument.
auto	_process_config_file () -> void
	Reads and applies the configuration file. Main application only.
auto	_process_config_file (const std::string &config_file, bool throw_error) -> bool
	Reads and applies one configuration file.
auto	_process_env () -> void
	Fills options from environment variables. Runs on every subcommand.
auto	_process_callbacks (callback_priority_t priority) -> void
	Runs the option callbacks at one priority. Runs on every subcommand.
auto	_process_help_flags (callback_priority_t priority, bool trigger_help=false, bool trigger_all_help=false) const -> void
	Handles any help flags that were used.
auto	_process_requirements () -> void
	Checks required options and cross-requirements, including selected subcommands.
auto	_process () -> void
	Runs every post-parse phase in order.
auto	_process_extras () -> void
	Reports anything left over that should not be.
auto	increment_parsed () -> void
	Increments the parse counter here and on nameless subcommands.
auto	_parse (std::vector< std::string > &args) -> void
	Parses a list of arguments.
auto	_parse (std::vector< std::string > &&args) -> void
	Parses a list of arguments.
auto	_parse_stream (std::istream &input) -> void
	Parses a stream as a configuration file.
auto	_parse_config (const std::vector< config_item_t > &args) -> void
	Applies a set of configuration entries.
auto	_parse_single_config (const config_item_t &item, std::size_t level=0) -> bool
	Applies one configuration entry.
auto	_add_flag_like_result (option_t *op, const config_item_t &item, const std::vector< std::string > &inputs) -> bool
	Stores a configuration entry against a flag-like option.
auto	_parse_single (std::vector< std::string > &args, bool &positional_only) -> bool
	Parses one argument, which may consume several.
auto	_count_remaining_positionals (bool required_only=false) const -> std::size_t
	Counts the positionals still waiting for values.
auto	_has_remaining_positionals () const -> bool
	Reports whether any positional is still waiting for values.
auto	_parse_positional (std::vector< std::string > &args, bool halt_on_subcommand) -> bool
	Parses a positional argument, walking up the tree as needed.
auto	_find_subcommand (const std::string &subc_name, bool ignore_disabled, bool ignore_used) const noexcept -> app_t *
	Finds a subcommand by name.
auto	_parse_subcommand (std::vector< std::string > &args) -> bool
	Parses a subcommand and everything it consumes.
auto	_parse_arg (std::vector< std::string > &args, detail::classifier_t current_type, bool local_processing_only) -> bool
	Parses an option argument sitting at the front of the list.
auto	_trigger_pre_parse (std::size_t remaining_args) -> void
	Runs the pre-parse callback, if it has not already run.
auto	_get_fallthrough_parent () noexcept -> app_t *
	Returns the application to fall through to.
auto	_get_fallthrough_parent () const noexcept -> const app_t *
	Returns the application to fall through to.
auto	_compare_subcommand_names (const app_t &subcom, const app_t &base) const -> const std::string &
	Returns the first name two subcommands share.
auto	_move_to_missing (detail::classifier_t val_type, const std::string &val) -> void
	Records an argument that matched nothing.

Protected Attributes
Basics
std::string	name_ {}
	Subcommand name, or program name; taken from the parser when empty.
std::string	description_ {}
	Description of this program or subcommand.
extras_mode_t	allow_extras_ {extras_mode_t::error}
	What to do with unmatched command-line arguments. Inheritable.
config_extras_mode_t	allow_config_extras_ {config_extras_mode_t::ignore}
	What to do with unmatched configuration entries. Inheritable.
prefix_command_mode_t	prefix_command_ {prefix_command_mode_t::off}
	Whether an unrecognised argument stops parsing. Inheritable.
bool	has_automatic_name_ {false}
	Whether the name was taken from the command line rather than set.
bool	required_ {false}
	Whether this subcommand must be used; ignored for the main app.
bool	disabled_ {false}
	Whether this subcommand is disabled; ignored for the main app.
bool	pre_parse_called_ {false}
	Whether pre_parse_callback_ has already fired.
bool	immediate_callback_ {false}
	Whether the callback runs on parse completion, before help and configuration files are handled. Inheritable.
std::function< void(std::size_t)>	pre_parse_callback_ {}
	Runs before parsing starts, given the argument count.
std::function< void()>	parse_complete_callback_ {}
	Runs once parsing has finished.
std::function< void()>	final_callback_ {}
	Runs once all processing has finished.
Options
option_defaults_t	option_defaults_ {}
	Settings newly added options inherit. Inheritable.
std::vector< option_ptr_t >	options_ {}
	The options owned by this application.
Config
option_t *	config_ptr_ {nullptr}
	The option naming a configuration file, if one was added.
std::shared_ptr< config_t >	config_formatter_ {std::make_shared<config_toml_t>()}
	Reads and writes configuration files. Inheritable, shared by pointer.

Subcommands
enum class	startup_mode_t : std::uint8_t { stable , enabled , disabled }
	Whether clear leaves this subcommand enabled or disabled. More...
std::vector< app_ptr_t >	subcommands_ {}
	The subcommands owned by this application.
bool	ignore_case_ {false}
	Whether subcommand name matching ignores case. Inheritable.
bool	ignore_underscore_ {false}
	Whether subcommand name matching ignores underscores. Inheritable.
bool	fallthrough_ {false}
	Whether options may fall through to a parent command.
bool	subcommand_fallthrough_ {true}
	Whether a later subcommand may be triggered from within this one.
bool	allow_windows_style_options_
	Whether /opt is accepted as an option form.
bool	positionals_at_end_ {false}
	Whether positionals must come after every option. Not inheritable.
startup_mode_t	default_startup {startup_mode_t::stable}
	What clear does to this subcommand's enabled state.
bool	configurable_ {false}
	Whether this subcommand can be triggered from a configuration file. Inheritable.
bool	validate_positionals_ {false}
	Whether positionals are validated before being assigned. Inheritable.
bool	validate_optional_arguments_ {false}
	Whether optional vector arguments are validated before being assigned. Inheritable.
bool	silent_ {false}
	Whether this subcommand is hidden from the subcommand list.
bool	allow_non_standard_options_ {false}
	Whether non-standard option names such as -single_dash_flag are accepted.
bool	allow_prefix_matching_ {false}
	Whether a subcommand may be matched by a unique prefix of its name.
std::uint32_t	parsed_ {0U}
	How many times this command or subcommand has been parsed.
std::size_t	require_subcommand_min_ {0}
	Smallest number of subcommands that must be used. Not inheritable.
std::size_t	require_subcommand_max_ {0}
	Largest number of subcommands accepted; 0 is unlimited. Inheritable.
std::size_t	require_option_min_ {0}
	Smallest number of options that must be used. Not inheritable.
std::size_t	require_option_max_ {0}
	Largest number of options accepted; 0 is unlimited. Not inheritable.
app_t *	parent_ {nullptr}
	The parent application, if this is a subcommand.
std::string	group_ {"SUBCOMMANDS"}
	The help group this subcommand is listed under. Inheritable.
std::vector< std::string >	aliases_ {}
	Alternative names this subcommand answers to.
auto	add_subcommand (std::string subcommand_name="", std::string subcommand_description="") -> app_t *
	Adds a subcommand.
auto	add_subcommand (app_ptr_t subcom) -> app_t *
	Adds an already-constructed application as a subcommand.
auto	remove_subcommand (app_t *subcom) -> bool
	Removes a subcommand from this application.
auto	get_subcommand (const app_t *subcom) const -> app_t *
	Finds a subcommand by pointer.
auto	get_subcommand (std::string subcom) const -> app_t *
	Finds a subcommand by name.
auto	get_subcommand_no_throw (std::string subcom) const noexcept -> app_t *
	Finds a subcommand by name, without throwing.
auto	get_subcommand (int index=0) const -> app_t *
	Finds a subcommand by position.
auto	get_subcommand_ptr (app_t *subcom) const -> app_ptr_t
	Finds a subcommand by pointer and returns an owning handle.
auto	get_subcommand_ptr (std::string subcom) const -> app_ptr_t
	Finds a subcommand by name and returns an owning handle.
auto	get_subcommand_ptr (int index=0) const -> app_ptr_t
	Finds a subcommand by position and returns an owning handle.
auto	get_option_group (std::string group_name) const -> app_t *
	Finds an option group by name.
auto	count () const -> std::size_t
	Returns how many times this subcommand was used.
auto	count_all () const -> std::size_t
	Returns how many arguments were consumed by options and subcommands.
auto	group (std::string group_name) -> app_t *
	Sets the help group this subcommand is listed under.
auto	require_subcommand () -> app_t *
	Requires at least one subcommand to be used.
auto	require_subcommand (int value) -> app_t *
	Requires a given number of subcommands.
auto	require_subcommand (std::size_t min, std::size_t max) -> app_t *
	Requires a number of subcommands within a range.
auto	require_option () -> app_t *
	Requires at least one option to be used.
auto	require_option (int value) -> app_t *
	Requires a given number of options.
auto	require_option (std::size_t min, std::size_t max) -> app_t *
	Requires a number of options within a range.
auto	fallthrough (bool value=true) -> app_t *
	Lets unrecognised options fall through to the parent command.
auto	subcommand_fallthrough (bool value=true) -> app_t *
	Lets a parent's subcommands be recognised from within this one.
	operator bool () const
	Reports whether this subcommand appeared on the command line.

Parsing
using	missing_t = std::vector<std::pair<detail::classifier_t, std::string>>
	Arguments that matched nothing, paired with how they were classified.
missing_t	missing_ {}
	Arguments that matched nothing. Extra detail is stripped on return from parse.
std::vector< option_t * >	parse_order_ {}
	The options that were used, in the order they appeared.
std::vector< app_t * >	parsed_subcommands_ {}
	The subcommands that were used, in the order they appeared.
std::set< app_t * >	exclude_subcommands_ {}
	Subcommands that may not be used alongside this one.
std::set< option_t * >	exclude_options_ {}
	Options that may not be used alongside this subcommand.
std::set< app_t * >	need_subcommands_ {}
	Subcommands this one requires. Not mutual: they do not require this one.
std::set< option_t * >	need_options_ {}
	Options this subcommand requires. Not mutual.
auto	clear () -> void
	Discards everything collected by a previous parse.
auto	parse (int argc, const char *const *argv) -> void
	Parses the command line.
auto	parse (int argc, const wchar_t *const *argv) -> void
	Parses a wide command line.
auto	parse (std::string commandline, bool program_name_included=false) -> void
	Parses a whole command line held in one string.
auto	parse (std::wstring commandline, bool program_name_included=false) -> void
	Parses a whole wide command line held in one string.
auto	parse (std::vector< std::string > &args) -> void
	Parses a list of arguments, in reverse order.
auto	parse (std::vector< std::string > &&args) -> void
	Parses a list of arguments, in reverse order.
auto	parse_from_stream (std::istream &input) -> void
	Parses arguments read from a stream as a configuration file.
auto	failure_message (std::function< std::string(const app_t *, const error_t &)> function) -> void
	Sets how an error is rendered by exit.
auto	exit (const error_t &e, std::ostream &out=std::cout, std::ostream &err=std::cerr) const -> int
	Prints an error and returns the exit code to give the process.

Getters
enum class	name_match_t : std::uint8_t { none = 0 , exact = 1 , prefix = 2 }
	How closely a name matched. More...
auto	get_formatter () const -> std::shared_ptr< formatter_base_t >
	Returns the help formatter.
auto	get_config_formatter () const -> std::shared_ptr< config_t >
	Returns the configuration reader and writer.
auto	get_config_formatter_base () const -> std::shared_ptr< config_base_t >
	Returns the configuration converter as a config_base_t.
auto	get_description () const -> const std::string &
	Returns the description shown in help output.
auto	description (std::string app_description) -> app_t *
	Sets the description shown in help output.
auto	get_options (const std::function< bool(const option_t *)> &filter={}) const -> std::vector< const option_t * >
	Returns the options matching a filter.
auto	get_options (const std::function< bool(option_t *)> &filter={}) -> std::vector< option_t * >
	Returns the options matching a filter.
auto	get_option_no_throw (std::string option_name) noexcept -> option_t *
	Finds an option by name, without throwing.
auto	get_option_no_throw (std::string option_name) const noexcept -> const option_t *
	Finds an option by name, without throwing.
auto	get_option (std::string option_name) const -> const option_t *
	Finds an option by name.
auto	get_option (std::string option_name) -> option_t *
	Finds an option by name.
auto	operator[] (const std::string &option_name) const -> const option_t *
	Finds an option by name.
auto	operator[] (const char *option_name) const -> const option_t *
	Finds an option by name.
auto	get_ignore_case () const -> bool
	Reports whether name matching ignores case.
auto	get_ignore_underscore () const -> bool
	Reports whether name matching ignores underscores.
auto	get_fallthrough () const -> bool
	Reports whether options fall through to the parent command.
auto	get_subcommand_fallthrough () const -> bool
	Reports whether a parent's subcommands are recognised here.
auto	get_allow_windows_style_options () const -> bool
	Reports whether Windows-style options are accepted.
auto	get_positionals_at_end () const -> bool
	Reports whether positionals must appear after every option.
auto	get_configurable () const -> bool
	Reports whether this subcommand can be triggered from a configuration file.
auto	get_group () const -> const std::string &
	Returns the help group this subcommand is listed under.
auto	get_usage () const -> std::string
	Returns the usage line.
auto	get_footer () const -> std::string
	Returns the footer.
auto	get_require_subcommand_min () const -> std::size_t
	Returns the smallest number of subcommands that must be used.
auto	get_require_subcommand_max () const -> std::size_t
	Returns the largest number of subcommands accepted.
auto	get_require_option_min () const -> std::size_t
	Returns the smallest number of options that must be used.
auto	get_require_option_max () const -> std::size_t
	Returns the largest number of options accepted.
auto	get_prefix_command () const -> bool
	Reports whether parsing stops at an unrecognised argument.
auto	get_prefix_command_mode () const -> prefix_command_mode_t
	Returns when parsing stops early.
auto	get_allow_extras () const -> bool
	Reports whether unmatched arguments are accepted.
auto	get_allow_extras_mode () const -> extras_mode_t
	Returns what happens to unmatched arguments.
auto	get_required () const -> bool
	Reports whether this subcommand must be used.
auto	get_disabled () const -> bool
	Reports whether this subcommand is disabled.
auto	get_silent () const -> bool
	Reports whether this subcommand is hidden from the processed list.
auto	get_allow_non_standard_option_names () const -> bool
	Reports whether non-standard option names are accepted.
auto	get_allow_subcommand_prefix_matching () const -> bool
	Reports whether subcommands may be matched by a name prefix.
auto	get_immediate_callback () const -> bool
	Reports whether the callback runs as soon as parsing finishes.
auto	get_disabled_by_default () const -> bool
	Reports whether clear leaves this subcommand disabled.
auto	get_enabled_by_default () const -> bool
	Reports whether clear leaves this subcommand enabled.
auto	get_validate_positionals () const -> bool
	Reports whether positionals are validated before assignment.
auto	get_validate_optional_arguments () const -> bool
	Reports whether optional vector arguments are validated before assignment.
auto	get_allow_config_extras () const -> config_extras_mode_t
	Returns what happens to unmatched configuration entries.
auto	get_help_ptr () -> option_t *
	Returns the help flag.
auto	get_help_ptr () const -> const option_t *
	Returns the help flag.
auto	get_help_all_ptr () const -> const option_t *
	Returns the expanded-help flag.
auto	get_config_ptr () -> option_t *
	Returns the option naming a configuration file.
auto	get_config_ptr () const -> const option_t *
	Returns the option naming a configuration file.
auto	get_version_ptr () -> option_t *
	Returns the version flag.
auto	get_version_ptr () const -> const option_t *
	Returns the version flag.
auto	get_parent () -> app_t *
	Returns the parent application.
auto	get_parent () const -> const app_t *
	Returns the parent application.
auto	get_name () const -> const std::string &
	Returns this application's name.
auto	get_aliases () const -> const std::vector< std::string > &
	Returns the alternative names this subcommand answers to.
auto	clear_aliases () -> app_t *
	Removes every alias.
auto	get_display_name (bool with_aliases=false) const -> std::string
	Returns the name shown in help output.
auto	check_name (std::string name_to_check) const -> bool
	Reports whether a name refers to this subcommand.
auto	check_name_detail (std::string name_to_check) const -> name_match_t
	Reports how closely a name matches this subcommand.
auto	get_groups () const -> std::vector< std::string >
	Returns the option groups defined here, in definition order.
auto	parse_order () const -> const std::vector< option_t * > &
	Returns the options that were used, in command-line order.
auto	remaining (bool recurse=false) const -> std::vector< std::string >
	Returns the arguments that matched nothing.
auto	remaining_for_passthrough (bool recurse=false) const -> std::vector< std::string >
	Returns the unmatched arguments, ready to hand to another program.
auto	remaining_size (bool recurse=false) const -> std::size_t
	Returns how many arguments matched nothing, excluding the -- separator.

Help
std::string	usage_ {}
	Usage line placed after the description. Inheritable.
std::function< std::string()>	usage_callback_ {}
	Generates the usage line, when one is not set directly.
std::string	footer_ {}
	Footer placed after all options. Inheritable.
std::function< std::string()>	footer_callback_ {}
	Generates the footer, when one is not set directly.
option_t *	help_ptr_ {nullptr}
	The help option, if one was added. Inheritable.
option_t *	help_all_ptr_ {nullptr}
	The expanded-help option, if one was added. Inheritable.
option_t *	version_ptr_ {nullptr}
	The version option, if one was added.
std::shared_ptr< formatter_base_t >	formatter_ {std::make_shared<formatter_t>()}
	Renders help output. Inheritable, and shared by pointer.
std::function< std::string(const app_t *, const error_t &)>	failure_message_
	Renders an error into the message printed by exit. Inheritable.
auto	usage (std::string usage_string) -> app_t *
	Sets the usage line shown after the description.
auto	usage (std::function< std::string()> usage_function) -> app_t *
	Sets a callable producing the usage line.
auto	footer (std::string footer_string) -> app_t *
	Sets the footer shown after all options.
auto	footer (std::function< std::string()> footer_function) -> app_t *
	Sets a callable producing the footer.
auto	config_to_str () const -> std::string
	Writes the current values out as configuration text.
auto	config_to_str (config_output_mode_t mode, bool write_description=false) const -> std::string
	Writes the current values out as configuration text.
auto	config_to_str (bool default_also, bool write_description=false) const -> std::string
	Writes the current values out as configuration text.
auto	help (std::string prev="", app_format_mode_t mode=app_format_mode_t::normal) const -> std::string
	Renders the help page using the configured formatter.
auto	version () const -> std::string
	Renders the version string.

Adding options
auto	add_option (std::string option_name, callback_t option_callback, std::string option_description="", bool defaulted=false, std::function< std::string()> func={}) -> option_t *
	Adds an option driven by a callback.
template<typename assign_to_t, typename convert_to_t = assign_to_t> requires (!std::is_const_v<convert_to_t>)
auto	add_option (std::string option_name, assign_to_t &variable, std::string option_description="") -> option_t *
	Adds an option bound to a variable.
template<typename assign_to_t> requires (!std::is_const_v<assign_to_t>)
auto	add_option_no_stream (std::string option_name, assign_to_t &variable, std::string option_description="") -> option_t *
	Adds an option bound to a variable, without a printed default.
template<typename arg_type_t>
auto	add_option_function (std::string option_name, std::function< void(const arg_type_t &)> func, std::string option_description="") -> option_t *
	Adds an option that hands its converted value to a callback.
auto	add_option (std::string option_name) -> option_t *
	Adds an option with no description and no bound variable.
template<typename T> requires (std::is_const_v<T> && std::is_constructible_v<std::string, T>)
auto	add_option (std::string option_name, T &option_description) -> option_t *
	Adds an option with a description but no bound variable.
auto	set_help_flag (std::string flag_name="", const std::string &help_description="") -> option_t *
	Replaces the help flag.
auto	set_help_all_flag (std::string help_name="", const std::string &help_description="") -> option_t *
	Replaces the expanded-help flag.
auto	set_version_flag (std::string flag_name="", const std::string &version_string="", const std::string &version_help="Display program version information and exit") -> option_t *
	Replaces the version flag with a fixed version string.
auto	set_version_flag (std::string flag_name, std::function< std::string()> vfunc, const std::string &version_help="Display program version information and exit") -> option_t *
	Replaces the version flag with one that generates its text.
auto	add_flag (std::string flag_name) -> option_t *
	Adds a flag with no description and no bound variable.
template<typename T> requires ((std::is_const_v<std::remove_reference_t<T>> || std::is_rvalue_reference_v<T &&>) && std::is_constructible_v <std::string, std::remove_reference_t<T>>)
auto	add_flag (std::string flag_name, T &&flag_description) -> option_t *
	Adds a flag with a description but no bound variable.
template<typename T> requires (!detail::mutable_container<T> && !std::is_const_v<T> && !std::is_constructible_v<std::function<void(std::int64_t)>, T>)
auto	add_flag (std::string flag_name, T &flag_result, std::string flag_description="") -> option_t *
	Adds a flag bound to a variable.
template<typename T> requires (!std::is_assignable_v<std::function<void(std::int64_t)> &, T>)
auto	add_flag (std::string flag_name, std::vector< T > &flag_results, std::string flag_description="") -> option_t *
	Adds a flag that collects a value for every appearance.
auto	add_flag_callback (std::string flag_name, std::function< void()> function, std::string flag_description="") -> option_t *
	Adds a flag that calls a function taking no arguments.
auto	add_flag_function (std::string flag_name, std::function< void(std::int64_t)> function, std::string flag_description="") -> option_t *
	Adds a flag that calls a function with its accumulated count.
auto	add_flag (std::string flag_name, std::function< void(std::int64_t)> function, std::string flag_description="") -> option_t *
	Adds a flag that calls a function with its accumulated count.
auto	set_config (std::string option_name="", std::string default_filename="", const std::string &help_message="Read an ini file", bool config_required=false) -> option_t *
	Sets the option that names a configuration file.
auto	remove_option (option_t *opt) -> bool
	Removes an option from this application.
template<typename T = option_group_t>
auto	add_option_group (std::string group_name, std::string group_description="") -> T *
	Adds an option group.

Detailed Description

A command-line parser, a subcommand, or an option group.

Create one, add options to it, and call parse. Call exit from a catch block to turn a cli::parse_error_t into a process exit code.

Member Typedef Documentation

missing_t

using cli::app_t::missing_t = std::vector<std::pair<detail::classifier_t, std::string>>

protected

Arguments that matched nothing, paired with how they were classified.

Keeping the classification avoids reclassifying on the way back out. May contain the -- separator.

Member Enumeration Documentation

name_match_t

enum class cli::app_t::name_match_t : std::uint8_t

strong

How closely a name matched.

Enumerator
none	No match.
exact	The name matched in full.
prefix	The name matched a prefix, and prefix matching is enabled.

startup_mode_t

enum class cli::app_t::startup_mode_t : std::uint8_t

strongprotected

Whether clear leaves this subcommand enabled or disabled.

Enumerator
stable	Leave the enabled state as it is.
enabled	Enable at the start of each parse.
disabled	Disable at the start of each parse.

Constructor & Destructor Documentation

app_t() [1/2]

cli::app_t::app_t ( std::string app_description, std::string app_name, app_t * parent )

protected

Constructs a subcommand.

Parameters

app_description	The description shown in help output.
app_name	The subcommand name.
parent	The owning application.

app_t() [2/2]

cli::app_t::app_t ( std::string app_description = "", std::string app_name = "" )

inlineexplicit

Constructs a top-level application.

A -h,--help flag is added automatically; remove it with set_help_flag if you want to supply your own.

Parameters

app_description	The description shown in help output.
app_name	The program name; taken from the command line when empty.

Member Function Documentation

_add_flag_like_result()

auto cli::app_t::_add_flag_like_result ( option_t * op, const config_item_t & item, const std::vector< std::string > & inputs ) -> bool

protected

Stores a configuration entry against a flag-like option.

Parameters

op	The option to fill.
item	The entry being applied.
inputs	The values from the entry.

Returns

true if the values were stored.

_compare_subcommand_names()

auto cli::app_t::_compare_subcommand_names ( const app_t & subcom, const app_t & base ) const -> const std::string &

nodiscardprotected

Returns the first name two subcommands share.

Parameters

subcom	The subcommand being added.
base	The subcommand to compare against.

Returns

The colliding name, or an empty string if there is none.

_configure()

auto cli::app_t::_configure ( ) -> void

protected

Prepares the subcommand tree for parsing.

Sets fallthrough and prefix behaviour on nameless subcommands, applies the automatic enable or disable, and fixes up parent pointers.

_count_remaining_positionals()

auto cli::app_t::_count_remaining_positionals ( bool required_only = false ) const -> std::size_t

nodiscardprotected

Counts the positionals still waiting for values.

Parameters

required_only

Count only the required ones.

Returns

The count.

_find_subcommand()

auto cli::app_t::_find_subcommand ( const std::string & subc_name, bool ignore_disabled, bool ignore_used ) const -> app_t *

nodiscardprotectednoexcept

Finds a subcommand by name.

Parameters

subc_name	The name to look for.
ignore_disabled	Skip disabled subcommands.
ignore_used	Skip subcommands that were already used.

Returns

A pointer to the subcommand, or nullptr if none matches.

_get_fallthrough_parent() [1/2]

auto cli::app_t::_get_fallthrough_parent ( ) const -> const app_t *

nodiscardprotectednoexcept

Returns the application to fall through to.

Returns

A pointer to that application.

_get_fallthrough_parent() [2/2]

auto cli::app_t::_get_fallthrough_parent ( ) -> app_t *

nodiscardprotectednoexcept

Returns the application to fall through to.

The nearest named ancestor, or the main application.

Returns

A pointer to that application.

_has_remaining_positionals()

auto cli::app_t::_has_remaining_positionals ( ) const -> bool

nodiscardprotected

Reports whether any positional is still waiting for values.

Returns

true if one is.

_move_option()

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

Moves an option from one application to another.

Provided for subclasses that reorganise options into subcommands.

Parameters

opt	The option to move.
app	The application to move it to.

_move_to_missing()

auto cli::app_t::_move_to_missing ( detail::classifier_t val_type, const std::string & val ) -> void

protected

Records an argument that matched nothing.

Parameters

val_type	How the argument was classified.
val	The argument itself.

_parse() [1/2]

auto cli::app_t::_parse ( std::vector< std::string > && args ) -> void

protected

Parses a list of arguments.

Parameters

args	The arguments, last one first.

_parse() [2/2]

auto cli::app_t::_parse ( std::vector< std::string > & args ) -> void

protected

Parses a list of arguments.

Parameters

[in,out]

args

The arguments, last one first.

_parse_arg()

auto cli::app_t::_parse_arg ( std::vector< std::string > & args, detail::classifier_t current_type, bool local_processing_only ) -> bool

protected

Parses an option argument sitting at the front of the list.

Parameters

[in,out]	args	The remaining arguments, last one first.
[in]	current_type	How the leading argument was classified.
[in]	local_processing_only	Disable fallthrough, reporting failure instead.

Returns

true if the argument was consumed.

_parse_config()

auto cli::app_t::_parse_config ( const std::vector< config_item_t > & args ) -> void

protected

Applies a set of configuration entries.

An entry whose name contains a separator is routed into the matching subcommand.

Parameters

args	The entries to apply.

_parse_positional()

auto cli::app_t::_parse_positional ( std::vector< std::string > & args, bool halt_on_subcommand ) -> bool

protected

Parses a positional argument, walking up the tree as needed.

Parameters

[in,out]	args	The remaining arguments, last one first.
[in]	halt_on_subcommand	Return false rather than descending into a subcommand.

Returns

true if the positional was consumed.

_parse_single()

auto cli::app_t::_parse_single ( std::vector< std::string > & args, bool & positional_only ) -> bool

protected

Parses one argument, which may consume several.

Delegates to the parent on failure, and records the argument as missing if even the main application cannot place it.

Parameters

[in,out]	args	The remaining arguments, last one first.
[in,out]	positional_only	Whether the -- separator has been seen.

Returns

false if parsing failed and should return to the parent.

_parse_single_config()

auto cli::app_t::_parse_single_config ( const config_item_t & item, std::size_t level = 0 ) -> bool

protected

Applies one configuration entry.

Parameters

item	The entry to apply.
level	How many section levels have been descended.

Returns

true if a matching option was found.

_parse_stream()

auto cli::app_t::_parse_stream ( std::istream & input ) -> void

protected

Parses a stream as a configuration file.

Parameters

input

The stream to read.

_parse_subcommand()

auto cli::app_t::_parse_subcommand ( std::vector< std::string > & args ) -> bool

protected

Parses a subcommand and everything it consumes.

Always allows fallthrough, unlike the other parse helpers.

Parameters

[in,out]

args

The remaining arguments, last one first.

Returns

true if a subcommand was processed.

_process_callbacks()

auto cli::app_t::_process_callbacks ( callback_priority_t priority ) -> void

protected

Runs the option callbacks at one priority. Runs on every subcommand.

Parameters

priority

Which callbacks to run.

_process_config_file()

auto cli::app_t::_process_config_file ( const std::string & config_file, bool throw_error ) -> bool

protected

Reads and applies one configuration file.

Parameters

config_file	The path to read.
throw_error	Report an error when the file cannot be read.

Returns

true if the file was read.

_process_help_flags()

auto cli::app_t::_process_help_flags ( callback_priority_t priority, bool trigger_help = false, bool trigger_all_help = false ) const -> void

protected

Handles any help flags that were used.

The flags let a recursive call remember that a parent already saw one.

Parameters

priority	Which callbacks are being run.
trigger_help	Whether a parent saw the help flag.
trigger_all_help	Whether a parent saw the expanded-help flag.

_recognize()

auto cli::app_t::_recognize ( const std::string & current, bool ignore_used_subcommands = true ) const -> detail::classifier_t

nodiscardprotected

Classifies one command-line argument.

Parameters

current	The argument to classify.
ignore_used_subcommands	Skip subcommands that were already used.

Returns

What the argument looks like.

_trigger_pre_parse()

auto cli::app_t::_trigger_pre_parse ( std::size_t remaining_args ) -> void

protected

Runs the pre-parse callback, if it has not already run.

Parameters

remaining_args

How many arguments are left to parse.

_valid_subcommand()

auto cli::app_t::_valid_subcommand ( const std::string & current, bool ignore_used = true ) const -> bool

nodiscardprotected

Reports whether a token names a usable subcommand.

Gives up immediately once the subcommand maximum has been reached.

Parameters

current	The token to test.
ignore_used	Skip subcommands that were already used.

Returns

true if the token names a usable subcommand.

_validate()

auto cli::app_t::_validate ( ) const -> void

protected

Checks the option set for conflicts.

Looks for more than one positional taking unlimited arguments, and for minimum and maximum counts that cannot both be satisfied.

Exceptions

cli::invalid_error_t

If the option set cannot work.

add_flag() [1/5]

auto cli::app_t::add_flag ( std::string flag_name ) -> option_t *

inline

Adds a flag with no description and no bound variable.

Parameters

flag_name

The name specification.

Returns

A pointer to the new option, for chaining.

add_flag() [2/5]

auto cli::app_t::add_flag ( std::string flag_name, std::function< void(std::int64_t)> function, std::string flag_description = "" ) -> option_t *

inline

Adds a flag that calls a function with its accumulated count.

Aliases add_flag_function.

Parameters

flag_name	The name specification.
function	Called with the flag's value.
flag_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_flag() [3/5]

template<typename T>
requires (!std::is_assignable_v<std::function<void(std::int64_t)> &, T>)

auto cli::app_t::add_flag ( std::string flag_name, std::vector< T > & flag_results, std::string flag_description = "" ) -> option_t *

inline

Adds a flag that collects a value for every appearance.

Template Parameters

T	The element type of the bound vector.

Parameters

flag_name	The name specification.
flag_results	The vector to append to.
flag_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_flag() [4/5]

template<typename T>
requires ((std::is_const_v<std::remove_reference_t<T>> || std::is_rvalue_reference_v<T &&>) && std::is_constructible_v
<std::string, std::remove_reference_t<T>>)

auto cli::app_t::add_flag ( std::string flag_name, T && flag_description ) -> option_t *

inline

Adds a flag with a description but no bound variable.

Takes a const string or an rvalue string. A non-const lvalue string binds to the overload below instead, and receives the flag's result.

Template Parameters

T	A const or rvalue string-like type.

Parameters

flag_name	The name specification.
flag_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_flag() [5/5]

template<typename T>
requires (!detail::mutable_container<T> && !std::is_const_v<T> && !std::is_constructible_v<std::function<void(std::int64_t)>, T>)

auto cli::app_t::add_flag ( std::string flag_name, T & flag_result, std::string flag_description = "" ) -> option_t *

inline

Adds a flag bound to a variable.

Accepts anything that is not a container and not callable: bool, an enumeration, a string, an integer counter, or any type constructible from a string. An integer wider than a byte is treated as a counter.

Template Parameters

T	The type of the bound variable.

Parameters

flag_name	The name specification.
flag_result	The variable to fill.
flag_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_flag_callback()

auto cli::app_t::add_flag_callback	(	std::string	flag_name,
		std::function< void()>	function,
		std::string	flag_description = "" ) -> option_t *

Adds a flag that calls a function taking no arguments.

Parameters

flag_name	The name specification.
function	Called once when the flag is used.
flag_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_flag_function()

auto cli::app_t::add_flag_function	(	std::string	flag_name,
		std::function< void(std::int64_t)>	function,
		std::string	flag_description = "" ) -> option_t *

Adds a flag that calls a function with its accumulated count.

Parameters

flag_name	The name specification.
function	Called with the flag's value.
flag_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_option() [1/4]

auto cli::app_t::add_option ( std::string option_name ) -> option_t *

inline

Adds an option with no description and no bound variable.

Parameters

option_name

The name specification.

Returns

A pointer to the new option, for chaining.

add_option() [2/4]

template<typename assign_to_t, typename convert_to_t = assign_to_t>
requires (!std::is_const_v<convert_to_t>)

auto cli::app_t::add_option ( std::string option_name, assign_to_t & variable, std::string option_description = "" ) -> option_t *

inline

Adds an option bound to a variable.

The variable's type determines how many values the option takes and how they are converted. Supply convert_to_t when the value should be read as one type and stored as another.

std::string filename;
program.add_option("filename", filename, "description of filename");

Template Parameters

assign_to_t	The type of the bound variable.
convert_to_t	The type values are parsed as.

Parameters

option_name	The name specification.
variable	The variable to fill.
option_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_option() [3/4]

auto cli::app_t::add_option	(	std::string	option_name,
		callback_t	option_callback,
		std::string	option_description = "",
		bool	defaulted = false,
		std::function< std::string()>	func = {} ) -> option_t *

Adds an option driven by a callback.

The other add_option overloads build on this one.

Parameters

option_name	The name specification, for example "-f,--file".
option_callback	Consumes the collected results.
option_description	The description shown in help output.
defaulted	Whether the bound value already holds a usable default.
func	Produces the printed default.

Returns

A pointer to the new option, for chaining.

add_option() [4/4]

template<typename T>
requires (std::is_const_v<T> && std::is_constructible_v<std::string, T>)

auto cli::app_t::add_option ( std::string option_name, T & option_description ) -> option_t *

inline

Adds an option with a description but no bound variable.

Template Parameters

T	A const string-like type.

Parameters

option_name	The name specification.
option_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_option_function()

template<typename arg_type_t>

auto cli::app_t::add_option_function ( std::string option_name, std::function< void(const arg_type_t &)> func, std::string option_description = "" ) -> option_t *

inline

Adds an option that hands its converted value to a callback.

Template Parameters

arg_type_t

The type values are converted to.

Parameters

option_name	The name specification.
func	Receives the converted value.
option_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_option_group()

template<typename T = option_group_t>

auto cli::app_t::add_option_group ( std::string group_name, std::string group_description = "" ) -> T *

inline

Adds an option group.

An option group is a subcommand with no name: it groups options in help output and can carry its own requirements, but is never named on the command line.

Template Parameters

T	The group type to create.

Parameters

group_name	The group name.
group_description	The description shown in help output.

Returns

A pointer to the new group, for chaining.

Exceptions

cli::incorrect_construction_t

If group_name contains a newline or null character.

add_option_no_stream()

template<typename assign_to_t>
requires (!std::is_const_v<assign_to_t>)

auto cli::app_t::add_option_no_stream ( std::string option_name, assign_to_t & variable, std::string option_description = "" ) -> option_t *

inline

Adds an option bound to a variable, without a printed default.

For types that have no usable string representation.

Template Parameters

assign_to_t

The type of the bound variable.

Parameters

option_name	The name specification.
variable	The variable to fill.
option_description	The description shown in help output.

Returns

A pointer to the new option, for chaining.

add_subcommand() [1/2]

auto cli::app_t::add_subcommand

(

app_ptr_t

subcom

)

-> app_t *

Adds an already-constructed application as a subcommand.

Parameters

subcom

The subcommand to adopt.

Returns

A pointer to the subcommand, for chaining.

add_subcommand() [2/2]

auto cli::app_t::add_subcommand	(	std::string	subcommand_name = "",
		std::string	subcommand_description = "" ) -> app_t *

Adds a subcommand.

The subcommand inherits the inheritable settings and the option defaults.

Parameters

subcommand_name	The subcommand name.
subcommand_description	The description shown in help output.

Returns

A pointer to the new subcommand, for chaining.

alias()

auto cli::app_t::alias

(

std::string

app_name

)

-> app_t *

Adds an alternative name this subcommand answers to.

Parameters

app_name

The alias.

Returns

A pointer to this application, for chaining.

allow_config_extras() [1/2]

auto cli::app_t::allow_config_extras ( bool allow = true ) -> app_t *

inline

Accepts unmatched configuration entries instead of reporting them.

Enabling this also enables allow_extras, since a captured configuration entry has to go somewhere.

Parameters

allow

Whether to accept them.

Returns

A pointer to this application, for chaining.

allow_config_extras() [2/2]

auto cli::app_t::allow_config_extras ( config_extras_mode_t mode ) -> app_t *

inline

Sets what happens to unmatched configuration entries.

Note

The original declared this twice, once taking config_extras_mode and once taking ConfigExtrasMode. Those were distinct types holding the same enumerators, and merging them leaves a single overload.

Parameters

mode	The mode to use.

Returns

A pointer to this application, for chaining.

allow_extras() [1/2]

auto cli::app_t::allow_extras ( bool allow = true ) -> app_t *

inline

Accepts unmatched arguments instead of reporting them.

Parameters

allow

Whether to accept them.

Returns

A pointer to this application, for chaining.

allow_extras() [2/2]

auto cli::app_t::allow_extras ( extras_mode_t allow ) -> app_t *

inline

Sets what happens to unmatched arguments.

Parameters

allow

The mode to use.

Returns

A pointer to this application, for chaining.

allow_non_standard_option_names()

auto cli::app_t::allow_non_standard_option_names ( bool allowed = true ) -> app_t *

inline

Accepts non-standard option names such as -single_dash_flag.

Parameters

allowed

Whether to accept them.

Returns

A pointer to this application, for chaining.

allow_subcommand_prefix_matching()

auto cli::app_t::allow_subcommand_prefix_matching ( bool allowed = true ) -> app_t *

inline

Lets a subcommand be matched by a unique prefix of its name.

Parameters

allowed

Whether to allow prefix matching.

Returns

A pointer to this application, for chaining.

allow_windows_style_options()

auto cli::app_t::allow_windows_style_options ( bool value = true ) -> app_t *

inline

Accepts Windows-style options such as /opt.

The first matching short or long name wins. Subcommands inherit this.

Parameters

value

Whether to accept them.

Returns

A pointer to this application, for chaining.

callback()

auto cli::app_t::callback ( std::function< void()> app_callback ) -> app_t *

inline

Sets the callback run once everything has been parsed and processed.

Assigns to parse_complete_callback when immediate_callback is set, and to final_callback otherwise. Capture by reference if the callback needs the application itself.

Parameters

app_callback

The callback to run.

Returns

A pointer to this application, for chaining.

check_name()

auto cli::app_t::check_name ( std::string name_to_check ) const -> bool

nodiscard

Reports whether a name refers to this subcommand.

Honours the case, underscore, and prefix-matching settings.

Parameters

name_to_check

The name to test.

Returns

true if it matches.

check_name_detail()

auto cli::app_t::check_name_detail ( std::string name_to_check ) const -> name_match_t

nodiscard

Reports how closely a name matches this subcommand.

Honours the case and underscore settings.

Parameters

name_to_check

The name to test.

Returns

How closely it matched.

clear_aliases()

auto cli::app_t::clear_aliases ( ) -> app_t *

inline

Removes every alias.

Returns

A pointer to this application, for chaining.

config_formatter()

auto cli::app_t::config_formatter ( std::shared_ptr< config_t > fmt ) -> app_t *

inline

Replaces the configuration reader and writer.

Parameters

fmt	The converter to use.

Returns

A pointer to this application, for chaining.

config_to_str() [1/3]

auto cli::app_t::config_to_str ( ) const -> std::string

inlinenodiscard

Writes the current values out as configuration text.

Returns

The configuration text, covering only options that were set.

config_to_str() [2/3]

auto cli::app_t::config_to_str ( bool default_also, bool write_description = false ) const -> std::string

inlinenodiscard

Writes the current values out as configuration text.

Deprecated

Use the config_output_mode_t overload instead.

Parameters

default_also	Include options left at their defaults.
write_description	Include descriptions as comments.

Returns

The configuration text.

config_to_str() [3/3]

auto cli::app_t::config_to_str ( config_output_mode_t mode, bool write_description = false ) const -> std::string

inlinenodiscard

Writes the current values out as configuration text.

Parameters

mode	How much of the application to write.
write_description	Include descriptions as comments.

Returns

The configuration text.

configurable()

auto cli::app_t::configurable ( bool value = true ) -> app_t *

inline

Lets this subcommand be triggered from a configuration file.

Parameters

value

Whether the subcommand is configurable.

Returns

A pointer to this application, for chaining.

count() [1/2]

auto cli::app_t::count ( ) const -> std::size_t

inlinenodiscard

Returns how many times this subcommand was used.

The main application reports 1, as does an unnamed subcommand unless a callback changes it.

Returns

The use count.

count() [2/2]

auto cli::app_t::count ( std::string option_name ) const -> std::size_t

inlinenodiscard

Returns how many times an option was used.

Parameters

option_name

The option to look up.

Returns

The use count.

Exceptions

cli::option_not_found_t

If no option matches.

count_all()

auto cli::app_t::count_all ( ) const -> std::size_t

nodiscard

Returns how many arguments were consumed by options and subcommands.

Arguments treated as extras are not counted.

Returns

The argument count.

description()

auto cli::app_t::description ( std::string app_description ) -> app_t *

inline

Sets the description shown in help output.

Parameters

app_description

The description.

Returns

A pointer to this application, for chaining.

disabled()

auto cli::app_t::disabled ( bool disable = true ) -> app_t *

inline

Disables this subcommand or option group.

Parameters

disable

Whether to disable it.

Returns

A pointer to this application, for chaining.

disabled_by_default()

auto cli::app_t::disabled_by_default ( bool disable = true ) -> app_t *

inline

Makes clear leave this subcommand disabled.

Turning this off returns to the stable state unless enabled_by_default was set, which takes precedence.

Parameters

disable

Whether to disable by default.

Returns

A pointer to this application, for chaining.

enabled_by_default()

auto cli::app_t::enabled_by_default ( bool enable = true ) -> app_t *

inline

Makes clear leave this subcommand enabled.

Turning this off returns to the stable state unless disabled_by_default was set, which takes precedence.

Parameters

enable

Whether to enable by default.

Returns

A pointer to this application, for chaining.

ensure_utf8()

auto cli::app_t::ensure_utf8 ( char ** argv ) -> char **

nodiscard

Converts argv to UTF-8 on Windows; does nothing elsewhere.

The converted strings are owned by this application, so the returned pointer stays valid for as long as it does.

Parameters

argv	The argument array from main.

Returns

The converted argument array.

excludes() [1/2]

auto cli::app_t::excludes ( app_t * app ) -> app_t *

inline

Forbids a subcommand from being used alongside this one.

The exclusion is recorded on both subcommands.

Parameters

app	The subcommand to exclude.

Returns

A pointer to this application, for chaining.

Exceptions

cli::option_not_found_t

If app is null or is this application.

excludes() [2/2]

auto cli::app_t::excludes ( option_t * opt ) -> app_t *

inline

Forbids an option from being used alongside this subcommand.

Parameters

opt	The option to exclude.

Returns

A pointer to this application, for chaining.

Exceptions

cli::option_not_found_t

If opt is null.

exit()

auto cli::app_t::exit	(	const error_t &	e,
		std::ostream &	out = std::cout,
		std::ostream &	err = std::cerr ) const -> int

Prints an error and returns the exit code to give the process.

A help or version request is printed to out; anything else goes to err.

Parameters

e	The error to report.
out	The stream used for successful early exits.
err	The stream used for failures.

Returns

The process exit code.

failure_message()

auto cli::app_t::failure_message ( std::function< std::string(const app_t *, const error_t &)> function ) -> void

inline

Sets how an error is rendered by exit.

Parameters

function

Receives the application and the error, returns the text to print.

fallthrough()

auto cli::app_t::fallthrough ( bool value = true ) -> app_t *

inline

Lets unrecognised options fall through to the parent command.

Inherited from the parent, and usually set there.

Parameters

value

Whether to allow fallthrough.

Returns

A pointer to this application, for chaining.

final_callback()

auto cli::app_t::final_callback ( std::function< void()> app_callback ) -> app_t *

inline

Sets the callback run once everything has been processed.

Parameters

app_callback

The callback to run.

Returns

A pointer to this application, for chaining.

footer() [1/2]

auto cli::app_t::footer ( std::function< std::string()> footer_function ) -> app_t *

inline

Sets a callable producing the footer.

Parameters

footer_function

Produces the footer text.

Returns

A pointer to this application, for chaining.

footer() [2/2]

auto cli::app_t::footer ( std::string footer_string ) -> app_t *

inline

Sets the footer shown after all options.

Parameters

footer_string

The footer text.

Returns

A pointer to this application, for chaining.

formatter()

auto cli::app_t::formatter ( std::shared_ptr< formatter_base_t > fmt ) -> app_t *

inline

Replaces the help formatter.

Parameters

fmt	The formatter to use.

Returns

A pointer to this application, for chaining.

formatter_fn()

auto cli::app_t::formatter_fn ( std::function< std::string(const app_t *, std::string, app_format_mode_t)> fmt ) -> app_t *

inline

Replaces the help formatter with a callable.

Parameters

fmt	Renders the whole help page.

Returns

A pointer to this application, for chaining.

get_aliases()

auto cli::app_t::get_aliases ( ) const -> const std::vector< std::string > &

inlinenodiscard

Returns the alternative names this subcommand answers to.

Returns

The aliases.

get_allow_config_extras()

auto cli::app_t::get_allow_config_extras ( ) const -> config_extras_mode_t

inlinenodiscard

Returns what happens to unmatched configuration entries.

Returns

The configuration extras mode.

get_allow_extras()

auto cli::app_t::get_allow_extras ( ) const -> bool

inlinenodiscard

Reports whether unmatched arguments are accepted.

Returns

true if they are captured rather than reported.

get_allow_extras_mode()

auto cli::app_t::get_allow_extras_mode ( ) const -> extras_mode_t

inlinenodiscard

Returns what happens to unmatched arguments.

Returns

The extras mode.

get_allow_non_standard_option_names()

auto cli::app_t::get_allow_non_standard_option_names ( ) const -> bool

inlinenodiscard

Reports whether non-standard option names are accepted.

Returns

true if they are accepted.

get_allow_subcommand_prefix_matching()

auto cli::app_t::get_allow_subcommand_prefix_matching ( ) const -> bool

inlinenodiscard

Reports whether subcommands may be matched by a name prefix.

Returns

true if prefix matching is enabled.

get_allow_windows_style_options()

auto cli::app_t::get_allow_windows_style_options ( ) const -> bool

inlinenodiscard

Reports whether Windows-style options are accepted.

Returns

true if /opt is accepted.

get_config_formatter()

auto cli::app_t::get_config_formatter ( ) const -> std::shared_ptr< config_t >

inlinenodiscard

Returns the configuration reader and writer.

Returns

A shared handle to the converter.

get_config_formatter_base()

auto cli::app_t::get_config_formatter_base ( ) const -> std::shared_ptr< config_base_t >

inlinenodiscard

Returns the configuration converter as a config_base_t.

Returns

A shared handle to the converter, or empty if it is not a config_base_t.

get_config_ptr() [1/2]

auto cli::app_t::get_config_ptr ( ) -> option_t *

inlinenodiscard

Returns the option naming a configuration file.

Returns

A pointer to the option, or nullptr if there is none.

get_config_ptr() [2/2]

auto cli::app_t::get_config_ptr ( ) const -> const option_t *

inlinenodiscard

Returns the option naming a configuration file.

Returns

A pointer to the option, or nullptr if there is none.

get_configurable()

auto cli::app_t::get_configurable ( ) const -> bool

inlinenodiscard

Reports whether this subcommand can be triggered from a configuration file.

Returns

true if it is configurable.

get_description()

auto cli::app_t::get_description ( ) const -> const std::string &

inlinenodiscard

Returns the description shown in help output.

Returns

The description.

get_disabled()

auto cli::app_t::get_disabled ( ) const -> bool

inlinenodiscard

Reports whether this subcommand is disabled.

Returns

true if it is disabled.

get_disabled_by_default()

auto cli::app_t::get_disabled_by_default ( ) const -> bool

inlinenodiscard

Reports whether clear leaves this subcommand disabled.

Returns

true if it is disabled by default.

get_display_name()

auto cli::app_t::get_display_name ( bool with_aliases = false ) const -> std::string

nodiscard

Returns the name shown in help output.

Parameters

with_aliases

Include the aliases alongside the name.

Returns

The display name.

get_enabled_by_default()

auto cli::app_t::get_enabled_by_default ( ) const -> bool

inlinenodiscard

Reports whether clear leaves this subcommand enabled.

Returns

true if it is enabled by default.

get_fallthrough()

auto cli::app_t::get_fallthrough ( ) const -> bool

inlinenodiscard

Reports whether options fall through to the parent command.

Returns

true if fallthrough is enabled.

get_footer()

auto cli::app_t::get_footer ( ) const -> std::string

inlinenodiscard

Returns the footer.

When a footer callback is set, its output precedes any fixed footer text.

Returns

The footer.

get_formatter()

auto cli::app_t::get_formatter ( ) const -> std::shared_ptr< formatter_base_t >

inlinenodiscard

Returns the help formatter.

Returns

A shared handle to the formatter.

get_group()

auto cli::app_t::get_group ( ) const -> const std::string &

inlinenodiscard

Returns the help group this subcommand is listed under.

Returns

The group name.

get_groups()

auto cli::app_t::get_groups ( ) const -> std::vector< std::string >

nodiscard

Returns the option groups defined here, in definition order.

Returns

The group names.

get_help_all_ptr()

auto cli::app_t::get_help_all_ptr ( ) const -> const option_t *

inlinenodiscard

Returns the expanded-help flag.

Returns

A pointer to the option, or nullptr if there is none.

get_help_ptr() [1/2]

auto cli::app_t::get_help_ptr ( ) -> option_t *

inlinenodiscard

Returns the help flag.

Returns

A pointer to the option, or nullptr if there is none.

get_help_ptr() [2/2]

auto cli::app_t::get_help_ptr ( ) const -> const option_t *

inlinenodiscard

Returns the help flag.

Returns

A pointer to the option, or nullptr if there is none.

get_ignore_case()

auto cli::app_t::get_ignore_case ( ) const -> bool

inlinenodiscard

Reports whether name matching ignores case.

Returns

true if case is ignored.

get_ignore_underscore()

auto cli::app_t::get_ignore_underscore ( ) const -> bool

inlinenodiscard

Reports whether name matching ignores underscores.

Returns

true if underscores are ignored.

get_immediate_callback()

auto cli::app_t::get_immediate_callback ( ) const -> bool

inlinenodiscard

Reports whether the callback runs as soon as parsing finishes.

Returns

true if the callback is immediate.

get_name()

auto cli::app_t::get_name ( ) const -> const std::string &

inlinenodiscard

Returns this application's name.

Returns

The name.

get_option() [1/2]

auto cli::app_t::get_option ( std::string option_name ) -> option_t *

nodiscard

Finds an option by name.

Parameters

option_name

The name to look for.

Returns

A pointer to the option.

Exceptions

cli::option_not_found_t

If no option matches.

get_option() [2/2]

auto cli::app_t::get_option ( std::string option_name ) const -> const option_t *

nodiscard

Finds an option by name.

Parameters

option_name

The name to look for.

Returns

A pointer to the option.

Exceptions

cli::option_not_found_t

If no option matches.

get_option_group()

auto cli::app_t::get_option_group ( std::string group_name ) const -> app_t *

nodiscard

Finds an option group by name.

Parameters

group_name

The group name.

Returns

A pointer to the group.

Exceptions

cli::option_not_found_t

If no group matches.

get_option_no_throw() [1/2]

auto cli::app_t::get_option_no_throw ( std::string option_name ) const -> const option_t *

nodiscardnoexcept

Finds an option by name, without throwing.

Parameters

option_name

The name to look for.

Returns

A pointer to the option, or nullptr if none matches.

get_option_no_throw() [2/2]

auto cli::app_t::get_option_no_throw ( std::string option_name ) -> option_t *

nodiscardnoexcept

Finds an option by name, without throwing.

Parameters

option_name

The name to look for.

Returns

A pointer to the option, or nullptr if none matches.

get_options() [1/2]

auto cli::app_t::get_options ( const std::function< bool(const option_t *)> & filter = {} ) const -> std::vector< const option_t * >

nodiscard

Returns the options matching a filter.

Parameters

filter

Selects which options to return; empty returns all.

Returns

The matching options.

get_options() [2/2]

auto cli::app_t::get_options ( const std::function< bool(option_t *)> & filter = {} ) -> std::vector< option_t * >

nodiscard

Returns the options matching a filter.

Parameters

filter

Selects which options to return; empty returns all.

Returns

The matching options.

get_parent() [1/2]

auto cli::app_t::get_parent ( ) -> app_t *

inlinenodiscard

Returns the parent application.

Returns

A pointer to the parent, or nullptr for the main application.

get_parent() [2/2]

auto cli::app_t::get_parent ( ) const -> const app_t *

inlinenodiscard

Returns the parent application.

Returns

A pointer to the parent, or nullptr for the main application.

get_positionals_at_end()

auto cli::app_t::get_positionals_at_end ( ) const -> bool

inlinenodiscard

Reports whether positionals must appear after every option.

Returns

true if positionals come last.

get_prefix_command()

auto cli::app_t::get_prefix_command ( ) const -> bool

inlinenodiscard

Reports whether parsing stops at an unrecognised argument.

Returns

true if prefix-command mode is enabled in any form.

get_prefix_command_mode()

auto cli::app_t::get_prefix_command_mode ( ) const -> prefix_command_mode_t

inlinenodiscard

Returns when parsing stops early.

Returns

The prefix-command mode.

get_require_option_max()

auto cli::app_t::get_require_option_max ( ) const -> std::size_t

inlinenodiscard

Returns the largest number of options accepted.

Returns

The count; 0 means unlimited.

get_require_option_min()

auto cli::app_t::get_require_option_min ( ) const -> std::size_t

inlinenodiscard

Returns the smallest number of options that must be used.

Returns

The count.

get_require_subcommand_max()

auto cli::app_t::get_require_subcommand_max ( ) const -> std::size_t

inlinenodiscard

Returns the largest number of subcommands accepted.

Returns

The count; 0 means unlimited.

get_require_subcommand_min()

auto cli::app_t::get_require_subcommand_min ( ) const -> std::size_t

inlinenodiscard

Returns the smallest number of subcommands that must be used.

Returns

The count.

get_required()

auto cli::app_t::get_required ( ) const -> bool

inlinenodiscard

Reports whether this subcommand must be used.

Returns

true if it is required.

get_silent()

auto cli::app_t::get_silent ( ) const -> bool

inlinenodiscard

Reports whether this subcommand is hidden from the processed list.

Returns

true if it is hidden.

get_subcommand() [1/3]

auto cli::app_t::get_subcommand

(

const app_t *

subcom

)

const -> app_t *

Finds a subcommand by pointer.

Parameters

subcom

The subcommand to look for; nullptr returns the first one.

Returns

A pointer to the subcommand.

Exceptions

cli::option_not_found_t

If it is not a subcommand of this application.

get_subcommand() [2/3]

auto cli::app_t::get_subcommand ( int index = 0 ) const -> app_t *

nodiscard

Finds a subcommand by position.

Parameters

index

The position to look up.

Returns

A pointer to the subcommand.

Exceptions

cli::option_not_found_t

If index is out of range.

get_subcommand() [3/3]

auto cli::app_t::get_subcommand ( std::string subcom ) const -> app_t *

nodiscard

Finds a subcommand by name.

Parameters

subcom

The name to look for.

Returns

A pointer to the subcommand.

Exceptions

cli::option_not_found_t

If no subcommand matches.

get_subcommand_fallthrough()

auto cli::app_t::get_subcommand_fallthrough ( ) const -> bool

inlinenodiscard

Reports whether a parent's subcommands are recognised here.

Returns

true if subcommand fallthrough is enabled.

get_subcommand_no_throw()

auto cli::app_t::get_subcommand_no_throw ( std::string subcom ) const -> app_t *

nodiscardnoexcept

Finds a subcommand by name, without throwing.

Parameters

subcom

The name to look for.

Returns

A pointer to the subcommand, or nullptr if none matches.

get_subcommand_ptr() [1/3]

auto cli::app_t::get_subcommand_ptr

(

app_t *

subcom

)

const -> app_ptr_t

Finds a subcommand by pointer and returns an owning handle.

Parameters

subcom

The subcommand to look for.

Returns

A shared handle to the subcommand.

Exceptions

cli::option_not_found_t

If it is not a subcommand of this application.

get_subcommand_ptr() [2/3]

auto cli::app_t::get_subcommand_ptr ( int index = 0 ) const -> app_ptr_t

nodiscard

Finds a subcommand by position and returns an owning handle.

Parameters

index

The position to look up.

Returns

A shared handle to the subcommand.

Exceptions

cli::option_not_found_t

If index is out of range.

get_subcommand_ptr() [3/3]

auto cli::app_t::get_subcommand_ptr ( std::string subcom ) const -> app_ptr_t

nodiscard

Finds a subcommand by name and returns an owning handle.

Parameters

subcom

The name to look for.

Returns

A shared handle to the subcommand.

Exceptions

cli::option_not_found_t

If no subcommand matches.

get_subcommands() [1/3]

auto cli::app_t::get_subcommands ( ) const -> const std::vector< app_t * > &

inlinenodiscard

Returns the subcommands that were used, in command-line order.

Returns

The parsed subcommands.

get_subcommands() [2/3]

auto cli::app_t::get_subcommands

(

const std::function< bool(app_t *)> &

filter

)

-> std::vector< app_t * >

Returns the subcommands matching a filter, as defined.

Parameters

filter

Selects which subcommands to return; empty returns all.

Returns

The matching subcommands.

get_subcommands() [3/3]

auto cli::app_t::get_subcommands

(

const std::function< bool(const app_t *)> &

filter

)

const -> std::vector< const app_t * >

Returns the subcommands matching a filter, as defined.

Parameters

filter

Selects which subcommands to return; empty returns all.

Returns

The matching subcommands.

get_usage()

auto cli::app_t::get_usage ( ) const -> std::string

inlinenodiscard

Returns the usage line.

When a usage callback is set, its output precedes any fixed usage text.

Returns

The usage line.

get_validate_optional_arguments()

auto cli::app_t::get_validate_optional_arguments ( ) const -> bool

inlinenodiscard

Reports whether optional vector arguments are validated before assignment.

Returns

true if they are validated first.

get_validate_positionals()

auto cli::app_t::get_validate_positionals ( ) const -> bool

inlinenodiscard

Reports whether positionals are validated before assignment.

Returns

true if they are validated first.

get_version_ptr() [1/2]

auto cli::app_t::get_version_ptr ( ) -> option_t *

inlinenodiscard

Returns the version flag.

Returns

A pointer to the option, or nullptr if there is none.

get_version_ptr() [2/2]

auto cli::app_t::get_version_ptr ( ) const -> const option_t *

inlinenodiscard

Returns the version flag.

Returns

A pointer to the option, or nullptr if there is none.

got_subcommand() [1/2]

auto cli::app_t::got_subcommand ( const app_t * subcom ) const -> bool

inline

Reports whether a subcommand was used.

Parameters

subcom

The subcommand to check.

Returns

true if it was used.

Exceptions

cli::option_not_found_t

If it is not a subcommand of this application.

got_subcommand() [2/2]

auto cli::app_t::got_subcommand ( std::string subcommand_name ) const -> bool

inlinenodiscardnoexcept

Reports whether a named subcommand was used.

Parameters

subcommand_name

The subcommand to check.

Returns

true if it exists and was used.

group()

auto cli::app_t::group ( std::string group_name ) -> app_t *

inline

Sets the help group this subcommand is listed under.

Parameters

group_name

The group name.

Returns

A pointer to this application, for chaining.

help()

auto cli::app_t::help ( std::string prev = "", app_format_mode_t mode = app_format_mode_t::normal ) const -> std::string

nodiscard

Renders the help page using the configured formatter.

Covers one subcommand at a time.

Parameters

prev	The name to present this application under.
mode	How much detail to include.

Returns

The rendered help page.

ignore_case()

auto cli::app_t::ignore_case

(

bool

value = true

)

-> app_t *

Makes name matching case-insensitive. Subcommands inherit this.

Parameters

value

Whether to ignore case.

Returns

A pointer to this application, for chaining.

ignore_underscore()

auto cli::app_t::ignore_underscore

(

bool

value = true

)

-> app_t *

Makes name matching ignore underscores. Subcommands inherit this.

Parameters

value

Whether to ignore underscores.

Returns

A pointer to this application, for chaining.

immediate_callback()

auto cli::app_t::immediate_callback

(

bool

immediate = true

)

-> app_t *

Runs this subcommand's callback as soon as it finishes parsing.

Parameters

immediate

Whether to run the callback immediately.

Returns

A pointer to this application, for chaining.

name()

auto cli::app_t::name

(

std::string

app_name = ""

)

-> app_t *

Sets the application or subcommand name.

Parameters

app_name

The name; an empty string defers to the command line.

Returns

A pointer to this application, for chaining.

needs() [1/2]

auto cli::app_t::needs ( app_t * app ) -> app_t *

inline

Requires a subcommand to be used alongside this one.

Not mutual.

Parameters

app	The required subcommand.

Returns

A pointer to this application, for chaining.

Exceptions

cli::option_not_found_t

If app is null or is this application.

needs() [2/2]

auto cli::app_t::needs ( option_t * opt ) -> app_t *

inline

Requires an option to be used alongside this subcommand.

Not mutual: the option does not come to require this subcommand.

Parameters

opt	The required option.

Returns

A pointer to this application, for chaining.

Exceptions

cli::option_not_found_t

If opt is null.

operator bool()

cli::app_t::operator bool ( ) const

inlineexplicitnodiscard

Reports whether this subcommand appeared on the command line.

Lets a subcommand be tested directly: if (*sub) { ... }.

Returns

true if it was parsed at least once.

operator[]() [1/2]

auto cli::app_t::operator[] ( const char * option_name ) const -> const option_t *

inlinenodiscard

Finds an option by name.

Parameters

option_name

The name to look for.

Returns

A pointer to the option.

Exceptions

cli::option_not_found_t

If no option matches.

operator[]() [2/2]

auto cli::app_t::operator[] ( const std::string & option_name ) const -> const option_t *

inlinenodiscard

Finds an option by name.

Parameters

option_name

The name to look for.

Returns

A pointer to the option.

Exceptions

cli::option_not_found_t

If no option matches.

option_defaults()

auto cli::app_t::option_defaults ( ) -> option_defaults_t *

inline

Returns the settings newly added options inherit.

Returns

A pointer to the option defaults.

parse() [1/6]

auto cli::app_t::parse	(	int	argc,
		const char *const *	argv ) -> void

Parses the command line.

Call once every option and subcommand has been added.

Parameters

argc	The argument count, as given to main.
argv	The argument array, as given to main.

Exceptions

cli::parse_error_t

If the command line cannot be parsed.

parse() [2/6]

auto cli::app_t::parse	(	int	argc,
		const wchar_t *const *	argv ) -> void

Parses a wide command line.

The arguments are narrowed to UTF-8 first.

Parameters

argc	The argument count.
argv	The argument array.

Exceptions

cli::parse_error_t

If the command line cannot be parsed.

parse() [3/6]

auto cli::app_t::parse	(	std::string	commandline,
		bool	program_name_included = false ) -> void

Parses a whole command line held in one string.

The string is split into arguments and handed to the vector overload.

Parameters

commandline	The command line to parse.
program_name_included	Whether commandline starts with the program name.

Exceptions

cli::parse_error_t

If the command line cannot be parsed.

parse() [4/6]

auto cli::app_t::parse

(

std::vector< std::string > &&

args

)

-> void

Parses a list of arguments, in reverse order.

Parameters

args	The arguments, last one first.

Exceptions

cli::parse_error_t

If the arguments cannot be parsed.

parse() [5/6]

auto cli::app_t::parse

(

std::vector< std::string > &

args

)

-> void

Parses a list of arguments, in reverse order.

This is where the work happens; the other overloads funnel into it. args is left holding whatever was not consumed.

Parameters

[in,out]

args

The arguments, last one first.

Exceptions

cli::parse_error_t

If the arguments cannot be parsed.

parse() [6/6]

auto cli::app_t::parse	(	std::wstring	commandline,
		bool	program_name_included = false ) -> void

Parses a whole wide command line held in one string.

Parameters

commandline	The command line to parse.
program_name_included	Whether commandline starts with the program name.

Exceptions

cli::parse_error_t

If the command line cannot be parsed.

parse_complete_callback()

auto cli::app_t::parse_complete_callback ( std::function< void()> pc_callback ) -> app_t *

inline

Sets the callback run once parsing has finished.

Parameters

pc_callback

The callback to run.

Returns

A pointer to this application, for chaining.

parse_from_stream()

auto cli::app_t::parse_from_stream

(

std::istream &

input

)

-> void

Parses arguments read from a stream as a configuration file.

Parameters

input

The stream to read.

Exceptions

cli::parse_error_t

If the contents cannot be parsed.

parse_order()

auto cli::app_t::parse_order ( ) const -> const std::vector< option_t * > &

inlinenodiscard

Returns the options that were used, in command-line order.

Returns

The options, in the order they appeared.

parsed()

auto cli::app_t::parsed ( ) const -> bool

inlinenodiscard

Reports whether this subcommand appeared on the command line.

Returns

true if it was parsed at least once.

positionals_at_end()

auto cli::app_t::positionals_at_end ( bool value = true ) -> app_t *

inline

Requires positionals to appear after every option.

Parameters

value

Whether positionals come last.

Returns

A pointer to this application, for chaining.

pre_callback()

virtual auto cli::app_t::pre_callback ( ) -> void

inlinevirtual

Hook run after parsing but before the callbacks.

Does not run if an error or a help request was thrown.

prefix_command() [1/2]

auto cli::app_t::prefix_command ( bool is_prefix = true ) -> app_t *

inline

Stops parsing at the first unrecognised argument.

Everything from that point on is left in the remaining-arguments list.

Parameters

is_prefix

Whether to stop early.

Returns

A pointer to this application, for chaining.

prefix_command() [2/2]

auto cli::app_t::prefix_command ( prefix_command_mode_t mode ) -> app_t *

inline

Sets when parsing stops early.

Parameters

mode	The mode to use.

Returns

A pointer to this application, for chaining.

preparse_callback()

auto cli::app_t::preparse_callback ( std::function< void(std::size_t)> pp_callback ) -> app_t *

inline

Sets the callback run before parsing starts.

Parameters

pp_callback

The callback to run, given the argument count.

Returns

A pointer to this application, for chaining.

remaining()

auto cli::app_t::remaining ( bool recurse = false ) const -> std::vector< std::string >

nodiscard

Returns the arguments that matched nothing.

Parameters

recurse

Include the arguments left over by subcommands.

Returns

The unmatched arguments.

remaining_for_passthrough()

auto cli::app_t::remaining_for_passthrough ( bool recurse = false ) const -> std::vector< std::string >

nodiscard

Returns the unmatched arguments, ready to hand to another program.

Parameters

recurse

Include the arguments left over by subcommands.

Returns

The unmatched arguments, in command-line order.

remaining_size()

auto cli::app_t::remaining_size ( bool recurse = false ) const -> std::size_t

nodiscard

Returns how many arguments matched nothing, excluding the -- separator.

Parameters

recurse

Include the arguments left over by subcommands.

Returns

The count.

remove_excludes() [1/2]

auto cli::app_t::remove_excludes

(

app_t *

app

)

-> bool

Drops a subcommand exclusion.

Parameters

app	The subcommand to stop excluding.

Returns

true if the exclusion was present.

remove_excludes() [2/2]

auto cli::app_t::remove_excludes

(

option_t *

opt

)

-> bool

Drops an option exclusion.

Parameters

opt	The option to stop excluding.

Returns

true if the exclusion was present.

remove_needs() [1/2]

auto cli::app_t::remove_needs

(

app_t *

app

)

-> bool

Drops a subcommand requirement.

Parameters

app	The subcommand to stop requiring.

Returns

true if the requirement was present.

remove_needs() [2/2]

auto cli::app_t::remove_needs

(

option_t *

opt

)

-> bool

Drops an option requirement.

Parameters

opt	The option to stop requiring.

Returns

true if the requirement was present.

remove_option()

auto cli::app_t::remove_option

(

option_t *

opt

)

-> bool

Removes an option from this application.

Parameters

opt	The option to remove.

Returns

true if the option was found and removed.

remove_subcommand()

auto cli::app_t::remove_subcommand

(

app_t *

subcom

)

-> bool

Removes a subcommand from this application.

Parameters

subcom

The subcommand to remove.

Returns

true if the subcommand was found and removed.

require_option() [1/3]

auto cli::app_t::require_option ( ) -> app_t *

inline

Requires at least one option to be used.

Returns

A pointer to this application, for chaining.

require_option() [2/3]

auto cli::app_t::require_option ( int value ) -> app_t *

inline

Requires a given number of options.

A negative value sets a maximum instead of an exact count; 0 means unlimited. Does not affect a help request.

Parameters

value

The count, or its negation for a maximum.

Returns

A pointer to this application, for chaining.

require_option() [3/3]

auto cli::app_t::require_option ( std::size_t min, std::size_t max ) -> app_t *

inline

Requires a number of options within a range.

A maximum of 0 means unlimited.

Parameters

min	The smallest acceptable count.
max	The largest acceptable count.

Returns

A pointer to this application, for chaining.

require_subcommand() [1/3]

auto cli::app_t::require_subcommand ( ) -> app_t *

inline

Requires at least one subcommand to be used.

Returns

A pointer to this application, for chaining.

require_subcommand() [2/3]

auto cli::app_t::require_subcommand ( int value ) -> app_t *

inline

Requires a given number of subcommands.

A negative value sets a maximum instead of an exact count; 0 means unlimited. Does not affect a help request. The maximum is inheritable.

Parameters

value

The count, or its negation for a maximum.

Returns

A pointer to this application, for chaining.

require_subcommand() [3/3]

auto cli::app_t::require_subcommand ( std::size_t min, std::size_t max ) -> app_t *

inline

Requires a number of subcommands within a range.

A maximum of 0 means unlimited. The maximum is inheritable.

Parameters

min	The smallest acceptable count.
max	The largest acceptable count.

Returns

A pointer to this application, for chaining.

required()

auto cli::app_t::required ( bool require = true ) -> app_t *

inline

Requires this subcommand to be used.

Parameters

require

Whether the subcommand is required.

Returns

A pointer to this application, for chaining.

run_callback()

auto cli::app_t::run_callback ( bool final_mode = false, bool suppress_final_callback = false ) -> void

protected

Runs this application's callback, and its subcommands', bottom up.

Parameters

final_mode	Run the final callbacks rather than the parse-complete ones.
suppress_final_callback	Skip this application's own final callback.

set_config()

auto cli::app_t::set_config	(	std::string	option_name = "",
		std::string	default_filename = "",
		const std::string &	help_message = "Read an ini file",
		bool	config_required = false ) -> option_t *

Sets the option that names a configuration file.

An empty option_name removes it.

Parameters

option_name	The name specification.
default_filename	The file read when the option is not given.
help_message	The description shown in help output.
config_required	Whether the file must exist.

Returns

A pointer to the new option, or nullptr if it was removed.

set_help_all_flag()

auto cli::app_t::set_help_all_flag	(	std::string	help_name = "",
		const std::string &	help_description = "" ) -> option_t *

Replaces the expanded-help flag.

An empty help_name removes it entirely.

Parameters

help_name	The name specification.
help_description	The description shown in help output.

Returns

A pointer to the new option, or nullptr if it was removed.

set_help_flag()

auto cli::app_t::set_help_flag	(	std::string	flag_name = "",
		const std::string &	help_description = "" ) -> option_t *

Replaces the help flag.

An empty flag_name removes the help flag entirely.

Parameters

flag_name	The name specification.
help_description	The description shown in help output.

Returns

A pointer to the new option, or nullptr if it was removed.

set_version_flag() [1/2]

auto cli::app_t::set_version_flag	(	std::string	flag_name,
		std::function< std::string()>	vfunc,
		const std::string &	version_help = "Display program version information and exit" ) -> option_t *

Replaces the version flag with one that generates its text.

Parameters

flag_name	The name specification.
vfunc	Produces the version text.
version_help	The description shown in help output.

Returns

A pointer to the new option, for chaining.

set_version_flag() [2/2]

auto cli::app_t::set_version_flag	(	std::string	flag_name = "",
		const std::string &	version_string = "",
		const std::string &	version_help = "Display program version information and exit" ) -> option_t *

Replaces the version flag with a fixed version string.

Parameters

flag_name	The name specification.
version_string	The version text to print.
version_help	The description shown in help output.

Returns

A pointer to the new option, or nullptr if it was removed.

silent()

auto cli::app_t::silent ( bool silence = true ) -> app_t *

inline

Hides this subcommand from the processed subcommand list.

Parameters

silence

Whether to hide it.

Returns

A pointer to this application, for chaining.

subcommand_fallthrough()

auto cli::app_t::subcommand_fallthrough ( bool value = true ) -> app_t *

inline

Lets a parent's subcommands be recognised from within this one.

Parameters

value

Whether to allow subcommand fallthrough.

Returns

A pointer to this application, for chaining.

usage() [1/2]

auto cli::app_t::usage ( std::function< std::string()> usage_function ) -> app_t *

inline

Sets a callable producing the usage line.

Parameters

usage_function

Produces the usage line.

Returns

A pointer to this application, for chaining.

usage() [2/2]

auto cli::app_t::usage ( std::string usage_string ) -> app_t *

inline

Sets the usage line shown after the description.

Parameters

usage_string

The usage line.

Returns

A pointer to this application, for chaining.

validate_optional_arguments()

auto cli::app_t::validate_optional_arguments ( bool validate = true ) -> app_t *

inline

Validates optional vector arguments before assigning them.

Parameters

validate

Whether to validate first.

Returns

A pointer to this application, for chaining.

validate_positionals()

auto cli::app_t::validate_positionals ( bool validate = true ) -> app_t *

inline

Validates positionals before assigning them.

Parameters

validate

Whether to validate first.

Returns

A pointer to this application, for chaining.

version()

auto cli::app_t::version ( ) const -> std::string

nodiscard

Renders the version string.

Returns

The version text.

Member Data Documentation

allow_windows_style_options_

bool cli::app_t::allow_windows_style_options_

protected

Initial value:

{
 
 
 
                false
 
            }

Whether /opt is accepted as an option form.

Defaults to enabled on Windows only. Inheritable.

failure_message_

std::function<std::string(const app_t *, const error_t &)> cli::app_t::failure_message_

protected

Initial value:

{
                failure_message::simple}

Renders an error into the message printed by exit. Inheritable.

fallthrough_

bool cli::app_t::fallthrough_ {false}

protected

Whether options may fall through to a parent command.

Lets a parent collect options written after a subcommand name. Inheritable.

require_subcommand_max_

std::size_t cli::app_t::require_subcommand_max_ {0}

protected

Largest number of subcommands accepted; 0 is unlimited. Inheritable.

Parsing stops once this many have been seen.

silent_

bool cli::app_t::silent_ {false}

protected

Whether this subcommand is hidden from the subcommand list.

Useful for a subcommand that only modifies how the parent behaves.

---

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

• /home/mccakit/desktop/repositories/cli11/src/app.cpp