Creates a command line program, with very few defaults. More...

#include <CLI11.hpp>

Inheritance diagram for CLI::App:

Collaboration diagram for CLI::App:

Public Member Functions
void	_move_option (Option opt, App app)
	function that could be used by subclasses of App to shift options around into subcommands

Basic
	App (std::string app_description="", std::string app_name="")
	Create a new program. Pass in the same arguments as main(), along with a help string.

	App (const App &)=delete

App &	operator= (const App &)=delete

virtual	~App ()=default
	virtual destructor

App *	callback (std::function< void()> app_callback)

App *	final_callback (std::function< void()> app_callback)

App *	parse_complete_callback (std::function< void()> pc_callback)

App *	preparse_callback (std::function< void(std::size_t)> pp_callback)

App *	name (std::string app_name="")
	Set a name for the app (empty will use parser to set the name)

App *	alias (std::string app_name)
	Set an alias for the app.

App *	allow_extras (bool allow=true)
	Remove the error when extras are left over on the command line.

App *	required (bool require=true)
	Remove the error when extras are left over on the command line.

App *	disabled (bool disable=true)
	Disable the subcommand or option group.

App *	silent (bool silence=true)
	silence the subcommand from showing up in the processed list

App *	disabled_by_default (bool disable=true)
	Set the subcommand to be disabled by default, so on clear(), at the start of each parse it is disabled.

App *	enabled_by_default (bool enable=true)

App *	immediate_callback (bool immediate=true)
	Set the subcommand callback to be executed immediately on subcommand completion.

App *	validate_positionals (bool validate=true)
	Set the subcommand to validate positional arguments before assigning.

App *	allow_config_extras (bool allow=true)
	ignore extras in config files

App *	allow_config_extras (config_extras_mode mode)
	ignore extras in config files

App *	prefix_command (bool allow=true)
	Do not parse anything after the first unrecognized option and return.

App *	ignore_case (bool value=true)
	Ignore case. Subcommands inherit value.

App *	allow_windows_style_options (bool value=true)

App *	positionals_at_end (bool value=true)
	Specify that the positional arguments are only at the end of the sequence.

App *	configurable (bool value=true)
	Specify that the subcommand can be triggered by a config file.

App *	ignore_underscore (bool value=true)
	Ignore underscore. Subcommands inherit value.

App *	formatter (std::shared_ptr< FormatterBase > fmt)
	Set the help formatter.

App *	formatter_fn (std::function< std::string(const App *, std::string, AppFormatMode)> fmt)
	Set the help formatter.

App *	config_formatter (std::shared_ptr< Config > fmt)
	Set the config formatter.

bool	parsed () const
	Check to see if this subcommand was parsed, true only if received on command line.

OptionDefaults *	option_defaults ()
	Get the OptionDefault object, to set option defaults.

Extras for subclassing
virtual void	pre_callback ()

Post parsing
std::size_t	count (std::string option_name) const
	Counts the number of times the given option was passed.

std::vector< App * >	get_subcommands () const

std::vector< const App * >	get_subcommands (const std::function< bool(const App *)> &filter) const

std::vector< App * >	get_subcommands (const std::function< bool(App *)> &filter)

bool	got_subcommand (const App *subcom) const
	Check to see if given subcommand was selected.

bool	got_subcommand (std::string subcommand_name) const
	Check with name instead of pointer to see if subcommand was selected.

App *	excludes (Option *opt)
	Sets excluded options for the subcommand.

App *	excludes (App *app)
	Sets excluded subcommands for the subcommand.

App *	needs (Option *opt)

App *	needs (App *app)

bool	remove_excludes (Option *opt)
	Removes an option from the excludes list of this subcommand.

bool	remove_excludes (App *app)
	Removes a subcommand from the excludes list of this subcommand.

bool	remove_needs (Option *opt)
	Removes an option from the needs list of this subcommand.

bool	remove_needs (App *app)
	Removes a subcommand from the needs list of this subcommand.

Getters
std::shared_ptr< FormatterBase >	get_formatter () const
	Access the formatter.

std::shared_ptr< Config >	get_config_formatter () const
	Access the config formatter.

std::shared_ptr< ConfigBase >	get_config_formatter_base () const
	Access the config formatter as a configBase pointer.

std::string	get_description () const
	Get the app or subcommand description.

App *	description (std::string app_description)
	Set the description of the app.

std::vector< const Option * >	get_options (const std::function< bool(const Option *)> filter={}) const
	Get the list of options (user facing function, so returns raw pointers), has optional filter function.

std::vector< Option * >	get_options (const std::function< bool(Option *)> filter={})
	Non-const version of the above.

Option *	get_option_no_throw (std::string option_name) noexcept
	Get an option by name (noexcept non-const version)

const Option *	get_option_no_throw (std::string option_name) const noexcept
	Get an option by name (noexcept const version)

const Option *	get_option (std::string option_name) const
	Get an option by name.

Option *	get_option (std::string option_name)
	Get an option by name (non-const version)

const Option *	operator[] (const std::string &option_name) const
	Shortcut bracket operator for getting a pointer to an option.

const Option *	operator[] (const char *option_name) const
	Shortcut bracket operator for getting a pointer to an option.

bool	get_ignore_case () const
	Check the status of ignore_case.

bool	get_ignore_underscore () const
	Check the status of ignore_underscore.

bool	get_fallthrough () const
	Check the status of fallthrough.

bool	get_allow_windows_style_options () const
	Check the status of the allow windows style options.

bool	get_positionals_at_end () const
	Check the status of the allow windows style options.

bool	get_configurable () const
	Check the status of the allow windows style options.

const std::string &	get_group () const
	Get the group of this subcommand.

std::string	get_footer () const
	Generate and return the footer.

std::size_t	get_require_subcommand_min () const
	Get the required min subcommand value.

std::size_t	get_require_subcommand_max () const
	Get the required max subcommand value.

std::size_t	get_require_option_min () const
	Get the required min option value.

std::size_t	get_require_option_max () const
	Get the required max option value.

bool	get_prefix_command () const
	Get the prefix command status.

bool	get_allow_extras () const
	Get the status of allow extras.

bool	get_required () const
	Get the status of required.

bool	get_disabled () const
	Get the status of disabled.

bool	get_silent () const
	Get the status of silence.

bool	get_immediate_callback () const
	Get the status of disabled.

bool	get_disabled_by_default () const
	Get the status of disabled by default.

bool	get_enabled_by_default () const
	Get the status of disabled by default.

bool	get_validate_positionals () const
	Get the status of validating positionals.

config_extras_mode	get_allow_config_extras () const
	Get the status of allow extras.

Option *	get_help_ptr ()
	Get a pointer to the help flag.

const Option *	get_help_ptr () const
	Get a pointer to the help flag. (const)

const Option *	get_help_all_ptr () const
	Get a pointer to the help all flag. (const)

Option *	get_config_ptr ()
	Get a pointer to the config option.

const Option *	get_config_ptr () const
	Get a pointer to the config option. (const)

Option *	get_version_ptr ()
	Get a pointer to the version option.

const Option *	get_version_ptr () const
	Get a pointer to the version option. (const)

App *	get_parent ()
	Get the parent of this subcommand (or nullptr if main app)

const App *	get_parent () const
	Get the parent of this subcommand (or nullptr if main app) (const version)

const std::string &	get_name () const
	Get the name of the current app.

const std::vector< std::string > &	get_aliases () const
	Get the aliases of the current app.

App *	clear_aliases ()
	clear all the aliases of the current App

std::string	get_display_name (bool with_aliases=false) const
	Get a display name for an app.

bool	check_name (std::string name_to_check) const
	Check the name, case insensitive and underscore insensitive if set.

std::vector< std::string >	get_groups () const
	Get the groups available directly from this option (in order)

const std::vector< Option * > &	parse_order () const
	This gets a vector of pointers with the original parse order.

std::vector< std::string >	remaining (bool recurse=false) const
	This returns the missing options from the current subcommand.

std::vector< std::string >	remaining_for_passthrough (bool recurse=false) const
	This returns the missing options in a form ready for processing by another command line program.

std::size_t	remaining_size (bool recurse=false) const
	This returns the number of remaining options, minus the – separator.

Protected Member Functions
	App (std::string app_description, std::string app_name, App *parent)
	Special private constructor for subcommand.

void	_validate () const

void	_configure ()

void	run_callback (bool final_mode=false, bool suppress_final_callback=false)
	Internal function to run (App) callback, bottom up.

bool	_valid_subcommand (const std::string &current, bool ignore_used=true) const
	Check to see if a subcommand is valid. Give up immediately if subcommand max has been reached.

detail::Classifier	_recognize (const std::string &current, bool ignore_used_subcommands=true) const
	Selects a Classifier enum based on the type of the current argument.

void	_process_config_file ()
	Read and process a configuration file (main app only)

void	_process_env ()
	Get envname options if not yet passed. Runs on all subcommands.

void	_process_callbacks ()
	Process callbacks. Runs on all subcommands.

void	_process_help_flags (bool trigger_help=false, bool trigger_all_help=false) const

void	_process_requirements ()
	Verify required options and cross requirements. Subcommands too (only if selected).

void	_process ()
	Process callbacks and such.

void	_process_extras ()
	Throw an error if anything is left over and should not be.

void	_process_extras (std::vector< std::string > &args)

void	increment_parsed ()
	Internal function to recursively increment the parsed counter on the current app as well unnamed subcommands.

void	_parse (std::vector< std::string > &args)
	Internal parse function.

void	_parse (std::vector< std::string > &&args)
	Internal parse function.

void	_parse_stream (std::istream &input)
	Internal function to parse a stream.

void	_parse_config (const std::vector< ConfigItem > &args)

bool	_parse_single_config (const ConfigItem &item, std::size_t level=0)
	Fill in a single config option.

bool	_parse_single (std::vector< std::string > &args, bool &positional_only)

std::size_t	_count_remaining_positionals (bool required_only=false) const
	Count the required remaining positional arguments.

bool	_has_remaining_positionals () const
	Count the required remaining positional arguments.

bool	_parse_positional (std::vector< std::string > &args, bool haltOnSubcommand)

App *	_find_subcommand (const std::string &subc_name, bool ignore_disabled, bool ignore_used) const noexcept

bool	_parse_subcommand (std::vector< std::string > &args)

bool	_parse_arg (std::vector< std::string > &args, detail::Classifier current_type)

void	_trigger_pre_parse (std::size_t remaining_args)
	Trigger the pre_parse callback if needed.

App *	_get_fallthrough_parent ()
	Get the appropriate parent to fallthrough to which is the first one that has a name or the main app.

const std::string &	_compare_subcommand_names (const App &subcom, const App &base) const
	Helper function to run through all possible comparisons of subcommand names to check there is no overlap.

void	_move_to_missing (detail::Classifier val_type, const std::string &val)
	Helper function to place extra values in the most appropriate position.

Protected Attributes
Basics
std::string	name_ {}
	Subcommand name or program name (from parser if name is empty)

std::string	description_ {}
	Description of the current program/subcommand.

bool	allow_extras_ {false}
	If true, allow extra arguments (ie, don't throw an error). INHERITABLE.

config_extras_mode	allow_config_extras_ {config_extras_mode::ignore}

bool	prefix_command_ {false}
	If true, return immediately on an unrecognized option (implies allow_extras) INHERITABLE.

bool	has_automatic_name_ {false}
	If set to true the name was automatically generated from the command line vs a user set name.

bool	required_ {false}
	If set to true the subcommand is required to be processed and used, ignored for main app.

bool	disabled_ {false}
	If set to true the subcommand is disabled and cannot be used, ignored for main app.

bool	pre_parse_called_ {false}
	Flag indicating that the pre_parse_callback has been triggered.

bool	immediate_callback_ {false}

std::function< void(std::size_t)>	pre_parse_callback_ {}
	This is a function that runs prior to the start of parsing.

std::function< void()>	parse_complete_callback_ {}
	This is a function that runs when parsing has finished.

std::function< void()>	final_callback_ {}
	This is a function that runs when all processing has completed.

Options
OptionDefaults	option_defaults_ {}
	The default values for options, customizable and changeable INHERITABLE.

std::vector< Option_p >	options_ {}
	The list of options, stored locally.

Config
Option *	config_ptr_ {nullptr}
	Pointer to the config option.

std::shared_ptr< Config >	config_formatter_ {new ConfigTOML()}
	This is the formatter for help printing. Default provided. INHERITABLE (same pointer)

Subcommands
enum class	startup_mode : char { stable , enabled , disabled }

std::vector< App_p >	subcommands_ {}
	Storage for subcommand list.

bool	ignore_case_ {false}
	If true, the program name is not case sensitive INHERITABLE.

bool	ignore_underscore_ {false}
	If true, the program should ignore underscores INHERITABLE.

bool	fallthrough_ {false}
	Allow subcommand fallthrough, so that parent commands can collect commands after subcommand. INHERITABLE.

bool	allow_windows_style_options_
	Allow '/' for options for Windows like options. Defaults to true on Windows, false otherwise. INHERITABLE.

bool	positionals_at_end_ {false}
	specify that positional arguments come at the end of the argument sequence not inheritable

startup_mode	default_startup {startup_mode::stable}

bool	configurable_ {false}
	if set to true the subcommand can be triggered via configuration files INHERITABLE

bool	validate_positionals_ {false}
	If set to true positional options are validated before assigning INHERITABLE.

bool	silent_ {false}

std::uint32_t	parsed_ {0U}
	Counts the number of times this command/subcommand was parsed.

std::size_t	require_subcommand_min_ {0}
	Minimum required subcommands (not inheritable!)

std::size_t	require_subcommand_max_ {0}
	Max number of subcommands allowed (parsing stops after this number). 0 is unlimited INHERITABLE.

std::size_t	require_option_min_ {0}
	Minimum required options (not inheritable!)

std::size_t	require_option_max_ {0}
	Max number of options allowed. 0 is unlimited (not inheritable)

App *	parent_ {nullptr}
	A pointer to the parent if this is a subcommand.

std::string	group_ {"Subcommands"}
	The group membership INHERITABLE.

std::vector< std::string >	aliases_ {}
	Alias names for the subcommand.

App *	add_subcommand (std::string subcommand_name="", std::string subcommand_description="")
	Add a subcommand. Inherits INHERITABLE and OptionDefaults, and help flag.

App *	add_subcommand (CLI::App_p subcom)
	Add a previously created app as a subcommand.

bool	remove_subcommand (App *subcom)
	Removes a subcommand from the App. Takes a subcommand pointer. Returns true if found and removed.

App *	get_subcommand (const App *subcom) const

App *	get_subcommand (std::string subcom) const
	Check to see if a subcommand is part of this command (text version)

App *	get_subcommand (int index=0) const
	Get a pointer to subcommand by index.

CLI::App_p	get_subcommand_ptr (App *subcom) const
	Check to see if a subcommand is part of this command and get a shared_ptr to it.

CLI::App_p	get_subcommand_ptr (std::string subcom) const
	Check to see if a subcommand is part of this command (text version)

CLI::App_p	get_subcommand_ptr (int index=0) const
	Get an owning pointer to subcommand by index.

App *	get_option_group (std::string group_name) const
	Check to see if an option group is part of this App.

std::size_t	count () const

std::size_t	count_all () const

App *	group (std::string group_name)
	Changes the group membership.

App *	require_subcommand ()
	The argumentless form of require subcommand requires 1 or more subcommands.

App *	require_subcommand (int value)

App *	require_subcommand (std::size_t min, std::size_t max)

App *	require_option ()
	The argumentless form of require option requires 1 or more options be used.

App *	require_option (int value)

App *	require_option (std::size_t min, std::size_t max)

App *	fallthrough (bool value=true)

	operator bool () const

Parsing
using	missing_t = std::vector< std::pair< detail::Classifier, std::string > >

missing_t	missing_ {}

std::vector< Option * >	parse_order_ {}
	This is a list of pointers to options with the original parse order.

std::vector< App * >	parsed_subcommands_ {}
	This is a list of the subcommands collected, in order.

std::set< App * >	exclude_subcommands_ {}
	this is a list of subcommands that are exclusionary to this one

std::set< Option * >	exclude_options_ {}

std::set< App * >	need_subcommands_ {}

std::set< Option * >	need_options_ {}

void	clear ()
	Reset the parsed data.

void	parse (int argc, const char const argv)

void	parse (std::string commandline, bool program_name_included=false)

void	parse (std::vector< std::string > &args)

void	parse (std::vector< std::string > &&args)
	The real work is done here. Expects a reversed vector.

void	parse_from_stream (std::istream &input)

void	failure_message (std::function< std::string(const App *, const Error &e)> function)
	Provide a function to print a help message. The function gets access to the App pointer and error.

int	exit (const Error &e, std::ostream &out=std::cout, std::ostream &err=std::cerr) const
	Print a nice error message and return the exit code.

Help
std::string	footer_ {}
	Footer to put after all options in the help output INHERITABLE.

std::function< std::string()>	footer_callback_ {}
	This is a function that generates a footer to put after all other options in help output.

Option *	help_ptr_ {nullptr}
	A pointer to the help flag if there is one INHERITABLE.

Option *	help_all_ptr_ {nullptr}
	A pointer to the help all flag if there is one INHERITABLE.

Option *	version_ptr_ {nullptr}
	A pointer to a version flag if there is one.

std::shared_ptr< FormatterBase >	formatter_ {new Formatter()}
	This is the formatter for help printing. Default provided. INHERITABLE (same pointer)

std::function< std::string(const App *, const Error &e)>	failure_message_ {FailureMessage::simple}
	The error message printing function INHERITABLE.

App *	footer (std::string footer_string)
	Set footer.

App *	footer (std::function< std::string()> footer_function)
	Set footer.

std::string	config_to_str (bool default_also=false, bool write_description=false) const

std::string	help (std::string prev="", AppFormatMode mode=AppFormatMode::Normal) const

std::string	version () const
	Displays a version string.

Adding options
Option *	add_option (std::string option_name, callback_t option_callback, std::string option_description="", bool defaulted=false, std::function< std::string()> func={})

template<typename AssignTo , typename ConvertTo = AssignTo, enable_if_t<!std::is_const< ConvertTo >::value, detail::enabler > = detail::dummy>
Option *	add_option (std::string option_name, AssignTo &variable, std::string option_description="")
	Add option for assigning to a variable.

template<typename AssignTo , enable_if_t<!std::is_const< AssignTo >::value, detail::enabler > = detail::dummy>
Option *	add_option_no_stream (std::string option_name, AssignTo &variable, std::string option_description="")
	Add option for assigning to a variable.

template<typename ArgType >
Option *	add_option_function (std::string option_name, const std::function< void(const ArgType &)> &func, std::string option_description="")
	Add option for a callback of a specific type.

Option *	add_option (std::string option_name)
	Add option with no description or variable assignment.

template<typename T , enable_if_t< std::is_const< T >::value &&std::is_constructible< std::string, T >::value, detail::enabler > = detail::dummy>
Option *	add_option (std::string option_name, T &option_description)
	Add option with description but with no variable assignment or callback.

Option *	set_help_flag (std::string flag_name="", const std::string &help_description="")
	Set a help flag, replace the existing one if present.

Option *	set_help_all_flag (std::string help_name="", const std::string &help_description="")
	Set a help all flag, replaced the existing one if present.

Option *	set_version_flag (std::string flag_name="", const std::string &versionString="", const std::string &version_help="Display program version information and exit")
	Set a version flag and version display string, replace the existing one if present.

Option *	set_version_flag (std::string flag_name, std::function< std::string()> vfunc, const std::string &version_help="Display program version information and exit")
	Generate the version string through a callback function.

Option *	add_flag (std::string flag_name)
	Add a flag with no description or variable assignment.

template<typename T , enable_if_t< std::is_const< T >::value &&std::is_constructible< std::string, T >::value, detail::enabler > = detail::dummy>
Option *	add_flag (std::string flag_name, T &flag_description)

template<typename T , enable_if_t< std::is_constructible< T, std::int64_t >::value &&!is_bool< T >::value, detail::enabler > = detail::dummy>
Option *	add_flag (std::string flag_name, T &flag_count, std::string flag_description="")

template<typename T , enable_if_t<!detail::is_mutable_container< T >::value &&!std::is_const< T >::value &&(!std::is_constructible< T, std::int64_t >::value\|\|is_bool< T >::value) &&!std::is_constructible< std::function< void(int)>, T >::value, detail::enabler > = detail::dummy>
Option *	add_flag (std::string flag_name, T &flag_result, std::string flag_description="")

template<typename T , enable_if_t<!std::is_assignable< std::function< void(std::int64_t)> &, T >::value, detail::enabler > = detail::dummy>
Option *	add_flag (std::string flag_name, std::vector< T > &flag_results, std::string flag_description="")
	Vector version to capture multiple flags.

Option *	add_flag_callback (std::string flag_name, std::function< void(void)> function, std::string flag_description="")
	Add option for callback that is triggered with a true flag and takes no arguments.

Option *	add_flag_function (std::string flag_name, std::function< void(std::int64_t)> function, std::string flag_description="")
	Add option for callback with an integer value.

Option *	set_config (std::string option_name="", std::string default_filename="", const std::string &help_message="Read an ini file", bool config_required=false)
	Set a configuration ini file option, or clear it if no name passed.

bool	remove_option (Option *opt)
	Removes an option from the App. Takes an option pointer. Returns true if found and removed.

template<typename T = Option_group>
T *	add_option_group (std::string group_name, std::string group_description="")
	creates an option group as part of the given app

Detailed Description

Creates a command line program, with very few defaults.

To use, create a new Program() instance with argc, argv, and a help description. The templated add_option methods make it easy to prepare options. Remember to call .start before starting your program, so that the options can be evaluated and the help option doesn't accidentally run your program.

Member Typedef Documentation

◆ missing_t

using CLI::App::missing_t = std::vector<std::pair<detail::Classifier, std::string> >

protected

Member Enumeration Documentation

◆ startup_mode

enum class CLI::App::startup_mode : char

strongprotected

Enumerator
stable
enabled
disabled

Constructor & Destructor Documentation

◆ App() [1/3]

CLI::App::App	(	std::string	app_description,
		std::string	app_name,
		App *	parent
	)

inlineprotected

Special private constructor for subcommand.

OptionDefaults

◆ App() [2/3]

CLI::App::App	(	std::string	app_description = `""`,
		std::string	app_name = `""`
	)

inlineexplicit

Create a new program. Pass in the same arguments as main(), along with a help string.

◆ App() [3/3]

CLI::App::App ( const App & )

delete

◆ ~App()

virtual CLI::App::~App ( )

virtualdefault

virtual destructor

Member Function Documentation

◆ _compare_subcommand_names()

const std::string & CLI::App::_compare_subcommand_names	(	const App &	subcom,
		const App &	base
	)		const

inlineprotected

Helper function to run through all possible comparisons of subcommand names to check there is no overlap.

Here is the call graph for this function:

◆ _configure()

void CLI::App::_configure ( )

inlineprotected

configure subcommands to enable parsing through the current object set the correct fallthrough and prefix for nameless subcommands and manage the automatic enable or disable makes sure parent is set correctly

◆ _count_remaining_positionals()

std::size_t CLI::App::_count_remaining_positionals ( bool required_only = false ) const

inlineprotected

Count the required remaining positional arguments.

Here is the call graph for this function:

◆ _find_subcommand()

App * CLI::App::_find_subcommand	(	const std::string &	subc_name,
		bool	ignore_disabled,
		bool	ignore_used
	)		const

inlineprotectednoexcept

Locate a subcommand by name with two conditions, should disabled subcommands be ignored, and should used subcommands be ignored

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _get_fallthrough_parent()

App * CLI::App::_get_fallthrough_parent ( )

inlineprotected

Get the appropriate parent to fallthrough to which is the first one that has a name or the main app.

Here is the caller graph for this function:

◆ _has_remaining_positionals()

bool CLI::App::_has_remaining_positionals ( ) const

inlineprotected

Count the required remaining positional arguments.

Here is the call graph for this function:

◆ _move_option()

void CLI::App::_move_option	(	Option *	opt,
		App *	app
	)

inline

function that could be used by subclasses of App to shift options around into subcommands

Here is the call graph for this function:

◆ _move_to_missing()

void CLI::App::_move_to_missing	(	detail::Classifier	val_type,
		const std::string &	val
	)

inlineprotected

Helper function to place extra values in the most appropriate position.

◆ _parse() [1/2]

void CLI::App::_parse ( std::vector< std::string > && args )

inlineprotected

Internal parse function.

◆ _parse() [2/2]

void CLI::App::_parse ( std::vector< std::string > & args )

inlineprotected

Internal parse function.

◆ _parse_arg()

bool CLI::App::_parse_arg	(	std::vector< std::string > &	args,
		detail::Classifier	current_type
	)

inlineprotected

Parse a short (false) or long (true) argument, must be at the top of the list return true if the argument was processed or false if nothing was done

if we require a separator add it here

Here is the caller graph for this function:

◆ _parse_config()

void CLI::App::_parse_config ( const std::vector< ConfigItem > & args )

inlineprotected

Parse one config param, return false if not found in any subcommand, remove if it is

If this has more than one dot.separated.name, go into the subcommand matching it Returns true if it managed to find the option, if false you'll need to remove the arg manually.

◆ _parse_positional()

bool CLI::App::_parse_positional	(	std::vector< std::string > &	args,
		bool	haltOnSubcommand
	)

inlineprotected

Parse a positional, go up the tree to check

Parameters

haltOnSubcommand if set to true the operation will not process subcommands merely return false Return true if the positional was used false otherwise

Try to find a local subcommand that is repeated

now try one last gasp at subcommands that have been executed before, go to root app and try to find a subcommand in a broader way, if one exists let the parent deal with it

If this is an option group don't deal with it

We are out of other options this goes to missing

Here is the call graph for this function:

◆ _parse_single()

bool CLI::App::_parse_single	(	std::vector< std::string > &	args,
		bool &	positional_only
	)

inlineprotected

Parse "one" argument (some may eat more than one), delegate to parent if fails, add to missing if missing from main return false if the parse has failed and needs to return to parent

◆ _parse_single_config()

bool CLI::App::_parse_single_config	(	const ConfigItem &	item,
		std::size_t	level = `0`
	)

inlineprotected

Fill in a single config option.

Here is the call graph for this function:

◆ _parse_stream()

void CLI::App::_parse_stream ( std::istream & input )

inlineprotected

Internal function to parse a stream.

◆ _parse_subcommand()

bool CLI::App::_parse_subcommand ( std::vector< std::string > & args )

inlineprotected

Parse a subcommand, modify args and continue

Unlike the others, this one will always allow fallthrough return true if the subcommand was processed false otherwise

Here is the caller graph for this function:

◆ _process()

void CLI::App::_process ( )

inlineprotected

Process callbacks and such.

◆ _process_callbacks()

void CLI::App::_process_callbacks ( )

inlineprotected

Process callbacks. Runs on all subcommands.

Here is the call graph for this function:

◆ _process_config_file()

void CLI::App::_process_config_file ( )

inlineprotected

Read and process a configuration file (main app only)

◆ _process_env()

void CLI::App::_process_env ( )

inlineprotected

Get envname options if not yet passed. Runs on all subcommands.

Here is the call graph for this function:

◆ _process_extras() [1/2]

void CLI::App::_process_extras ( )

inlineprotected

Throw an error if anything is left over and should not be.

◆ _process_extras() [2/2]

void CLI::App::_process_extras ( std::vector< std::string > & args )

inlineprotected

Throw an error if anything is left over and should not be. Modifies the args to fill in the missing items before throwing.

◆ _process_help_flags()

void CLI::App::_process_help_flags	(	bool	trigger_help = `false`,
		bool	trigger_all_help = `false`
	)		const

inlineprotected

Run help flag processing if any are found.

The flags allow recursive calls to remember if there was a help flag on a parent.

Here is the call graph for this function:

◆ _process_requirements()

void CLI::App::_process_requirements ( )

inlineprotected

Verify required options and cross requirements. Subcommands too (only if selected).

Here is the call graph for this function:

◆ _recognize()

detail::Classifier CLI::App::_recognize	(	const std::string &	current,
		bool	ignore_used_subcommands = `true`
	)		const

inlineprotected

Selects a Classifier enum based on the type of the current argument.

◆ _trigger_pre_parse()

void CLI::App::_trigger_pre_parse ( std::size_t remaining_args )

inlineprotected

Trigger the pre_parse callback if needed.

◆ _valid_subcommand()

bool CLI::App::_valid_subcommand	(	const std::string &	current,
		bool	ignore_used = `true`
	)		const

inlineprotected

Check to see if a subcommand is valid. Give up immediately if subcommand max has been reached.

◆ _validate()

void CLI::App::_validate ( ) const

inlineprotected

Check the options to make sure there are no conflicts.

Currently checks to see if multiple positionals exist with unlimited args and checks if the min and max options are feasible

◆ add_flag() [1/5]

Option * CLI::App::add_flag ( std::string flag_name )

inline

Add a flag with no description or variable assignment.

Here is the caller graph for this function:

◆ add_flag() [2/5]

template<typename T , enable_if_t<!std::is_assignable< std::function< void(std::int64_t)> &, T >::value, detail::enabler > = detail::dummy>

Option * CLI::App::add_flag	(	std::string	flag_name,
		std::vector< T > &	flag_results,
		std::string	flag_description = `""`
	)

inline

Vector version to capture multiple flags.

Parameters

flag_results A vector of values with the flag results

◆ add_flag() [3/5]

template<typename T , enable_if_t< std::is_constructible< T, std::int64_t >::value &&!is_bool< T >::value, detail::enabler > = detail::dummy>

Option * CLI::App::add_flag	(	std::string	flag_name,
		T &	flag_count,
		std::string	flag_description = `""`
	)

inline

Add option for flag with integer result - defaults to allowing multiple passings, but can be forced to one if multi_option_policy(CLI::MultiOptionPolicy::Throw) is used.

Parameters

flag_count A variable holding the count

◆ add_flag() [4/5]

template<typename T , enable_if_t< std::is_const< T >::value &&std::is_constructible< std::string, T >::value, detail::enabler > = detail::dummy>

Option * CLI::App::add_flag	(	std::string	flag_name,
		T &	flag_description
	)

inline

Add flag with description but with no variable assignment or callback takes a constant string, if a variable string is passed that variable will be assigned the results from the flag

◆ add_flag() [5/5]

template<typename T , enable_if_t<!detail::is_mutable_container< T >::value &&!std::is_const< T >::value &&(!std::is_constructible< T, std::int64_t >::value||is_bool< T >::value) &&!std::is_constructible< std::function< void(int)>, T >::value, detail::enabler > = detail::dummy>

Option * CLI::App::add_flag	(	std::string	flag_name,
		T &	flag_result,
		std::string	flag_description = `""`
	)

inline

Other type version accepts all other types that are not vectors such as bool, enum, string or other classes that can be converted from a string

Parameters

flag_result A variable holding true if passed

Here is the call graph for this function:

◆ add_flag_callback()

Option * CLI::App::add_flag_callback	(	std::string	flag_name,
		std::function< void(void)>	function,
		std::string	flag_description = `""`
	)

inline

Add option for callback that is triggered with a true flag and takes no arguments.

Parameters

function A function to call, void(void)

Here is the call graph for this function:

◆ add_flag_function()

Option * CLI::App::add_flag_function	(	std::string	flag_name,
		std::function< void(std::int64_t)>	function,
		std::string	flag_description = `""`
	)

inline

Add option for callback with an integer value.

Parameters

function A function to call, void(int)

◆ add_option() [1/4]

Option * CLI::App::add_option ( std::string option_name )

inline

Add option with no description or variable assignment.

◆ add_option() [2/4]

template<typename AssignTo , typename ConvertTo = AssignTo, enable_if_t<!std::is_const< ConvertTo >::value, detail::enabler > = detail::dummy>

Option * CLI::App::add_option	(	std::string	option_name,
		AssignTo &	variable,
		std::string	option_description = `""`
	)

inline

Add option for assigning to a variable.

Parameters

variable The variable to set

Here is the call graph for this function:

◆ add_option() [3/4]

Option * CLI::App::add_option	(	std::string	option_name,
		callback_t	option_callback,
		std::string	option_description = `""`,
		bool	defaulted = `false`,
		std::function< std::string()>	func = `{}`
	)

inline

Add an option, will automatically understand the type for common types.

To use, create a variable with the expected type, and pass it in after the name. After start is called, you can use count to see if the value was passed, and the value will be initialized properly. Numbers, vectors, and strings are supported.

->required(), ->default, and the validators are options, The positional options take an optional number of arguments.

For example,

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

Here is the caller graph for this function:

◆ add_option() [4/4]

template<typename T , enable_if_t< std::is_const< T >::value &&std::is_constructible< std::string, T >::value, detail::enabler > = detail::dummy>

Option * CLI::App::add_option	(	std::string	option_name,
		T &	option_description
	)

inline

Add option with description but with no variable assignment or callback.

◆ add_option_function()

template<typename ArgType >

Option * CLI::App::add_option_function	(	std::string	option_name,
		const std::function< void(const ArgType &)> &	func,
		std::string	option_description = `""`
	)

inline

Add option for a callback of a specific type.

Parameters

func	the callback to execute

Here is the call graph for this function:

◆ add_option_group()

template<typename T = Option_group>

T * CLI::App::add_option_group	(	std::string	group_name,
		std::string	group_description = `""`
	)

inline

creates an option group as part of the given app

◆ add_option_no_stream()

template<typename AssignTo , enable_if_t<!std::is_const< AssignTo >::value, detail::enabler > = detail::dummy>

Option * CLI::App::add_option_no_stream	(	std::string	option_name,
		AssignTo &	variable,
		std::string	option_description = `""`
	)

inline

Add option for assigning to a variable.

Parameters

variable The variable to set

Here is the call graph for this function:

◆ add_subcommand() [1/2]

App * CLI::App::add_subcommand ( CLI::App_p subcom )

inline

Add a previously created app as a subcommand.

◆ add_subcommand() [2/2]

App * CLI::App::add_subcommand	(	std::string	subcommand_name = `""`,
		std::string	subcommand_description = `""`
	)

inline

Add a subcommand. Inherits INHERITABLE and OptionDefaults, and help flag.

◆ alias()

App * CLI::App::alias ( std::string app_name )

inline

Set an alias for the app.

◆ allow_config_extras() [1/2]

App * CLI::App::allow_config_extras ( bool allow = true )

inline

ignore extras in config files

◆ allow_config_extras() [2/2]

App * CLI::App::allow_config_extras ( config_extras_mode mode )

inline

ignore extras in config files

◆ allow_extras()

App * CLI::App::allow_extras ( bool allow = true )

inline

Remove the error when extras are left over on the command line.

◆ allow_windows_style_options()

App * CLI::App::allow_windows_style_options ( bool value = true )

inline

Allow windows style options, such as /opt. First matching short or long name used. Subcommands inherit value.

◆ callback()

App * CLI::App::callback ( std::function< void()> app_callback )

inline

Set a callback for execution when all parsing and processing has completed

Due to a bug in c++11, it is not possible to overload on std::function (fixed in c++14 and backported to c++11 on newer compilers). Use capture by reference to get a pointer to App if needed.

◆ check_name()

bool CLI::App::check_name ( std::string name_to_check ) const

inline

Check the name, case insensitive and underscore insensitive if set.

Here is the caller graph for this function:

◆ clear()

void CLI::App::clear ( )

inline

Reset the parsed data.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clear_aliases()

App * CLI::App::clear_aliases ( )

inline

clear all the aliases of the current App

Here is the call graph for this function:

◆ config_formatter()

App * CLI::App::config_formatter ( std::shared_ptr< Config > fmt )

inline

Set the config formatter.

◆ config_to_str()

std::string CLI::App::config_to_str	(	bool	default_also = `false`,
		bool	write_description = `false`
	)		const

inline

Produce a string that could be read in as a config of the current values of the App. Set default_also to include default arguments. write_descriptions will print a description for the App and for each option.

◆ configurable()

App * CLI::App::configurable ( bool value = true )

inline

Specify that the subcommand can be triggered by a config file.

◆ count() [1/2]

std::size_t CLI::App::count ( ) const

inline

No argument version of count counts the number of times this subcommand was passed in. The main app will return 1. Unnamed subcommands will also return 1 unless otherwise modified in a callback

◆ count() [2/2]

std::size_t CLI::App::count ( std::string option_name ) const

inline

Counts the number of times the given option was passed.

◆ count_all()

std::size_t CLI::App::count_all ( ) const

inline

Get a count of all the arguments processed in options and subcommands, this excludes arguments which were treated as extras.

Here is the call graph for this function:

◆ description()

App * CLI::App::description ( std::string app_description )

inline

Set the description of the app.

◆ disabled()

App * CLI::App::disabled ( bool disable = true )

inline

Disable the subcommand or option group.

Here is the caller graph for this function:

◆ disabled_by_default()

App * CLI::App::disabled_by_default ( bool disable = true )

inline

Set the subcommand to be disabled by default, so on clear(), at the start of each parse it is disabled.

Here is the caller graph for this function:

◆ enabled_by_default()

App * CLI::App::enabled_by_default ( bool enable = true )

inline

Set the subcommand to be enabled by default, so on clear(), at the start of each parse it is enabled (not disabled)

Here is the caller graph for this function:

◆ excludes() [1/2]

App * CLI::App::excludes ( App * app )

inline

Sets excluded subcommands for the subcommand.

◆ excludes() [2/2]

App * CLI::App::excludes ( Option * opt )

inline

Sets excluded options for the subcommand.

◆ exit()

int CLI::App::exit	(	const Error &	e,
		std::ostream &	out = `std::cout`,
		std::ostream &	err = `std::cerr`
	)		const

inline

Print a nice error message and return the exit code.

Avoid printing anything if this is a CLI::RuntimeError

Here is the call graph for this function:

◆ failure_message()

void CLI::App::failure_message ( std::function< std::string(const App *, const Error &e)> function )

inline

Provide a function to print a help message. The function gets access to the App pointer and error.

◆ fallthrough()

App * CLI::App::fallthrough ( bool value = true )

inline

Stop subcommand fallthrough, so that parent commands cannot collect commands after subcommand. Default from parent, usually set on parent.

◆ final_callback()

App * CLI::App::final_callback ( std::function< void()> app_callback )

inline

Set a callback for execution when all parsing and processing has completed aliased as callback

◆ footer() [1/2]

App * CLI::App::footer ( std::function< std::string()> footer_function )

inline

Set footer.

◆ footer() [2/2]

App * CLI::App::footer ( std::string footer_string )

inline

Set footer.

◆ formatter()

App * CLI::App::formatter ( std::shared_ptr< FormatterBase > fmt )

inline

Set the help formatter.

◆ formatter_fn()

App * CLI::App::formatter_fn ( std::function< std::string(const App *, std::string, AppFormatMode)> fmt )

inline

Set the help formatter.

◆ get_aliases()

const std::vector< std::string > & CLI::App::get_aliases ( ) const

inline

Get the aliases of the current app.

Here is the caller graph for this function:

◆ get_allow_config_extras()

config_extras_mode CLI::App::get_allow_config_extras ( ) const

inline

Get the status of allow extras.

◆ get_allow_extras()

bool CLI::App::get_allow_extras ( ) const

inline

Get the status of allow extras.

◆ get_allow_windows_style_options()

bool CLI::App::get_allow_windows_style_options ( ) const

inline

Check the status of the allow windows style options.

◆ get_config_formatter()

std::shared_ptr< Config > CLI::App::get_config_formatter ( ) const

inline

Access the config formatter.

◆ get_config_formatter_base()

std::shared_ptr< ConfigBase > CLI::App::get_config_formatter_base ( ) const

inline

Access the config formatter as a configBase pointer.

◆ get_config_ptr() [1/2]

Option * CLI::App::get_config_ptr ( )

inline

Get a pointer to the config option.

◆ get_config_ptr() [2/2]

const Option * CLI::App::get_config_ptr ( ) const

inline

Get a pointer to the config option. (const)

◆ get_configurable()

bool CLI::App::get_configurable ( ) const

inline

Check the status of the allow windows style options.

Here is the caller graph for this function:

◆ get_description()

std::string CLI::App::get_description ( ) const

inline

Get the app or subcommand description.

Here is the caller graph for this function:

◆ get_disabled()

bool CLI::App::get_disabled ( ) const

inline

Get the status of disabled.

◆ get_disabled_by_default()

bool CLI::App::get_disabled_by_default ( ) const

inline

Get the status of disabled by default.

◆ get_display_name()

std::string CLI::App::get_display_name ( bool with_aliases = false ) const

inline

Get a display name for an app.

Here is the caller graph for this function:

◆ get_enabled_by_default()

bool CLI::App::get_enabled_by_default ( ) const

inline

Get the status of disabled by default.

◆ get_fallthrough()

bool CLI::App::get_fallthrough ( ) const

inline

Check the status of fallthrough.

◆ get_footer()

std::string CLI::App::get_footer ( ) const

inline

Generate and return the footer.

Here is the caller graph for this function:

◆ get_formatter()

std::shared_ptr< FormatterBase > CLI::App::get_formatter ( ) const

inline

Access the formatter.

◆ get_group()

const std::string & CLI::App::get_group ( ) const

inline

Get the group of this subcommand.

Here is the caller graph for this function:

◆ get_groups()

std::vector< std::string > CLI::App::get_groups ( ) const

inline

Get the groups available directly from this option (in order)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_help_all_ptr()

const Option * CLI::App::get_help_all_ptr ( ) const

inline

Get a pointer to the help all flag. (const)

Here is the caller graph for this function:

◆ get_help_ptr() [1/2]

Option * CLI::App::get_help_ptr ( )

inline

Get a pointer to the help flag.

Here is the caller graph for this function:

◆ get_help_ptr() [2/2]

const Option * CLI::App::get_help_ptr ( ) const

inline

Get a pointer to the help flag. (const)

◆ get_ignore_case()

bool CLI::App::get_ignore_case ( ) const

inline

Check the status of ignore_case.

◆ get_ignore_underscore()

bool CLI::App::get_ignore_underscore ( ) const

inline

Check the status of ignore_underscore.

◆ get_immediate_callback()

bool CLI::App::get_immediate_callback ( ) const

inline

Get the status of disabled.

◆ get_name()

const std::string & CLI::App::get_name ( ) const

inline

Get the name of the current app.

Here is the caller graph for this function:

◆ get_option() [1/2]

Option * CLI::App::get_option ( std::string option_name )

inline

Get an option by name (non-const version)

◆ get_option() [2/2]

const Option * CLI::App::get_option ( std::string option_name ) const

inline

Get an option by name.

Here is the caller graph for this function:

◆ get_option_group()

App * CLI::App::get_option_group ( std::string group_name ) const

inline

Check to see if an option group is part of this App.

◆ get_option_no_throw() [1/2]

const Option * CLI::App::get_option_no_throw ( std::string option_name ) const

inlinenoexcept

Get an option by name (noexcept const version)

Here is the call graph for this function:

◆ get_option_no_throw() [2/2]

Option * CLI::App::get_option_no_throw ( std::string option_name )

inlinenoexcept

Get an option by name (noexcept non-const version)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_options() [1/2]

std::vector< const Option * > CLI::App::get_options ( const std::function< bool(const Option *)> filter = {} ) const

inline

Get the list of options (user facing function, so returns raw pointers), has optional filter function.

Here is the caller graph for this function:

◆ get_options() [2/2]

std::vector< Option * > CLI::App::get_options ( const std::function< bool(Option *)> filter = {} )

inline

Non-const version of the above.

◆ get_parent() [1/2]

App * CLI::App::get_parent ( )

inline

Get the parent of this subcommand (or nullptr if main app)

Here is the caller graph for this function:

◆ get_parent() [2/2]

const App * CLI::App::get_parent ( ) const

inline

Get the parent of this subcommand (or nullptr if main app) (const version)

◆ get_positionals_at_end()

bool CLI::App::get_positionals_at_end ( ) const

inline

Check the status of the allow windows style options.

◆ get_prefix_command()

bool CLI::App::get_prefix_command ( ) const

inline

Get the prefix command status.

◆ get_require_option_max()

std::size_t CLI::App::get_require_option_max ( ) const

inline

Get the required max option value.

Here is the caller graph for this function:

◆ get_require_option_min()

std::size_t CLI::App::get_require_option_min ( ) const

inline

Get the required min option value.

Here is the caller graph for this function:

◆ get_require_subcommand_max()

std::size_t CLI::App::get_require_subcommand_max ( ) const

inline

Get the required max subcommand value.

Here is the caller graph for this function:

◆ get_require_subcommand_min()

std::size_t CLI::App::get_require_subcommand_min ( ) const

inline

Get the required min subcommand value.

Here is the caller graph for this function:

◆ get_required()

bool CLI::App::get_required ( ) const

inline

Get the status of required.

Here is the caller graph for this function:

◆ get_silent()

bool CLI::App::get_silent ( ) const

inline

Get the status of silence.

◆ get_subcommand() [1/3]

App * CLI::App::get_subcommand ( const App * subcom ) const

inline

Check to see if a subcommand is part of this command (doesn't have to be in command line) returns the first subcommand if passed a nullptr

Here is the call graph for this function:

◆ get_subcommand() [2/3]

App * CLI::App::get_subcommand ( int index = 0 ) const

inline

Get a pointer to subcommand by index.

◆ get_subcommand() [3/3]

App * CLI::App::get_subcommand ( std::string subcom ) const

inline

Check to see if a subcommand is part of this command (text version)

◆ get_subcommand_ptr() [1/3]

CLI::App_p CLI::App::get_subcommand_ptr ( App * subcom ) const

inline

Check to see if a subcommand is part of this command and get a shared_ptr to it.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_subcommand_ptr() [2/3]

CLI::App_p CLI::App::get_subcommand_ptr ( int index = 0 ) const

inline

Get an owning pointer to subcommand by index.

◆ get_subcommand_ptr() [3/3]

CLI::App_p CLI::App::get_subcommand_ptr ( std::string subcom ) const

inline

Check to see if a subcommand is part of this command (text version)

◆ get_subcommands() [1/3]

std::vector< App * > CLI::App::get_subcommands ( ) const

inline

Get a subcommand pointer list to the currently selected subcommands (after parsing by default, in command line order; use parsed = false to get the original definition list.)

Here is the caller graph for this function:

◆ get_subcommands() [2/3]

std::vector< App * > CLI::App::get_subcommands ( const std::function< bool(App *)> & filter )

inline

Get a filtered subcommand pointer list from the original definition list. An empty function will provide all subcommands

◆ get_subcommands() [3/3]

std::vector< const App * > CLI::App::get_subcommands ( const std::function< bool(const App *)> & filter ) const

inline

Get a filtered subcommand pointer list from the original definition list. An empty function will provide all subcommands (const)

◆ get_validate_positionals()

bool CLI::App::get_validate_positionals ( ) const

inline

Get the status of validating positionals.

◆ get_version_ptr() [1/2]

Option * CLI::App::get_version_ptr ( )

inline

Get a pointer to the version option.

◆ get_version_ptr() [2/2]

const Option * CLI::App::get_version_ptr ( ) const

inline

Get a pointer to the version option. (const)

◆ got_subcommand() [1/2]

bool CLI::App::got_subcommand ( const App * subcom ) const

inline

Check to see if given subcommand was selected.

Here is the caller graph for this function:

◆ got_subcommand() [2/2]

bool CLI::App::got_subcommand ( std::string subcommand_name ) const

inline

Check with name instead of pointer to see if subcommand was selected.

◆ group()

App * CLI::App::group ( std::string group_name )

inline

Changes the group membership.

◆ help()

std::string CLI::App::help	(	std::string	prev = `""`,
		AppFormatMode	mode = `AppFormatMode::Normal`
	)		const

inline

Makes a help message, using the currently configured formatter Will only do one subcommand at a time

Here is the caller graph for this function:

◆ ignore_case()

App * CLI::App::ignore_case ( bool value = true )

inline

Ignore case. Subcommands inherit value.

◆ ignore_underscore()

App * CLI::App::ignore_underscore ( bool value = true )

inline

Ignore underscore. Subcommands inherit value.

◆ immediate_callback()

App * CLI::App::immediate_callback ( bool immediate = true )

inline

Set the subcommand callback to be executed immediately on subcommand completion.

◆ increment_parsed()

void CLI::App::increment_parsed ( )

inlineprotected

Internal function to recursively increment the parsed counter on the current app as well unnamed subcommands.

◆ name()

App * CLI::App::name ( std::string app_name = "" )

inline

Set a name for the app (empty will use parser to set the name)

◆ needs() [1/2]

App * CLI::App::needs ( App * app )

inline

◆ needs() [2/2]

App * CLI::App::needs ( Option * opt )

inline

◆ operator bool()

CLI::App::operator bool ( ) const

inlineexplicit

Check to see if this subcommand was parsed, true only if received on command line. This allows the subcommand to be directly checked.

◆ operator=()

App & CLI::App::operator= ( const App & )

delete

◆ operator[]() [1/2]

const Option * CLI::App::operator[] ( const char * option_name ) const

inline

Shortcut bracket operator for getting a pointer to an option.

◆ operator[]() [2/2]

const Option * CLI::App::operator[] ( const std::string & option_name ) const

inline

Shortcut bracket operator for getting a pointer to an option.

◆ option_defaults()

OptionDefaults * CLI::App::option_defaults ( )

inline

Get the OptionDefault object, to set option defaults.

◆ parse() [1/4]

void CLI::App::parse	(	int	argc,
		const char const	argv
	)

inline

Parses the command line - throws errors. This must be called after the options are in but before the rest of the program.

◆ parse() [2/4]

void CLI::App::parse	(	std::string	commandline,
		bool	program_name_included = `false`
	)

inline

Parse a single string as if it contained command line arguments. This function splits the string into arguments then calls parse(std::vector<std::string> &) the function takes an optional boolean argument specifying if the programName is included in the string to process

◆ parse() [3/4]

void CLI::App::parse ( std::vector< std::string > && args )

inline

The real work is done here. Expects a reversed vector.

◆ parse() [4/4]

void CLI::App::parse ( std::vector< std::string > & args )

inline

The real work is done here. Expects a reversed vector. Changes the vector to the remaining options.

◆ parse_complete_callback()

App * CLI::App::parse_complete_callback ( std::function< void()> pc_callback )

inline

Set a callback to execute when parsing has completed for the app

◆ parse_from_stream()

void CLI::App::parse_from_stream ( std::istream & input )

inline

◆ parse_order()

const std::vector< Option * > & CLI::App::parse_order ( ) const

inline

This gets a vector of pointers with the original parse order.

◆ parsed()

bool CLI::App::parsed ( ) const

inline

Check to see if this subcommand was parsed, true only if received on command line.

◆ positionals_at_end()

App * CLI::App::positionals_at_end ( bool value = true )

inline

Specify that the positional arguments are only at the end of the sequence.

◆ pre_callback()

virtual void CLI::App::pre_callback ( )

inlinevirtual

This allows subclasses to inject code before callbacks but after parse.

This does not run if any errors or help is thrown.

◆ prefix_command()

App * CLI::App::prefix_command ( bool allow = true )

inline

Do not parse anything after the first unrecognized option and return.

◆ preparse_callback()

App * CLI::App::preparse_callback ( std::function< void(std::size_t)> pp_callback )

inline

Set a callback to execute prior to parsing.

Here is the caller graph for this function:

◆ remaining()

std::vector< std::string > CLI::App::remaining ( bool recurse = false ) const

inline

This returns the missing options from the current subcommand.

◆ remaining_for_passthrough()

std::vector< std::string > CLI::App::remaining_for_passthrough ( bool recurse = false ) const

inline

This returns the missing options in a form ready for processing by another command line program.

◆ remaining_size()

std::size_t CLI::App::remaining_size ( bool recurse = false ) const

inline

This returns the number of remaining options, minus the – separator.

◆ remove_excludes() [1/2]

bool CLI::App::remove_excludes ( App * app )

inline

Removes a subcommand from the excludes list of this subcommand.

◆ remove_excludes() [2/2]

bool CLI::App::remove_excludes ( Option * opt )

inline

Removes an option from the excludes list of this subcommand.

◆ remove_needs() [1/2]

bool CLI::App::remove_needs ( App * app )

inline

Removes a subcommand from the needs list of this subcommand.

◆ remove_needs() [2/2]

bool CLI::App::remove_needs ( Option * opt )

inline

Removes an option from the needs list of this subcommand.

◆ remove_option()

bool CLI::App::remove_option ( Option * opt )

inline

Removes an option from the App. Takes an option pointer. Returns true if found and removed.

Here is the caller graph for this function:

◆ remove_subcommand()

bool CLI::App::remove_subcommand ( App * subcom )

inline

Removes a subcommand from the App. Takes a subcommand pointer. Returns true if found and removed.

◆ require_option() [1/3]

App * CLI::App::require_option ( )

inline

The argumentless form of require option requires 1 or more options be used.

◆ require_option() [2/3]

App * CLI::App::require_option ( int value )

inline

Require an option to be given (does not affect help call) The number required can be given. Negative values indicate maximum number allowed (0 for any number).

◆ require_option() [3/3]

App * CLI::App::require_option	(	std::size_t	min,
		std::size_t	max
	)

inline

Explicitly control the number of options required. Setting 0 for the max means unlimited number allowed. Max number inheritable.

◆ require_subcommand() [1/3]

App * CLI::App::require_subcommand ( )

inline

The argumentless form of require subcommand requires 1 or more subcommands.

◆ require_subcommand() [2/3]

App * CLI::App::require_subcommand ( int value )

inline

Require a subcommand to be given (does not affect help call) The number required can be given. Negative values indicate maximum number allowed (0 for any number). Max number inheritable.

◆ require_subcommand() [3/3]

App * CLI::App::require_subcommand	(	std::size_t	min,
		std::size_t	max
	)

inline

Explicitly control the number of subcommands required. Setting 0 for the max means unlimited number allowed. Max number inheritable.

◆ required()

App * CLI::App::required ( bool require = true )

inline

Remove the error when extras are left over on the command line.

◆ run_callback()

void CLI::App::run_callback	(	bool	final_mode = `false`,
		bool	suppress_final_callback = `false`
	)

inlineprotected

Internal function to run (App) callback, bottom up.

◆ set_config()

Option * CLI::App::set_config	(	std::string	option_name = `""`,
		std::string	default_filename = `""`,
		const std::string &	help_message = `"Read an ini file"`,
		bool	config_required = `false`
	)

inline

Set a configuration ini file option, or clear it if no name passed.

◆ set_help_all_flag()

Option * CLI::App::set_help_all_flag	(	std::string	help_name = `""`,
		const std::string &	help_description = `""`
	)

inline

Set a help all flag, replaced the existing one if present.

◆ set_help_flag()

Option * CLI::App::set_help_flag	(	std::string	flag_name = `""`,
		const std::string &	help_description = `""`
	)

inline

Set a help flag, replace the existing one if present.

◆ set_version_flag() [1/2]

Option * CLI::App::set_version_flag	(	std::string	flag_name,
		std::function< std::string()>	vfunc,
		const std::string &	version_help = `"Display program version information and exit"`
	)

inline

Generate the version string through a callback function.

◆ set_version_flag() [2/2]

Option * CLI::App::set_version_flag	(	std::string	flag_name = `""`,
		const std::string &	versionString = `""`,
		const std::string &	version_help = `"Display program version information and exit"`
	)

inline

Set a version flag and version display string, replace the existing one if present.

◆ silent()

App * CLI::App::silent ( bool silence = true )

inline

silence the subcommand from showing up in the processed list

◆ validate_positionals()

App * CLI::App::validate_positionals ( bool validate = true )

inline

Set the subcommand to validate positional arguments before assigning.

◆ version()

std::string CLI::App::version ( ) const

inline

Displays a version string.

Member Data Documentation

◆ aliases_

std::vector<std::string> CLI::App::aliases_ {}

protected

Alias names for the subcommand.

◆ allow_config_extras_

config_extras_mode CLI::App::allow_config_extras_ {config_extras_mode::ignore}

protected

If ignore, allow extra arguments in the ini file (ie, don't throw an error). INHERITABLE if error error on an extra argument, and if capture feed it to the app

◆ allow_extras_

bool CLI::App::allow_extras_ {false}

protected

If true, allow extra arguments (ie, don't throw an error). INHERITABLE.

◆ allow_windows_style_options_

bool CLI::App::allow_windows_style_options_

protected

Initial value:

{
 
        false
 
    }

Allow '/' for options for Windows like options. Defaults to true on Windows, false otherwise. INHERITABLE.

◆ config_formatter_

std::shared_ptr<Config> CLI::App::config_formatter_ {new ConfigTOML()}

protected

This is the formatter for help printing. Default provided. INHERITABLE (same pointer)

◆ config_ptr_

Option* CLI::App::config_ptr_ {nullptr}

protected

Pointer to the config option.

◆ configurable_

bool CLI::App::configurable_ {false}

protected

if set to true the subcommand can be triggered via configuration files INHERITABLE

◆ default_startup

startup_mode CLI::App::default_startup {startup_mode::stable}

protected

specify the startup mode for the app stable=no change, enabled= startup enabled, disabled=startup disabled

◆ description_

std::string CLI::App::description_ {}

protected

Description of the current program/subcommand.

◆ disabled_

bool CLI::App::disabled_ {false}

protected

If set to true the subcommand is disabled and cannot be used, ignored for main app.

◆ exclude_options_

std::set<Option *> CLI::App::exclude_options_ {}

protected

This is a list of options which are exclusionary to this App, if the options were used this subcommand should not be

◆ exclude_subcommands_

std::set<App *> CLI::App::exclude_subcommands_ {}

protected

this is a list of subcommands that are exclusionary to this one

◆ failure_message_

std::function<std::string(const App *, const Error &e)> CLI::App::failure_message_ {FailureMessage::simple}

protected

The error message printing function INHERITABLE.

◆ fallthrough_

bool CLI::App::fallthrough_ {false}

protected

Allow subcommand fallthrough, so that parent commands can collect commands after subcommand. INHERITABLE.

◆ final_callback_

std::function<void()> CLI::App::final_callback_ {}

protected

This is a function that runs when all processing has completed.

◆ footer_

std::string CLI::App::footer_ {}

protected

Footer to put after all options in the help output INHERITABLE.

◆ footer_callback_

std::function<std::string()> CLI::App::footer_callback_ {}

protected

This is a function that generates a footer to put after all other options in help output.

◆ formatter_

std::shared_ptr<FormatterBase> CLI::App::formatter_ {new Formatter()}

protected

This is the formatter for help printing. Default provided. INHERITABLE (same pointer)

◆ group_

std::string CLI::App::group_ {"Subcommands"}

protected

The group membership INHERITABLE.

◆ has_automatic_name_

bool CLI::App::has_automatic_name_ {false}

protected

If set to true the name was automatically generated from the command line vs a user set name.

◆ help_all_ptr_

Option* CLI::App::help_all_ptr_ {nullptr}

protected

A pointer to the help all flag if there is one INHERITABLE.

◆ help_ptr_

Option* CLI::App::help_ptr_ {nullptr}

protected

A pointer to the help flag if there is one INHERITABLE.

◆ ignore_case_

bool CLI::App::ignore_case_ {false}

protected

If true, the program name is not case sensitive INHERITABLE.

◆ ignore_underscore_

bool CLI::App::ignore_underscore_ {false}

protected

If true, the program should ignore underscores INHERITABLE.

◆ immediate_callback_

bool CLI::App::immediate_callback_ {false}

protected

Flag indicating that the callback for the subcommand should be executed immediately on parse completion which is before help or ini files are processed. INHERITABLE

◆ missing_

missing_t CLI::App::missing_ {}

protected

Pair of classifier, string for missing options. (extra detail is removed on returning from parse)

This is faster and cleaner than storing just a list of strings and reparsing. This may contain the – separator.

◆ name_

std::string CLI::App::name_ {}

protected

Subcommand name or program name (from parser if name is empty)

◆ need_options_

std::set<Option *> CLI::App::need_options_ {}

protected

This is a list of options which are required by this app, the list is not mutual, listed options do not need the subcommand not be

◆ need_subcommands_

std::set<App *> CLI::App::need_subcommands_ {}

protected

this is a list of subcommands or option groups that are required by this one, the list is not mutual, the listed subcommands do not require this one

◆ option_defaults_

OptionDefaults CLI::App::option_defaults_ {}

protected

The default values for options, customizable and changeable INHERITABLE.

◆ options_

std::vector<Option_p> CLI::App::options_ {}

protected

The list of options, stored locally.

◆ parent_

App* CLI::App::parent_ {nullptr}

protected

A pointer to the parent if this is a subcommand.

◆ parse_complete_callback_

std::function<void()> CLI::App::parse_complete_callback_ {}

protected

This is a function that runs when parsing has finished.

◆ parse_order_

std::vector<Option *> CLI::App::parse_order_ {}

protected

This is a list of pointers to options with the original parse order.

◆ parsed_

std::uint32_t CLI::App::parsed_ {0U}

protected

Counts the number of times this command/subcommand was parsed.

◆ parsed_subcommands_

std::vector<App *> CLI::App::parsed_subcommands_ {}

protected

This is a list of the subcommands collected, in order.

◆ positionals_at_end_

bool CLI::App::positionals_at_end_ {false}

protected

specify that positional arguments come at the end of the argument sequence not inheritable

◆ pre_parse_callback_

std::function<void(std::size_t)> CLI::App::pre_parse_callback_ {}

protected

This is a function that runs prior to the start of parsing.

◆ pre_parse_called_

bool CLI::App::pre_parse_called_ {false}

protected

Flag indicating that the pre_parse_callback has been triggered.

◆ prefix_command_

bool CLI::App::prefix_command_ {false}

protected

If true, return immediately on an unrecognized option (implies allow_extras) INHERITABLE.

◆ require_option_max_

std::size_t CLI::App::require_option_max_ {0}

protected

Max number of options allowed. 0 is unlimited (not inheritable)

◆ require_option_min_

std::size_t CLI::App::require_option_min_ {0}

protected

Minimum required options (not inheritable!)

◆ require_subcommand_max_

std::size_t CLI::App::require_subcommand_max_ {0}

protected

Max number of subcommands allowed (parsing stops after this number). 0 is unlimited INHERITABLE.

◆ require_subcommand_min_

std::size_t CLI::App::require_subcommand_min_ {0}

protected

Minimum required subcommands (not inheritable!)

◆ required_

bool CLI::App::required_ {false}

protected

If set to true the subcommand is required to be processed and used, ignored for main app.

◆ silent_

bool CLI::App::silent_ {false}

protected

indicator that the subcommand is silent and won't show up in subcommands list This is potentially useful as a modifier subcommand

◆ subcommands_

std::vector<App_p> CLI::App::subcommands_ {}

protected

Storage for subcommand list.

◆ validate_positionals_

bool CLI::App::validate_positionals_ {false}

protected

If set to true positional options are validated before assigning INHERITABLE.

◆ version_ptr_

Option* CLI::App::version_ptr_ {nullptr}

protected

A pointer to a version flag if there is one.

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

CLI11.hpp

Public Member Functions

Protected Member Functions

Protected Attributes

Subcommands

Parsing

Help

Adding options

Detailed Description

Member Typedef Documentation

◆ missing_t

Member Enumeration Documentation

◆ startup_mode

Constructor & Destructor Documentation

◆ App() [1/3]

◆ App() [2/3]

◆ App() [3/3]

◆ ~App()

Member Function Documentation

◆ _compare_subcommand_names()

◆ _configure()

◆ _count_remaining_positionals()

◆ _find_subcommand()

◆ _get_fallthrough_parent()

◆ _has_remaining_positionals()

◆ _move_option()

◆ _move_to_missing()

◆ _parse() [1/2]

◆ _parse() [2/2]

◆ _parse_arg()

◆ _parse_config()

◆ _parse_positional()

◆ _parse_single()

◆ _parse_single_config()

◆ _parse_stream()

◆ _parse_subcommand()

◆ _process()

◆ _process_callbacks()

◆ _process_config_file()

◆ _process_env()

◆ _process_extras() [1/2]

◆ _process_extras() [2/2]

◆ _process_help_flags()

◆ _process_requirements()

◆ _recognize()

◆ _trigger_pre_parse()

◆ _valid_subcommand()

◆ _validate()

◆ add_flag() [1/5]

◆ add_flag() [2/5]

◆ add_flag() [3/5]

◆ add_flag() [4/5]

◆ add_flag() [5/5]

◆ add_flag_callback()

◆ add_flag_function()

◆ add_option() [1/4]

◆ add_option() [2/4]

◆ add_option() [3/4]

◆ add_option() [4/4]

◆ add_option_function()

◆ add_option_group()

◆ add_option_no_stream()

◆ add_subcommand() [1/2]

◆ add_subcommand() [2/2]

◆ alias()

◆ allow_config_extras() [1/2]

◆ allow_config_extras() [2/2]

◆ allow_extras()

◆ allow_windows_style_options()

◆ callback()

◆ check_name()

◆ clear()

◆ clear_aliases()

◆ config_formatter()

◆ config_to_str()

◆ configurable()

◆ count() [1/2]

◆ count() [2/2]

◆ count_all()

◆ description()

◆ disabled()