cli::option_group_t Class Reference

An application specialised for grouping options. More...

Inheritance diagram for cli::option_group_t:

Public Member Functions
	option_group_t (std::string group_description, std::string group_name, app_t *parent)
	Constructs an option group.
auto	add_option (option_t *opt) -> option_t *
	Moves an existing option into this group.
auto	add_options (option_t *opt) -> void
	Moves an existing option into this group.
template<typename... args_t>
auto	add_options (option_t *opt, args_t... args) -> void
	Moves several existing options into this group.
auto	add_subcommand (app_t *subcom) -> app_t *
	Moves an existing subcommand into this group.
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.
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	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.
Public Member Functions inherited from cli::app_t
auto	_move_option (option_t *opt, app_t *app) -> void
	Moves an option from one application to another.
	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.
virtual auto	pre_callback () -> void
	Hook run after parsing but before the callbacks.
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.
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.
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.
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.
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.
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.

Additional Inherited Members
enum class	name_match_t : std::uint8_t { none = 0 , exact = 1 , prefix = 2 }
	How closely a name matched. More...
enum class	startup_mode_t : std::uint8_t { stable , enabled , disabled }
	Whether clear leaves this subcommand enabled or disabled. More...
using	missing_t = std::vector<std::pair<detail::classifier_t, std::string>>
	Arguments that matched nothing, paired with how they were classified.
Protected Member Functions inherited from cli::app_t
	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 inherited from cli::app_t
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.
option_defaults_t	option_defaults_ {}
	Settings newly added options inherit. Inheritable.
std::vector< option_ptr_t >	options_ {}
	The options owned by this application.
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.
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.
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.
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.

Detailed Description

An application specialised for grouping options.

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. Create one with app_t::add_option_group.

Constructor & Destructor Documentation

option_group_t()

cli::option_group_t::option_group_t ( std::string group_description, std::string group_name, app_t * parent )

inline

Constructs an option group.

Parameters

group_description	The description shown in help output.
group_name	The group name.
parent	The owning application.

Member Function Documentation

add_option() [1/5]

auto cli::option_group_t::add_option ( option_t * opt ) -> option_t *

inline

Moves an existing option into this group.

Parameters

opt	The option to adopt.

Returns

opt, for chaining.

Exceptions

cli::option_not_found_t

If this group has no parent.

add_option() [2/5]

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() [3/5]

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() [4/5]

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() [5/5]

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_options() [1/2]

auto cli::option_group_t::add_options ( option_t * opt ) -> void

inline

Moves an existing option into this group.

Parameters

opt	The option to adopt.

add_options() [2/2]

template<typename... args_t>

auto cli::option_group_t::add_options ( option_t * opt, args_t... args ) -> void

inline

Moves several existing options into this group.

Parameters

opt	The first option to adopt.
args	The remaining options to adopt.

add_subcommand() [1/3]

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/3]

auto cli::option_group_t::add_subcommand ( app_t * subcom ) -> app_t *

inline

Moves an existing subcommand into this group.

Parameters

subcom

The subcommand to adopt.

Returns

subcom, for chaining.

add_subcommand() [3/3]

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.

---

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

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