Loading...
Searching...
No Matches
CLI::App Class Reference

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

`#include <App.hpp>`

Inheritance 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
CLI11_NODISCARD char ** | ensure_utf8 (char **argv)
| Convert the contents of argv to UTF-8. Only does something on Windows, does nothing elsewhere.
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 * | allow_non_standard_option_names (bool allowed=true)
| allow non standard option names
App * | allow_subcommand_prefix_matching (bool allowed=true)
| allow prefix matching for subcommands
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 * | validate_optional_arguments (bool validate=true)
| Set the subcommand to validate optional vector 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 is_prefix=true)
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.
CLI11_NODISCARD 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
CLI11_NODISCARD std::size_t | count (std::string option_name) const
| Counts the number of times the given option was passed.
CLI11_NODISCARD 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.
CLI11_NODISCARD bool | got_subcommand (std::string subcommand_name) const noexcept
| 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.

## 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.
CLI11_NODISCARD 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.
CLI11_NODISCARD 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).
bool | _process_config_file (const std::string &config_file, bool throw_error)
| Read and process a particular configuration file.
void | _process_env ()
| Get envname options if not yet passed. Runs on all subcommands.
void | _process_callbacks (CallbackPriority priority)
| Process callbacks. Runs on all subcommands.
void | _process_help_flags (CallbackPriority priority, 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 | _add_flag_like_result (Option *op, const ConfigItem &item, const std::vector< std::string > &inputs)
| store the results for a flag like option
bool | _parse_single (std::vector< std::string > &args, bool &positional_only)
CLI11_NODISCARD std::size_t | _count_remaining_positionals (bool required_only=false) const
| Count the required remaining positional arguments.
CLI11_NODISCARD bool | _has_remaining_positionals () const
| Count the required remaining positional arguments.
bool | _parse_positional (std::vector< std::string > &args, bool haltOnSubcommand)
CLI11_NODISCARD 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, bool local_processing_only)
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.
CLI11_NODISCARD 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, cease processing 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 : std::uint8_t { 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}
bool | subcommand_fallthrough_ {true}
| Allow subcommands to fallthrough, so that parent commands can trigger other subcommands after subcommand.
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 | validate_optional_arguments_ {false}
| If set to true optional vector arguments are validated before assigning INHERITABLE.
bool | silent_ {false}
bool | allow_non_standard_options_ {false}
| indicator that the subcommand should allow non-standard option arguments, such as -single_dash_flag
bool | allow_prefix_matching_ {false}
| indicator to allow subcommands to match with prefix matching
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
CLI11_NODISCARD App * | get_subcommand (std::string subcom) const
| Check to see if a subcommand is part of this command (text version).
CLI11_NODISCARD App * | get_subcommand_no_throw (std::string subcom) const noexcept
CLI11_NODISCARD 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.
CLI11_NODISCARD CLI::App_p | get_subcommand_ptr (std::string subcom) const
| Check to see if a subcommand is part of this command (text version).
CLI11_NODISCARD CLI::App_p | get_subcommand_ptr (int index=0) const
| Get an owning pointer to subcommand by index.
CLI11_NODISCARD App * | get_option_group (std::string group_name) const
| Check to see if an option group is part of this App.
CLI11_NODISCARD std::size_t | count () const
CLI11_NODISCARD 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)
App * | subcommand_fallthrough (bool value=true)
| Set subcommand fallthrough, set to true so that subcommands on parents are recognized.
| 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 (int argc, const wchar_t *const *argv)
void | parse (std::string commandline, bool program_name_included=false)
void | parse (std::wstring 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.

## Getters

enum class | NameMatch : std::uint8_t { none = 0 , exact = 1 , prefix = 2 }
| enumeration of matching possibilities More...
CLI11_NODISCARD std::shared_ptr< FormatterBase > | get_formatter () const
| Access the formatter.
CLI11_NODISCARD std::shared_ptr< Config > | get_config_formatter () const
| Access the config formatter.
CLI11_NODISCARD std::shared_ptr< ConfigBase > | get_config_formatter_base () const
| Access the config formatter as a configBase pointer.
CLI11_NODISCARD 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.
CLI11_NODISCARD Option * | get_option_no_throw (std::string option_name) noexcept
| Get an option by name (noexcept non-const version).
CLI11_NODISCARD const Option * | get_option_no_throw (std::string option_name) const noexcept
| Get an option by name (noexcept const version).
CLI11_NODISCARD 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.
CLI11_NODISCARD bool | get_ignore_case () const
| Check the status of ignore_case.
CLI11_NODISCARD bool | get_ignore_underscore () const
| Check the status of ignore_underscore.
CLI11_NODISCARD bool | get_fallthrough () const
| Check the status of fallthrough.
CLI11_NODISCARD bool | get_subcommand_fallthrough () const
| Check the status of subcommand fallthrough.
CLI11_NODISCARD bool | get_allow_windows_style_options () const
| Check the status of the allow windows style options.
CLI11_NODISCARD bool | get_positionals_at_end () const
| Check the status of the allow windows style options.
CLI11_NODISCARD bool | get_configurable () const
| Check the status of the allow windows style options.
CLI11_NODISCARD const std::string & | get_group () const
| Get the group of this subcommand.
CLI11_NODISCARD std::string | get_usage () const
| Generate and return the usage.
CLI11_NODISCARD std::string | get_footer () const
| Generate and return the footer.
CLI11_NODISCARD std::size_t | get_require_subcommand_min () const
| Get the required min subcommand value.
CLI11_NODISCARD std::size_t | get_require_subcommand_max () const
| Get the required max subcommand value.
CLI11_NODISCARD std::size_t | get_require_option_min () const
| Get the required min option value.
CLI11_NODISCARD std::size_t | get_require_option_max () const
| Get the required max option value.
CLI11_NODISCARD bool | get_prefix_command () const
| Get the prefix command status.
CLI11_NODISCARD bool | get_allow_extras () const
| Get the status of allow extras.
CLI11_NODISCARD bool | get_required () const
| Get the status of required.
CLI11_NODISCARD bool | get_disabled () const
| Get the status of disabled.
CLI11_NODISCARD bool | get_silent () const
| Get the status of silence.
CLI11_NODISCARD bool | get_allow_non_standard_option_names () const
| Get the status of allowing non standard option names.
CLI11_NODISCARD bool | get_allow_subcommand_prefix_matching () const
| Get the status of allowing prefix matching for subcommands.
CLI11_NODISCARD bool | get_immediate_callback () const
| Get the status of disabled.
CLI11_NODISCARD bool | get_disabled_by_default () const
| Get the status of disabled by default.
CLI11_NODISCARD bool | get_enabled_by_default () const
| Get the status of disabled by default.
CLI11_NODISCARD bool | get_validate_positionals () const
| Get the status of validating positionals.
CLI11_NODISCARD bool | get_validate_optional_arguments () const
| Get the status of validating optional vector arguments.
CLI11_NODISCARD 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.
CLI11_NODISCARD const Option * | get_help_ptr () const
| Get a pointer to the help flag. (const).
CLI11_NODISCARD 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.
CLI11_NODISCARD 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.
CLI11_NODISCARD 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).
CLI11_NODISCARD const App * | get_parent () const
| Get the parent of this subcommand (or nullptr if main app) (const version).
CLI11_NODISCARD const std::string & | get_name () const
| Get the name of the current app.
CLI11_NODISCARD 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
CLI11_NODISCARD std::string | get_display_name (bool with_aliases=false) const
| Get a display name for an app.
CLI11_NODISCARD bool | check_name (std::string name_to_check) const
CLI11_NODISCARD NameMatch | check_name_detail (std::string name_to_check) const
CLI11_NODISCARD std::vector< std::string > | get_groups () const
| Get the groups available directly from this option (in order).
CLI11_NODISCARD const std::vector< Option * > & | parse_order () const
| This gets a vector of pointers with the original parse order.
CLI11_NODISCARD std::vector< std::string > | remaining (bool recurse=false) const
| This returns the missing options from the current subcommand.
CLI11_NODISCARD 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.
CLI11_NODISCARD std::size_t | remaining_size (bool recurse=false) const
| This returns the number of remaining options, minus the – separator.

## Help

std::string | usage_ {}
| Usage to put after program/subcommand description in the help output INHERITABLE.
std::function< std::string()> | usage_callback_ {}
| This is a function that generates a usage to put after program/subcommand description in help output.
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 * | usage (std::string usage_string)
| Set usage.
App * | usage (std::function< std::string()> usage_function)
| Set usage.
App * | footer (std::string footer_string)
| Set footer.
App * | footer (std::function< std::string()> footer_function)
| Set footer.
CLI11_NODISCARD std::string | config_to_str (bool default_also=false, bool write_description=false) const
CLI11_NODISCARD std::string | help (std::string prev="", AppFormatMode mode=AppFormatMode::Normal) const
CLI11_NODISCARD 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< typename std::remove_reference< T >::type >::value||std::is_rvalue_reference< T && >::value) &&std::is_constructible< std::string, typename std::remove_reference< T >::type >::value, detail::enabler > = detail::dummy>
Option * | add_flag (std::string flag_name, T &&flag_description)
template<typename T, enable_if_t<!detail::is_mutable_container< T >::value &&!std::is_const< 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

## NameMatch

enum class CLI::App::NameMatch : std::uint8_t

strong

enumeration of matching possibilities

Enumerator
none |
exact |
prefix |

## startup_mode

enum class CLI::App::startup_mode : std::uint8_t

strong protected

Enumerator
stable |
enabled |
disabled |

## Constructor & Destructor Documentation

## App() [1/3]

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

protected

Special private constructor for subcommand.

## App() [2/3]

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

inline explicit

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 | ( |  | ) |

virtual default

virtual destructor

## Member Function Documentation

## _add_flag_like_result()

bool CLI::App::_add_flag_like_result | ( | Option * | op,
|  | const ConfigItem & | item,
|  | const std::vector< std::string > & | inputs )

protected

store the results for a flag like option

## _compare_subcommand_names()

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

protected

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

## _configure()

void CLI::App::_configure | ( |  | ) |

protected

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()

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

protected

Count the required remaining positional arguments.

## _find_subcommand()

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

protected noexcept

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

## _get_fallthrough_parent()

App * CLI::App::_get_fallthrough_parent | ( |  | ) |

protected

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

## _has_remaining_positionals()

CLI11_NODISCARD bool CLI::App::_has_remaining_positionals | ( |  | ) | const

protected

Count the required remaining positional arguments.

## _move_option()

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

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

## _move_to_missing()

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

protected

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

## _parse() [1/2]

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

protected

Internal parse function.

## _parse() [2/2]

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

protected

Internal parse function.

## _parse_arg()

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

protected

Parse a short (false) or long (true) argument, must be at the top of the list if local_processing_only is set to true then fallthrough is disabled will return false if not found return true if the argument was processed or false if nothing was done

## _parse_config()

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

protected

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 )

protected

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

## _parse_single()

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

protected

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 )

protected

Fill in a single config option.

## _parse_stream()

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

protected

Internal function to parse a stream.

## _parse_subcommand()

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

protected

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

## _process()

void CLI::App::_process | ( |  | ) |

protected

Process callbacks and such.

## _process_callbacks()

void CLI::App::_process_callbacks | ( | CallbackPriority | priority | ) |

protected

Process callbacks. Runs on all subcommands.

## _process_config_file() [1/2]

void CLI::App::_process_config_file | ( |  | ) |

protected

Read and process a configuration file (main app only).

## _process_config_file() [2/2]

bool CLI::App::_process_config_file | ( | const std::string & | config_file,
|  | bool | throw_error )

protected

Read and process a particular configuration file.

## _process_env()

void CLI::App::_process_env | ( |  | ) |

protected

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

## _process_extras() [1/2]

void CLI::App::_process_extras | ( |  | ) |

protected

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 | ) |

protected

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 | ( | CallbackPriority | priority,
|  | bool | trigger_help = false,
|  | bool | trigger_all_help = false ) const

protected

Run help flag processing if any are found.

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

## _process_requirements()

void CLI::App::_process_requirements | ( |  | ) |

protected

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

## _recognize()

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

protected

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 | ) |

protected

Trigger the pre_parse callback if needed.

## _valid_subcommand()

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

protected

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

## _validate()

void CLI::App::_validate | ( |  | ) | const

protected

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

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

inline

Add a flag with no description or variable assignment.

## add_flag() [2/4]

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

template<typename T, enable_if_t<(std::is_const< typename std::remove_reference< T >::type >::value||std::is_rvalue_reference< T && >::value) &&std::is_constructible< std::string, typename std::remove_reference< T >::type >::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 or a rvalue reference to a string, if a variable string is passed that variable will be assigned the results from the flag

## add_flag() [4/4]

template<typename T, enable_if_t<!detail::is_mutable_container< T >::value &&!std::is_const< 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 the flag result

## add_flag_callback()

Option * CLI::App::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.

Parameters

  function | A function to call, void(void)

## add_flag_function()

Option * CLI::App::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.

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

## 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 = {} )

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");

## 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

## 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

## add_subcommand() [1/2]

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

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 = "" )

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

## alias()

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

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_non_standard_option_names()

App * CLI::App::allow_non_standard_option_names | ( | bool | allowed = true | ) |

inline

allow non standard option names

## allow_subcommand_prefix_matching()

App * CLI::App::allow_subcommand_prefix_matching | ( | bool | allowed = true | ) |

inline

allow prefix matching for subcommands

## 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()

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

Check the name, case-insensitive and underscore insensitive, and prefix matching if set

Returns
  true if matched

## check_name_detail()

CLI11_NODISCARD NameMatch CLI::App::check_name_detail | ( | std::string | name_to_check | ) | const

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

Returns
  NameMatch::none if no match, NameMatch::exact if the match is exact NameMatch::prefix if prefix is enabled and a prefix matches

## clear()

void CLI::App::clear | ( |  | ) |

Reset the parsed data.

## clear_aliases()

App * CLI::App::clear_aliases | ( |  | ) |

inline

clear all the aliases of the current App

## config_formatter()

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

inline

Set the config formatter.

## config_to_str()

CLI11_NODISCARD 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]

CLI11_NODISCARD 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]

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

inline

Counts the number of times the given option was passed.

## count_all()

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

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

## 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.

## 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.

## 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)

## ensure_utf8()

CLI11_NODISCARD char ** CLI::App::ensure_utf8 | ( | char ** | argv | ) |

Convert the contents of argv to UTF-8. Only does something on Windows, does nothing elsewhere.

## 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

Print a nice error message and return the exit code.

## 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

Set fallthrough, set to true so that options will fallthrough to parent if not recognized in a 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()

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

inline

Get the aliases of the current app.

## get_allow_config_extras()

CLI11_NODISCARD config_extras_mode CLI::App::get_allow_config_extras | ( |  | ) | const

inline

Get the status of allow extras.

## get_allow_extras()

CLI11_NODISCARD bool CLI::App::get_allow_extras | ( |  | ) | const

inline

Get the status of allow extras.

## get_allow_non_standard_option_names()

CLI11_NODISCARD bool CLI::App::get_allow_non_standard_option_names | ( |  | ) | const

inline

Get the status of allowing non standard option names.

## get_allow_subcommand_prefix_matching()

CLI11_NODISCARD bool CLI::App::get_allow_subcommand_prefix_matching | ( |  | ) | const

inline

Get the status of allowing prefix matching for subcommands.

## get_allow_windows_style_options()

CLI11_NODISCARD bool CLI::App::get_allow_windows_style_options | ( |  | ) | const

inline

Check the status of the allow windows style options.

## get_config_formatter()

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

inline

Access the config formatter.

## get_config_formatter_base()

CLI11_NODISCARD 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]

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

inline

Get a pointer to the config option. (const).

## get_configurable()

CLI11_NODISCARD bool CLI::App::get_configurable | ( |  | ) | const

inline

Check the status of the allow windows style options.

## get_description()

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

inline

Get the app or subcommand description.

## get_disabled()

CLI11_NODISCARD bool CLI::App::get_disabled | ( |  | ) | const

inline

Get the status of disabled.

## get_disabled_by_default()

CLI11_NODISCARD bool CLI::App::get_disabled_by_default | ( |  | ) | const

inline

Get the status of disabled by default.

## get_display_name()

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

Get a display name for an app.

## get_enabled_by_default()

CLI11_NODISCARD bool CLI::App::get_enabled_by_default | ( |  | ) | const

inline

Get the status of disabled by default.

## get_fallthrough()

CLI11_NODISCARD bool CLI::App::get_fallthrough | ( |  | ) | const

inline

Check the status of fallthrough.

## get_footer()

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

inline

Generate and return the footer.

## get_formatter()

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

inline

Access the formatter.

## get_group()

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

inline

Get the group of this subcommand.

## get_groups()

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

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

## get_help_all_ptr()

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

inline

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

## get_help_ptr() [1/2]

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

inline

Get a pointer to the help flag.

## get_help_ptr() [2/2]

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

inline

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

## get_ignore_case()

CLI11_NODISCARD bool CLI::App::get_ignore_case | ( |  | ) | const

inline

Check the status of ignore_case.

## get_ignore_underscore()

CLI11_NODISCARD bool CLI::App::get_ignore_underscore | ( |  | ) | const

inline

Check the status of ignore_underscore.

## get_immediate_callback()

CLI11_NODISCARD bool CLI::App::get_immediate_callback | ( |  | ) | const

inline

Get the status of disabled.

## get_name()

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

inline

Get the name of the current app.

## 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]

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

inline

Get an option by name.

## get_option_group()

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

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

## get_option_no_throw() [1/2]

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

noexcept

Get an option by name (noexcept const version).

## get_option_no_throw() [2/2]

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

noexcept

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

## get_options() [1/2]

std::vector< const Option * > CLI::App::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.

## get_options() [2/2]

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

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).

## get_parent() [2/2]

CLI11_NODISCARD 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()

CLI11_NODISCARD bool CLI::App::get_positionals_at_end | ( |  | ) | const

inline

Check the status of the allow windows style options.

## get_prefix_command()

CLI11_NODISCARD bool CLI::App::get_prefix_command | ( |  | ) | const

inline

Get the prefix command status.

## get_require_option_max()

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

inline

Get the required max option value.

## get_require_option_min()

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

inline

Get the required min option value.

## get_require_subcommand_max()

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

inline

Get the required max subcommand value.

## get_require_subcommand_min()

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

inline

Get the required min subcommand value.

## get_required()

CLI11_NODISCARD bool CLI::App::get_required | ( |  | ) | const

inline

Get the status of required.

## get_silent()

CLI11_NODISCARD 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

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

## get_subcommand() [2/3]

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

Get a pointer to subcommand by index.

## get_subcommand() [3/3]

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

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

## get_subcommand_fallthrough()

CLI11_NODISCARD bool CLI::App::get_subcommand_fallthrough | ( |  | ) | const

inline

Check the status of subcommand fallthrough.

## get_subcommand_no_throw()

CLI11_NODISCARD App * CLI::App::get_subcommand_no_throw | ( | std::string | subcom | ) | const

noexcept

Get a subcommand by name (noexcept non-const version) returns null if subcommand doesn't exist

## get_subcommand_ptr() [1/3]

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

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

## get_subcommand_ptr() [2/3]

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

Get an owning pointer to subcommand by index.

## get_subcommand_ptr() [3/3]

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

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

## get_subcommands() [1/3]

CLI11_NODISCARD 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.)

## get_subcommands() [2/3]

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

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

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

## get_usage()

CLI11_NODISCARD std::string CLI::App::get_usage | ( |  | ) | const

inline

Generate and return the usage.

## get_validate_optional_arguments()

CLI11_NODISCARD bool CLI::App::get_validate_optional_arguments | ( |  | ) | const

inline

Get the status of validating optional vector arguments.

## get_validate_positionals()

CLI11_NODISCARD 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]

CLI11_NODISCARD 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.

## got_subcommand() [2/2]

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

inline noexcept

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()

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

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

## ignore_case()

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

Ignore case. Subcommands inherit value.

## ignore_underscore()

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

Ignore underscore. Subcommands inherit value.

## immediate_callback()

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

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

## increment_parsed()

void CLI::App::increment_parsed | ( |  | ) |

protected

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 = "" | ) |

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

inline explicit

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

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

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

## parse() [2/6]

void CLI::App::parse | ( | int | argc,
|  | const wchar_t *const * | argv )

## parse() [3/6]

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

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

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

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

## parse() [5/6]

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

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

## parse() [6/6]

void CLI::App::parse | ( | std::wstring | commandline,
|  | bool | program_name_included = false )

## 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 | ) |

## parse_order()

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

inline

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

## parsed()

CLI11_NODISCARD 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 | ( |  | ) |

inline virtual

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 | is_prefix = true | ) |

inline

Do not parse anything after the first unrecognized option (if true) all remaining arguments are stored in remaining args

## preparse_callback()

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

inline

Set a callback to execute prior to parsing.

## remaining()

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

This returns the missing options from the current subcommand.

## remaining_for_passthrough()

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

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

## remaining_size()

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

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

## remove_excludes() [1/2]

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

Removes a subcommand from the excludes list of this subcommand.

## remove_excludes() [2/2]

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

Removes an option from the excludes list of this subcommand.

## remove_needs() [1/2]

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

Removes a subcommand from the needs list of this subcommand.

## remove_needs() [2/2]

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

Removes an option from the needs list of this subcommand.

## remove_option()

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

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

## remove_subcommand()

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

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 )

protected

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 )

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 = "" )

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 = "" )

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" )

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" )

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

## subcommand_fallthrough()

App * CLI::App::subcommand_fallthrough | ( | bool | value = true | ) |

inline

Set subcommand fallthrough, set to true so that subcommands on parents are recognized.

## usage() [1/2]

App * CLI::App::usage | ( | std::function< std::string()> | usage_function | ) |

inline

Set usage.

## usage() [2/2]

App * CLI::App::usage | ( | std::string | usage_string | ) |

inline

Set usage.

## validate_optional_arguments()

App * CLI::App::validate_optional_arguments | ( | bool | validate = true | ) |

inline

Set the subcommand to validate optional vector arguments before assigning.

## validate_positionals()

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

inline

Set the subcommand to validate positional arguments before assigning.

## version()

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

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_non_standard_options_

bool CLI::App::allow_non_standard_options_ {false}

protected

indicator that the subcommand should allow non-standard option arguments, such as -single_dash_flag

## allow_prefix_matching_

bool CLI::App::allow_prefix_matching_ {false}

protected

indicator to allow subcommands to match with prefix matching

## 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 options or other arguments to fallthrough, so that parent commands can collect options 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, cease processing 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

## subcommand_fallthrough_

bool CLI::App::subcommand_fallthrough_ {true}

protected

Allow subcommands to fallthrough, so that parent commands can trigger other subcommands after subcommand.

## subcommands_

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

protected

Storage for subcommand list.

## usage_

std::string CLI::App::usage_ {}

protected

Usage to put after program/subcommand description in the help output INHERITABLE.

## usage_callback_

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

protected

This is a function that generates a usage to put after program/subcommand description in help output.

## validate_optional_arguments_

bool CLI::App::validate_optional_arguments_ {false}

protected

If set to true optional vector arguments are validated before assigning INHERITABLE.

## 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:

- include/CLI/App.hpp