Scarab  v3.4.1
Project 8 C++ Utility Library
Public Member Functions | Protected Member Functions | Private Attributes | List of all members
App Class Reference

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

#include <CLI11.hpp>

Inheritance diagram for App:
Inheritance graph

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 More...
 
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. More...
 
virtual ~App ()=default
 virtual destructor More...
 
Appcallback (std::function< void()> app_callback)
 
Apppreparse_callback (std::function< void(size_t)> pp_callback)
 
Appname (std::string app_name="")
 Set a name for the app (empty will use parser to set the name) More...
 
Appallow_extras (bool allow=true)
 Remove the error when extras are left over on the command line. More...
 
Apprequired (bool require=true)
 Remove the error when extras are left over on the command line. More...
 
Appdisabled (bool disable=true)
 Disable the subcommand or option group. More...
 
Appdisabled_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. More...
 
Appenabled_by_default (bool enable=true)
 
Appimmediate_callback (bool immediate=true)
 Set the subcommand callback to be executed immediately on subcommand completion. More...
 
Appvalidate_positionals (bool validate=true)
 Set the subcommand to validate positional arguments before assigning. More...
 
Appallow_config_extras (bool allow=true)
 
Appprefix_command (bool allow=true)
 Do not parse anything after the first unrecognized option and return. More...
 
Appignore_case (bool value=true)
 Ignore case. Subcommands inherit value. More...
 
Appallow_windows_style_options (bool value=true)
 Allow windows style options, such as /opt. First matching short or long name used. Subcommands inherit value. More...
 
Apppositionals_at_end (bool value=true)
 Specify that the positional arguments are only at the end of the sequence. More...
 
Appignore_underscore (bool value=true)
 Ignore underscore. Subcommands inherit value. More...
 
Appformatter (std::shared_ptr< FormatterBase > fmt)
 Set the help formatter. More...
 
Appformatter_fn (std::function< std::string(const App *, std::string, AppFormatMode)> fmt)
 Set the help formatter. More...
 
Appconfig_formatter (std::shared_ptr< Config > fmt)
 Set the config formatter. More...
 
bool parsed () const
 Check to see if this subcommand was parsed, true only if received on command line. More...
 
OptionDefaultsoption_defaults ()
 Get the OptionDefault object, to set option defaults. More...
 
Subcommmands
Appadd_subcommand (std::string subcommand_name="", std::string subcommand_description="")
 Add a subcommand. Inherits INHERITABLE and OptionDefaults, and help flag. More...
 
Appadd_subcommand (CLI::App_p subcom)
 Add a previously created app as a subcommand. More...
 
bool remove_subcommand (App *subcom)
 Removes a subcommand from the App. Takes a subcommand pointer. Returns true if found and removed. More...
 
Appget_subcommand (App *subcom) const
 
Appget_subcommand (std::string subcom) const
 Check to see if a subcommand is part of this command (text version) More...
 
Appget_subcommand (int index=0) const
 Get a pointer to subcommand by index. More...
 
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. More...
 
CLI::App_p get_subcommand_ptr (std::string subcom) const
 Check to see if a subcommand is part of this command (text version) More...
 
CLI::App_p get_subcommand_ptr (int index=0) const
 Get an owning pointer to subcommand by index. More...
 
Appget_option_group (std::string group_name) const
 Check to see if an option group is part of this App. More...
 
size_t count () const
 
size_t count_all () const
 
Appgroup (std::string group_name)
 Changes the group membership. More...
 
Apprequire_subcommand ()
 The argumentless form of require subcommand requires 1 or more subcommands. More...
 
Apprequire_subcommand (int value)
 
Apprequire_subcommand (size_t min, size_t max)
 
Apprequire_option ()
 The argumentless form of require option requires 1 or more options be used. More...
 
Apprequire_option (int value)
 
Apprequire_option (size_t min, size_t max)
 
Appfallthrough (bool value=true)
 
 operator bool () const
 
Extras for subclassing
virtual void pre_callback ()
 
Post parsing
size_t count (std::string option_name) const
 Counts the number of times the given option was passed. More...
 
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 (App *subcom) const
 Check to see if given subcommand was selected. More...
 
bool got_subcommand (std::string subcommand_name) const
 Check with name instead of pointer to see if subcommand was selected. More...
 
Appexcludes (Option *opt)
 Sets excluded options for the subcommand. More...
 
Appexcludes (App *app)
 Sets excluded subcommands for the subcommand. More...
 
bool remove_excludes (Option *opt)
 Removes an option from the excludes list of this subcommand. More...
 
bool remove_excludes (App *app)
 Removes a subcommand from this excludes list of this subcommand. More...
 
Getters
std::shared_ptr< FormatterBaseget_formatter () const
 Access the formatter. More...
 
std::shared_ptr< Configget_config_formatter () const
 Access the config formatter. More...
 
std::string get_description () const
 Get the app or subcommand description. More...
 
Appdescription (std::string app_description)
 Set the description of the app. More...
 
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. More...
 
Optionget_option_no_throw (std::string option_name) noexcept
 Get an option by name (noexcept non-const version) More...
 
const Optionget_option_no_throw (std::string option_name) const noexcept
 Get an option by name (noexcept const version) More...
 
const Optionget_option (std::string option_name) const
 Get an option by name. More...
 
Optionget_option (std::string option_name)
 Get an option by name (non-const version) More...
 
const Optionoperator[] (const std::string &option_name) const
 Shortcut bracket operator for getting a pointer to an option. More...
 
const Optionoperator[] (const char *option_name) const
 Shortcut bracket operator for getting a pointer to an option. More...
 
bool get_ignore_case () const
 Check the status of ignore_case. More...
 
bool get_ignore_underscore () const
 Check the status of ignore_underscore. More...
 
bool get_fallthrough () const
 Check the status of fallthrough. More...
 
bool get_allow_windows_style_options () const
 Check the status of the allow windows style options. More...
 
bool get_positionals_at_end () const
 Check the status of the allow windows style options. More...
 
const std::string & get_group () const
 Get the group of this subcommand. More...
 
const std::string & get_footer () const
 Get footer. More...
 
size_t get_require_subcommand_min () const
 Get the required min subcommand value. More...
 
size_t get_require_subcommand_max () const
 Get the required max subcommand value. More...
 
size_t get_require_option_min () const
 Get the required min option value. More...
 
size_t get_require_option_max () const
 Get the required max option value. More...
 
bool get_prefix_command () const
 Get the prefix command status. More...
 
bool get_allow_extras () const
 Get the status of allow extras. More...
 
bool get_required () const
 Get the status of required. More...
 
bool get_disabled () const
 Get the status of disabled. More...
 
bool get_immediate_callback () const
 Get the status of disabled. More...
 
bool get_disabled_by_default () const
 Get the status of disabled by default. More...
 
bool get_enabled_by_default () const
 Get the status of disabled by default. More...
 
bool get_validate_positionals () const
 Get the status of validating positionals. More...
 
bool get_allow_config_extras () const
 Get the status of allow extras. More...
 
Optionget_help_ptr ()
 Get a pointer to the help flag. More...
 
const Optionget_help_ptr () const
 Get a pointer to the help flag. (const) More...
 
const Optionget_help_all_ptr () const
 Get a pointer to the help all flag. (const) More...
 
Optionget_config_ptr ()
 Get a pointer to the config option. More...
 
const Optionget_config_ptr () const
 Get a pointer to the config option. (const) More...
 
Appget_parent ()
 Get the parent of this subcommand (or nullptr if master app) More...
 
const Appget_parent () const
 Get the parent of this subcommand (or nullptr if master app) (const version) More...
 
std::string get_name () const
 Get the name of the current app. More...
 
std::string get_display_name () const
 Get a display name for an app. More...
 
bool check_name (std::string name_to_check) const
 Check the name, case insensitive and underscore insensitive if set. More...
 
std::vector< std::string > get_groups () const
 Get the groups available directly from this option (in order) More...
 
const std::vector< Option * > & parse_order () const
 This gets a vector of pointers with the original parse order. More...
 
std::vector< std::string > remaining (bool recurse=false) const
 This returns the missing options from the current subcommand. More...
 
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. More...
 
size_t remaining_size (bool recurse=false) const
 This returns the number of remaining options, minus the – separator. More...
 

Protected Member Functions

 App (std::string app_description, std::string app_name, App *parent)
 Special private constructor for subcommand. More...
 
void _validate () const
 
void _configure ()
 
void run_callback ()
 Internal function to run (App) callback, bottom up. More...
 
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. More...
 
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. More...
 
void _process_ini ()
 Read and process an ini file (main app only) More...
 
void _process_env ()
 Get envname options if not yet passed. Runs on all subcommands. More...
 
void _process_callbacks ()
 Process callbacks. Runs on all subcommands. More...
 
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). More...
 
void _process ()
 Process callbacks and such. More...
 
void _process_extras ()
 Throw an error if anything is left over and should not be. More...
 
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. More...
 
void _parse (std::vector< std::string > &args)
 Internal parse function. More...
 
void _parse (std::vector< std::string > &&args)
 Internal parse function. More...
 
void _parse_config (std::vector< ConfigItem > &args)
 
bool _parse_single_config (const ConfigItem &item, size_t level=0)
 Fill in a single config option. More...
 
bool _parse_single (std::vector< std::string > &args, bool &positional_only)
 
size_t _count_remaining_positionals (bool required_only=false) const
 Count the required remaining positional arguments. More...
 
bool _has_remaining_positionals () const
 Count the required remaining positional arguments. More...
 
bool _parse_positional (std::vector< std::string > &args)
 
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 (size_t remaining_args)
 Trigger the pre_parse callback if needed. More...
 
App_get_fallthrough_parent ()
 Get the appropriate parent to fallthrough to which is the first one that has a name or the main app. More...
 
void _move_to_missing (detail::Classifier val_type, const std::string &val)
 Helper function to place extra values in the most appropriate position. More...
 

Protected Attributes

Basics
std::string name_
 Subcommand name or program name (from parser if name is empty) More...
 
std::string description_
 Description of the current program/subcommand. More...
 
bool allow_extras_ {false}
 If true, allow extra arguments (ie, don't throw an error). INHERITABLE. More...
 
bool allow_config_extras_ {false}
 If true, allow extra arguments in the ini file (ie, don't throw an error). INHERITABLE. More...
 
bool prefix_command_ {false}
 If true, return immediately on an unrecognized option (implies allow_extras) INHERITABLE. More...
 
bool has_automatic_name_ {false}
 If set to true the name was automatically generated from the command line vs a user set name. More...
 
bool required_ {false}
 If set to true the subcommand is required to be processed and used, ignored for main app. More...
 
bool disabled_ {false}
 If set to true the subcommand is disabled and cannot be used, ignored for main app. More...
 
bool pre_parse_called_ {false}
 Flag indicating that the pre_parse_callback has been triggered. More...
 
bool immediate_callback_ {false}
 
std::function< void(size_t)> pre_parse_callback_
 This is a function that runs prior to the start of parsing. More...
 
std::function< void()> callback_
 This is a function that runs when complete. Great for subcommands. Can throw. More...
 
Options
OptionDefaults option_defaults_
 The default values for options, customizable and changeable INHERITABLE. More...
 
std::vector< Option_poptions_
 The list of options, stored locally. More...
 
Subcommands
std::vector< App_psubcommands_
 Storage for subcommand list. More...
 
bool ignore_case_ {false}
 If true, the program name is not case sensitive INHERITABLE. More...
 
bool ignore_underscore_ {false}
 If true, the program should ignore underscores INHERITABLE. More...
 
bool fallthrough_ {false}
 Allow subcommand fallthrough, so that parent commands can collect commands after subcommand. INHERITABLE. More...
 
bool allow_windows_style_options_
 Allow '/' for options for Windows like options. Defaults to true on Windows, false otherwise. INHERITABLE. More...
 
bool positionals_at_end_ {false}
 specify that positional arguments come at the end of the argument sequence not inheritable More...
 
bool disabled_by_default_ {false}
 If set to true the subcommand will start each parse disabled. More...
 
bool enabled_by_default_ {false}
 If set to true the subcommand will be reenabled at the start of each parse. More...
 
bool validate_positionals_ {false}
 If set to true positional options are validated before assigning INHERITABLE. More...
 
Appparent_ {nullptr}
 A pointer to the parent if this is a subcommand. More...
 
size_t parsed_ = 0
 Counts the number of times this command/subcommand was parsed. More...
 
size_t require_subcommand_min_ = 0
 Minimum required subcommands (not inheritable!) More...
 
size_t require_subcommand_max_ = 0
 Max number of subcommands allowed (parsing stops after this number). 0 is unlimited INHERITABLE. More...
 
size_t require_option_min_ = 0
 Minimum required options (not inheritable!) More...
 
size_t require_option_max_ = 0
 Max number of options allowed. 0 is unlimited (not inheritable) More...
 
std::string group_ {"Subcommands"}
 The group membership INHERITABLE. More...
 
Config
std::string config_name_
 The name of the connected config file. More...
 
bool config_required_ {false}
 True if ini is required (throws if not present), if false simply keep going. More...
 
Optionconfig_ptr_ {nullptr}
 Pointer to the config option. More...
 
std::shared_ptr< Configconfig_formatter_ {new ConfigINI()}
 This is the formatter for help printing. Default provided. INHERITABLE (same pointer) More...
 

Private Attributes

friend Option
 

Help

std::string footer_
 Footer to put after all options in the help output INHERITABLE. More...
 
Optionhelp_ptr_ {nullptr}
 A pointer to the help flag if there is one INHERITABLE. More...
 
Optionhelp_all_ptr_ {nullptr}
 A pointer to the help all flag if there is one INHERITABLE. More...
 
std::shared_ptr< FormatterBaseformatter_ {new Formatter()}
 This is the formatter for help printing. Default provided. INHERITABLE (same pointer) More...
 
std::function< std::string(const App *, const Error &e)> failure_message_ = FailureMessage::simple
 The error message printing function INHERITABLE. More...
 
Appfooter (std::string footer_string)
 Set footer. More...
 
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
 

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. More...
 
std::vector< App * > parsed_subcommands_
 This is a list of the subcommands collected, in order. More...
 
std::set< App * > exclude_subcommands_
 this is a list of subcommands that are exclusionary to this one More...
 
std::set< Option * > exclude_options_
 
void clear ()
 Reset the parsed data. More...
 
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. More...
 
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. More...
 
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. More...
 

Adding options

Optionadd_option (std::string option_name, callback_t option_callback, std::string option_description="", bool defaulted=false, std::function< std::string()> func={})
 
template<typename T , enable_if_t<!is_vector< T >::value &!std::is_const< T >::value, detail::enabler > = detail::dummy>
Optionadd_option (std::string option_name, T &variable, std::string option_description="", bool defaulted=false)
 Add option for non-vectors (duplicate copy needed without defaulted to avoid iostream << value) More...
 
template<typename T , enable_if_t<!is_vector< T >::value, detail::enabler > = detail::dummy>
Optionadd_option_function (std::string option_name, const std::function< void(const T &)> &func, std::string option_description="")
 Add option for a callback of a specific type. More...
 
Optionadd_option (std::string option_name)
 Add option with no description or variable assignment. More...
 
template<typename T , enable_if_t< std::is_const< T >::value &&std::is_constructible< std::string, T >::value, detail::enabler > = detail::dummy>
Optionadd_option (std::string option_name, T &option_description)
 Add option with description but with no variable assignment or callback. More...
 
template<typename T >
Optionadd_option (std::string option_name, std::vector< T > &variable, std::string option_description="", bool defaulted=false)
 Add option for vectors. More...
 
template<typename T , enable_if_t< is_vector< T >::value, detail::enabler > = detail::dummy>
Optionadd_option_function (std::string option_name, const std::function< void(const T &)> &func, std::string option_description="")
 Add option for a vector callback of a specific type. More...
 
Optionset_help_flag (std::string flag_name="", const std::string &help_description="")
 Set a help flag, replace the existing one if present. More...
 
Optionset_help_all_flag (std::string help_name="", const std::string &help_description="")
 Set a help all flag, replaced the existing one if present. More...
 
Optionadd_flag (std::string flag_name)
 Add a flag with no description or variable assignment. More...
 
template<typename T , enable_if_t< std::is_const< T >::value &&std::is_constructible< std::string, T >::value, detail::enabler > = detail::dummy>
Optionadd_flag (std::string flag_name, T &flag_description)
 
template<typename T , enable_if_t< std::is_integral< T >::value &&!is_bool< T >::value, detail::enabler > = detail::dummy>
Optionadd_flag (std::string flag_name, T &flag_count, std::string flag_description="")
 
template<typename T , enable_if_t<!is_vector< T >::value &&!std::is_const< T >::value &&(!std::is_integral< T >::value||is_bool< T >::value) &&!std::is_constructible< std::function< void(int)>, T >::value, detail::enabler > = detail::dummy>
Optionadd_flag (std::string flag_name, T &flag_result, std::string flag_description="")
 
template<typename T , enable_if_t<!std::is_assignable< std::function< void(int64_t)>, T >::value, detail::enabler > = detail::dummy>
Optionadd_flag (std::string flag_name, std::vector< T > &flag_results, std::string flag_description="")
 Vector version to capture multiple flags. More...
 
Optionadd_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. More...
 
Optionadd_flag_function (std::string flag_name, std::function< void(int64_t)> function, std::string flag_description="")
 Add option for callback with an integer value. More...
 
template<typename T >
Optionadd_set (std::string option_name, T &member, std::set< T > options, std::string option_description="")
 Add set of options (No default, temp reference, such as an inline set) DEPRECATED. More...
 
template<typename T >
Optionadd_mutable_set (std::string option_name, T &member, const std::set< T > &options, std::string option_description="")
 Add set of options (No default, set can be changed afterwards - do not destroy the set) DEPRECATED. More...
 
template<typename T >
Optionadd_set (std::string option_name, T &member, std::set< T > options, std::string option_description, bool defaulted)
 Add set of options (with default, static set, such as an inline set) DEPRECATED. More...
 
template<typename T >
Optionadd_mutable_set (std::string option_name, T &member, const std::set< T > &options, std::string option_description, bool defaulted)
 Add set of options (with default, set can be changed afterwards - do not destroy the set) DEPRECATED. More...
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case)) instead"))) Option *add_set_ignore_case(std
 Add set of options, string only, ignore case (no default, static set) DEPRECATED. More...
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case)) with a (shared) pointer instead"))) Option *add_mutable_set_ignore_case(std
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case)) instead"))) Option *add_set_ignore_case(std
 Add set of options, string only, ignore case (default, static set) DEPRECATED. More...
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(...)) with a (shared) pointer instead"))) Option *add_mutable_set_ignore_case(std
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) instead"))) Option *add_set_ignore_underscore(std
 Add set of options, string only, ignore underscore (no default, static set) DEPRECATED. More...
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) with a (shared) pointer instead"))) Option *add_mutable_set_ignore_underscore(std
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) instead"))) Option *add_set_ignore_underscore(std
 Add set of options, string only, ignore underscore (default, static set) DEPRECATED. More...
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) with a (shared) pointer instead"))) Option *add_mutable_set_ignore_underscore(std
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) instead"))) Option *add_set_ignore_case_underscore(std
 Add set of options, string only, ignore underscore and case (no default, static set) DEPRECATED. More...
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) with a (shared) pointer instead"))) Option *add_mutable_set_ignore_case_underscore(std
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) instead"))) Option *add_set_ignore_case_underscore(std
 Add set of options, string only, ignore underscore and case (default, static set) DEPRECATED. More...
 
 __attribute__ ((deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) with a (shared) pointer instead"))) Option *add_mutable_set_ignore_case_underscore(std
 
template<typename T >
Optionadd_complex (std::string option_name, T &variable, std::string option_description="", bool defaulted=false, std::string label="COMPLEX")
 Add a complex number. More...
 
Optionset_config (std::string option_name="", std::string default_filename="", 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. More...
 
bool remove_option (Option *opt)
 Removes an option from the App. Takes an option pointer. Returns true if found and removed. More...
 
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 More...
 
Option_add_flag_internal (std::string flag_name, CLI::callback_t fun, std::string flag_description)
 Internal function for adding a flag. More...
 

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.

Definition at line 3696 of file CLI11.hpp.

Member Typedef Documentation

◆ missing_t

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

Definition at line 3776 of file CLI11.hpp.

Constructor & Destructor Documentation

◆ App() [1/2]

App ( std::string  app_description,
std::string  app_name,
App parent 
)
inlineprotected

Special private constructor for subcommand.

OptionDefaults

Definition at line 3869 of file CLI11.hpp.

◆ App() [2/2]

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.

Definition at line 3906 of file CLI11.hpp.

◆ ~App()

virtual ~App ( )
virtualdefault

virtual destructor

Member Function Documentation

◆ __attribute__() [1/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case)) instead"))  )
inline

Add set of options, string only, ignore case (no default, static set) DEPRECATED.

Definition at line 4443 of file CLI11.hpp.

◆ __attribute__() [2/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case)) with a (shared) pointer instead"))  )
inline

Add set of options, string only, ignore case (no default, set can be changed afterwards - do not destroy the set) DEPRECATED

Definition at line 4456 of file CLI11.hpp.

◆ __attribute__() [3/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case)) instead"))  )
inline

Add set of options, string only, ignore case (default, static set) DEPRECATED.

Definition at line 4468 of file CLI11.hpp.

◆ __attribute__() [4/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(...)) with a (shared) pointer instead"))  )
inline

Add set of options, string only, ignore case (default, set can be changed afterwards - do not destroy the set) DEPRECATED

Definition at line 4482 of file CLI11.hpp.

◆ __attribute__() [5/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) instead"))  )
inline

Add set of options, string only, ignore underscore (no default, static set) DEPRECATED.

Definition at line 4495 of file CLI11.hpp.

◆ __attribute__() [6/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) with a (shared) pointer instead"))  )
inline

Add set of options, string only, ignore underscore (no default, set can be changed afterwards - do not destroy the set) DEPRECATED

Definition at line 4508 of file CLI11.hpp.

◆ __attribute__() [7/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) instead"))  )
inline

Add set of options, string only, ignore underscore (default, static set) DEPRECATED.

Definition at line 4520 of file CLI11.hpp.

◆ __attribute__() [8/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_underscore)) with a (shared) pointer instead"))  )
inline

Add set of options, string only, ignore underscore (default, set can be changed afterwards - do not destroy the set) DEPRECATED

Definition at line 4534 of file CLI11.hpp.

◆ __attribute__() [9/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) instead"))  )
inline

Add set of options, string only, ignore underscore and case (no default, static set) DEPRECATED.

Definition at line 4547 of file CLI11.hpp.

◆ __attribute__() [10/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) with a (shared) pointer instead"))  )
inline

Add set of options, string only, ignore underscore and case (no default, set can be changed afterwards - do not destroy the set) DEPRECATED

Definition at line 4561 of file CLI11.hpp.

◆ __attribute__() [11/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) instead"))  )
inline

Add set of options, string only, ignore underscore and case (default, static set) DEPRECATED.

Definition at line 4573 of file CLI11.hpp.

◆ __attribute__() [12/12]

__attribute__ ( (deprecated("Use ->transform(CLI::IsMember(..., CLI::ignore_case, CLI::ignore_underscore)) with a (shared) pointer instead"))  )
inline

Add set of options, string only, ignore underscore and case (default, set can be changed afterwards - do not destroy the set) DEPRECATED

Definition at line 4588 of file CLI11.hpp.

◆ _add_flag_internal()

Option* _add_flag_internal ( std::string  flag_name,
CLI::callback_t  fun,
std::string  flag_description 
)
inlineprivate

Internal function for adding a flag.

Definition at line 4253 of file CLI11.hpp.

◆ _configure()

void _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

Definition at line 5469 of file CLI11.hpp.

◆ _count_remaining_positionals()

size_t _count_remaining_positionals ( bool  required_only = false) const
inlineprotected

Count the required remaining positional arguments.

Definition at line 5950 of file CLI11.hpp.

◆ _find_subcommand()

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

Definition at line 6045 of file CLI11.hpp.

◆ _get_fallthrough_parent()

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.

Definition at line 6252 of file CLI11.hpp.

◆ _has_remaining_positionals()

bool _has_remaining_positionals ( ) const
inlineprotected

Count the required remaining positional arguments.

Definition at line 5961 of file CLI11.hpp.

◆ _move_option()

void _move_option ( Option opt,
App app 
)
inline

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

Definition at line 6282 of file CLI11.hpp.

◆ _move_to_missing()

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

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

Definition at line 6264 of file CLI11.hpp.

◆ _parse() [1/2]

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

Internal parse function.

Definition at line 5808 of file CLI11.hpp.

◆ _parse() [2/2]

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

Internal parse function.

Definition at line 5837 of file CLI11.hpp.

◆ _parse_arg()

bool _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

Definition at line 6092 of file CLI11.hpp.

◆ _parse_config()

void _parse_config ( 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.

Definition at line 5857 of file CLI11.hpp.

◆ _parse_positional()

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

Parse a positional, go up the tree to check 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

Definition at line 5972 of file CLI11.hpp.

◆ _parse_single()

bool _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 master return false if the parse has failed and needs to return to parent

Definition at line 5906 of file CLI11.hpp.

◆ _parse_single_config()

bool _parse_single_config ( const ConfigItem item,
size_t  level = 0 
)
inlineprotected

Fill in a single config option.

Definition at line 5865 of file CLI11.hpp.

◆ _parse_subcommand()

bool _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

Definition at line 6066 of file CLI11.hpp.

◆ _process()

void _process ( )
inlineprotected

Process callbacks and such.

Definition at line 5759 of file CLI11.hpp.

◆ _process_callbacks()

void _process_callbacks ( )
inlineprotected

Process callbacks. Runs on all subcommands.

Definition at line 5600 of file CLI11.hpp.

◆ _process_env()

void _process_env ( )
inlineprotected

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

Definition at line 5567 of file CLI11.hpp.

◆ _process_extras() [1/2]

void _process_extras ( )
inlineprotected

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

Definition at line 5768 of file CLI11.hpp.

◆ _process_extras() [2/2]

void _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.

Definition at line 5784 of file CLI11.hpp.

◆ _process_help_flags()

void _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.

Definition at line 5628 of file CLI11.hpp.

◆ _process_ini()

void _process_ini ( )
inlineprotected

Read and process an ini file (main app only)

Definition at line 5547 of file CLI11.hpp.

◆ _process_requirements()

void _process_requirements ( )
inlineprotected

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

Definition at line 5651 of file CLI11.hpp.

◆ _recognize()

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

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

Definition at line 5526 of file CLI11.hpp.

◆ _trigger_pre_parse()

void _trigger_pre_parse ( size_t  remaining_args)
inlineprotected

Trigger the pre_parse callback if needed.

Definition at line 6233 of file CLI11.hpp.

◆ _valid_subcommand()

bool _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.

Definition at line 5512 of file CLI11.hpp.

◆ _validate()

void _validate ( ) const
inlineprotected

Check the options to make sure there are no conflicts.

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

Definition at line 5438 of file CLI11.hpp.

◆ add_complex()

Option* add_complex ( std::string  option_name,
T &  variable,
std::string  option_description = "",
bool  defaulted = false,
std::string  label = "COMPLEX" 
)
inline

Add a complex number.

Definition at line 4602 of file CLI11.hpp.

◆ add_flag() [1/5]

Option* add_flag ( std::string  flag_name)
inline

Add a flag with no description or variable assignment.

Definition at line 4279 of file CLI11.hpp.

◆ add_flag() [2/5]

Option* 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

Definition at line 4287 of file CLI11.hpp.

◆ add_flag() [3/5]

Option* 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_countA variable holding the count

Definition at line 4295 of file CLI11.hpp.

◆ add_flag() [4/5]

Option* 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_resultA variable holding true if passed

Definition at line 4317 of file CLI11.hpp.

◆ add_flag() [5/5]

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

Vector version to capture multiple flags.

Parameters
flag_resultsA vector of values with the flag results

Definition at line 4335 of file CLI11.hpp.

◆ add_flag_callback()

Option* 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
functionA function to call, void(void)

Definition at line 4350 of file CLI11.hpp.

◆ add_flag_function()

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

Add option for callback with an integer value.

Parameters
functionA function to call, void(int)

Definition at line 4370 of file CLI11.hpp.

◆ add_mutable_set() [1/2]

Option* add_mutable_set ( std::string  option_name,
T &  member,
const std::set< T > &  options,
std::string  option_description = "" 
)
inline

Add set of options (No default, set can be changed afterwards - do not destroy the set) DEPRECATED.

Parameters
memberThe selected member of the set
optionsThe set of possibilities

Definition at line 4406 of file CLI11.hpp.

◆ add_mutable_set() [2/2]

Option* add_mutable_set ( std::string  option_name,
T &  member,
const std::set< T > &  options,
std::string  option_description,
bool  defaulted 
)
inline

Add set of options (with default, set can be changed afterwards - do not destroy the set) DEPRECATED.

Parameters
memberThe selected member of the set
optionsThe set of possibilities

Definition at line 4431 of file CLI11.hpp.

◆ add_option() [1/5]

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

Definition at line 4074 of file CLI11.hpp.

◆ add_option() [2/5]

Option* add_option ( std::string  option_name,
T &  variable,
std::string  option_description = "",
bool  defaulted = false 
)
inline

Add option for non-vectors (duplicate copy needed without defaulted to avoid iostream << value)

Parameters
variableThe variable to set

Definition at line 4110 of file CLI11.hpp.

◆ add_option() [3/5]

Option* add_option ( std::string  option_name)
inline

Add option with no description or variable assignment.

Definition at line 4146 of file CLI11.hpp.

◆ add_option() [4/5]

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

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

Definition at line 4154 of file CLI11.hpp.

◆ add_option() [5/5]

Option* add_option ( std::string  option_name,
std::vector< T > &  variable,
std::string  option_description = "",
bool  defaulted = false 
)
inline

Add option for vectors.

Parameters
variableThe variable vector to set

Definition at line 4160 of file CLI11.hpp.

◆ add_option_function() [1/2]

Option* add_option_function ( std::string  option_name,
const std::function< void(const T &)> &  func,
std::string  option_description = "" 
)
inline

Add option for a callback of a specific type.

Parameters
functhe callback to execute

Definition at line 4127 of file CLI11.hpp.

◆ add_option_function() [2/2]

Option* add_option_function ( std::string  option_name,
const std::function< void(const T &)> &  func,
std::string  option_description = "" 
)
inline

Add option for a vector callback of a specific type.

Parameters
functhe callback to execute

Definition at line 4194 of file CLI11.hpp.

◆ add_option_group()

T* add_option_group ( std::string  group_name,
std::string  group_description = "" 
)
inline

creates an option group as part of the given app

Definition at line 4677 of file CLI11.hpp.

◆ add_set() [1/2]

Option* add_set ( std::string  option_name,
T &  member,
std::set< T >  options,
std::string  option_description = "" 
)
inline

Add set of options (No default, temp reference, such as an inline set) DEPRECATED.

Parameters
memberThe selected member of the set
optionsThe set of possibilities

Definition at line 4394 of file CLI11.hpp.

◆ add_set() [2/2]

Option* add_set ( std::string  option_name,
T &  member,
std::set< T >  options,
std::string  option_description,
bool  defaulted 
)
inline

Add set of options (with default, static set, such as an inline set) DEPRECATED.

Parameters
memberThe selected member of the set
optionsThe set of possibilities

Definition at line 4418 of file CLI11.hpp.

◆ add_subcommand() [1/2]

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

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

Definition at line 4691 of file CLI11.hpp.

◆ add_subcommand() [2/2]

App* add_subcommand ( CLI::App_p  subcom)
inline

Add a previously created app as a subcommand.

Definition at line 4697 of file CLI11.hpp.

◆ allow_config_extras()

App* allow_config_extras ( bool  allow = true)
inline

Remove the error when extras are left over on the command line. Will also call App::allow_extras().

Definition at line 3984 of file CLI11.hpp.

◆ allow_extras()

App* allow_extras ( bool  allow = true)
inline

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

Definition at line 3940 of file CLI11.hpp.

◆ allow_windows_style_options()

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.

Definition at line 4009 of file CLI11.hpp.

◆ callback()

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

Set a callback for the end of parsing.

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.

Definition at line 3920 of file CLI11.hpp.

◆ check_name()

bool check_name ( std::string  name_to_check) const
inline

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

Definition at line 5351 of file CLI11.hpp.

◆ clear()

void clear ( )
inline

Reset the parsed data.

Definition at line 4901 of file CLI11.hpp.

◆ config_formatter()

App* config_formatter ( std::shared_ptr< Config fmt)
inline

Set the config formatter.

Definition at line 4045 of file CLI11.hpp.

◆ config_to_str()

std::string 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. Prefix will add a string to the beginning of each option.

Definition at line 5146 of file CLI11.hpp.

◆ count() [1/2]

size_t 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

Definition at line 4794 of file CLI11.hpp.

◆ count() [2/2]

size_t count ( std::string  option_name) const
inline

Counts the number of times the given option was passed.

Definition at line 5038 of file CLI11.hpp.

◆ count_all()

size_t count_all ( ) const
inline

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

Definition at line 4798 of file CLI11.hpp.

◆ description()

App* description ( std::string  app_description)
inline

Set the description of the app.

Definition at line 5180 of file CLI11.hpp.

◆ disabled()

App* disabled ( bool  disable = true)
inline

Disable the subcommand or option group.

Definition at line 3952 of file CLI11.hpp.

◆ disabled_by_default()

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.

Definition at line 3958 of file CLI11.hpp.

◆ enabled_by_default()

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)

Definition at line 3965 of file CLI11.hpp.

◆ excludes() [1/2]

App* excludes ( Option opt)
inline

Sets excluded options for the subcommand.

Definition at line 5089 of file CLI11.hpp.

◆ excludes() [2/2]

App* excludes ( App app)
inline

Sets excluded subcommands for the subcommand.

Definition at line 5098 of file CLI11.hpp.

◆ exit()

int 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

Definition at line 5009 of file CLI11.hpp.

◆ failure_message()

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

Definition at line 5004 of file CLI11.hpp.

◆ fallthrough()

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.

Definition at line 4878 of file CLI11.hpp.

◆ footer()

App* footer ( std::string  footer_string)
inline

Set footer.

Definition at line 5139 of file CLI11.hpp.

◆ formatter()

App* formatter ( std::shared_ptr< FormatterBase fmt)
inline

Set the help formatter.

Definition at line 4033 of file CLI11.hpp.

◆ formatter_fn()

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

Set the help formatter.

Definition at line 4039 of file CLI11.hpp.

◆ get_allow_config_extras()

bool get_allow_config_extras ( ) const
inline

Get the status of allow extras.

Definition at line 5321 of file CLI11.hpp.

◆ get_allow_extras()

bool get_allow_extras ( ) const
inline

Get the status of allow extras.

Definition at line 5301 of file CLI11.hpp.

◆ get_allow_windows_style_options()

bool get_allow_windows_style_options ( ) const
inline

Check the status of the allow windows style options.

Definition at line 5274 of file CLI11.hpp.

◆ get_config_formatter()

std::shared_ptr<Config> get_config_formatter ( ) const
inline

Access the config formatter.

Definition at line 5174 of file CLI11.hpp.

◆ get_config_ptr() [1/2]

Option* get_config_ptr ( )
inline

Get a pointer to the config option.

Definition at line 5333 of file CLI11.hpp.

◆ get_config_ptr() [2/2]

const Option* get_config_ptr ( ) const
inline

Get a pointer to the config option. (const)

Definition at line 5336 of file CLI11.hpp.

◆ get_description()

std::string get_description ( ) const
inline

Get the app or subcommand description.

Definition at line 5177 of file CLI11.hpp.

◆ get_disabled()

bool get_disabled ( ) const
inline

Get the status of disabled.

Definition at line 5307 of file CLI11.hpp.

◆ get_disabled_by_default()

bool get_disabled_by_default ( ) const
inline

Get the status of disabled by default.

Definition at line 5313 of file CLI11.hpp.

◆ get_display_name()

std::string get_display_name ( ) const
inline

Get a display name for an app.

Definition at line 5348 of file CLI11.hpp.

◆ get_enabled_by_default()

bool get_enabled_by_default ( ) const
inline

Get the status of disabled by default.

Definition at line 5316 of file CLI11.hpp.

◆ get_fallthrough()

bool get_fallthrough ( ) const
inline

Check the status of fallthrough.

Definition at line 5271 of file CLI11.hpp.

◆ get_footer()

const std::string& get_footer ( ) const
inline

Get footer.

Definition at line 5283 of file CLI11.hpp.

◆ get_formatter()

std::shared_ptr<FormatterBase> get_formatter ( ) const
inline

Access the formatter.

Definition at line 5171 of file CLI11.hpp.

◆ get_group()

const std::string& get_group ( ) const
inline

Get the group of this subcommand.

Definition at line 5280 of file CLI11.hpp.

◆ get_groups()

std::vector<std::string> get_groups ( ) const
inline

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

Definition at line 5366 of file CLI11.hpp.

◆ get_help_all_ptr()

const Option* get_help_all_ptr ( ) const
inline

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

Definition at line 5330 of file CLI11.hpp.

◆ get_help_ptr() [1/2]

Option* get_help_ptr ( )
inline

Get a pointer to the help flag.

Definition at line 5324 of file CLI11.hpp.

◆ get_help_ptr() [2/2]

const Option* get_help_ptr ( ) const
inline

Get a pointer to the help flag. (const)

Definition at line 5327 of file CLI11.hpp.

◆ get_ignore_case()

bool get_ignore_case ( ) const
inline

Check the status of ignore_case.

Definition at line 5265 of file CLI11.hpp.

◆ get_ignore_underscore()

bool get_ignore_underscore ( ) const
inline

Check the status of ignore_underscore.

Definition at line 5268 of file CLI11.hpp.

◆ get_immediate_callback()

bool get_immediate_callback ( ) const
inline

Get the status of disabled.

Definition at line 5310 of file CLI11.hpp.

◆ get_name()

std::string get_name ( ) const
inline

Get the name of the current app.

Definition at line 5345 of file CLI11.hpp.

◆ get_option() [1/2]

const Option* get_option ( std::string  option_name) const
inline

Get an option by name.

Definition at line 5241 of file CLI11.hpp.

◆ get_option() [2/2]

Option* get_option ( std::string  option_name)
inline

Get an option by name (non-const version)

Definition at line 5250 of file CLI11.hpp.

◆ get_option_group()

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

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

Definition at line 4782 of file CLI11.hpp.

◆ get_option_no_throw() [1/2]

Option* get_option_no_throw ( std::string  option_name)
inlinenoexcept

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

Definition at line 5203 of file CLI11.hpp.

◆ get_option_no_throw() [2/2]

const Option* get_option_no_throw ( std::string  option_name) const
inlinenoexcept

Get an option by name (noexcept const version)

Definition at line 5222 of file CLI11.hpp.

◆ get_options()

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

Definition at line 5186 of file CLI11.hpp.

◆ get_parent() [1/2]

App* get_parent ( )
inline

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

Definition at line 5339 of file CLI11.hpp.

◆ get_parent() [2/2]

const App* get_parent ( ) const
inline

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

Definition at line 5342 of file CLI11.hpp.

◆ get_positionals_at_end()

bool get_positionals_at_end ( ) const
inline

Check the status of the allow windows style options.

Definition at line 5277 of file CLI11.hpp.

◆ get_prefix_command()

bool get_prefix_command ( ) const
inline

Get the prefix command status.

Definition at line 5298 of file CLI11.hpp.

◆ get_require_option_max()

size_t get_require_option_max ( ) const
inline

Get the required max option value.

Definition at line 5295 of file CLI11.hpp.

◆ get_require_option_min()

size_t get_require_option_min ( ) const
inline

Get the required min option value.

Definition at line 5292 of file CLI11.hpp.

◆ get_require_subcommand_max()

size_t get_require_subcommand_max ( ) const
inline

Get the required max subcommand value.

Definition at line 5289 of file CLI11.hpp.

◆ get_require_subcommand_min()

size_t get_require_subcommand_min ( ) const
inline

Get the required min subcommand value.

Definition at line 5286 of file CLI11.hpp.

◆ get_required()

bool get_required ( ) const
inline

Get the status of required.

Definition at line 5304 of file CLI11.hpp.

◆ get_subcommand() [1/3]

App* get_subcommand ( 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

Definition at line 4727 of file CLI11.hpp.

◆ get_subcommand() [2/3]

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

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

Definition at line 4737 of file CLI11.hpp.

◆ get_subcommand() [3/3]

App* get_subcommand ( int  index = 0) const
inline

Get a pointer to subcommand by index.

Definition at line 4744 of file CLI11.hpp.

◆ get_subcommand_ptr() [1/3]

CLI::App_p 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.

Definition at line 4754 of file CLI11.hpp.

◆ get_subcommand_ptr() [2/3]

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

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

Definition at line 4764 of file CLI11.hpp.

◆ get_subcommand_ptr() [3/3]

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

Get an owning pointer to subcommand by index.

Definition at line 4772 of file CLI11.hpp.

◆ get_subcommands() [1/3]

std::vector<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.)

Definition at line 5042 of file CLI11.hpp.

◆ get_subcommands() [2/3]

std::vector<const 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)

Definition at line 5046 of file CLI11.hpp.

◆ get_subcommands() [3/3]

std::vector<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

Definition at line 5064 of file CLI11.hpp.

◆ get_validate_positionals()

bool get_validate_positionals ( ) const
inline

Get the status of validating positionals.

Definition at line 5318 of file CLI11.hpp.

◆ got_subcommand() [1/2]

bool got_subcommand ( App subcom) const
inline

Check to see if given subcommand was selected.

Definition at line 5080 of file CLI11.hpp.

◆ got_subcommand() [2/2]

bool got_subcommand ( std::string  subcommand_name) const
inline

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

Definition at line 5086 of file CLI11.hpp.

◆ group()

App* group ( std::string  group_name)
inline

Changes the group membership.

Definition at line 4813 of file CLI11.hpp.

◆ help()

std::string 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

Definition at line 5152 of file CLI11.hpp.

◆ ignore_case()

App* ignore_case ( bool  value = true)
inline

Ignore case. Subcommands inherit value.

Definition at line 3997 of file CLI11.hpp.

◆ ignore_underscore()

App* ignore_underscore ( bool  value = true)
inline

Ignore underscore. Subcommands inherit value.

Definition at line 4021 of file CLI11.hpp.

◆ immediate_callback()

App* immediate_callback ( bool  immediate = true)
inline

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

Definition at line 3971 of file CLI11.hpp.

◆ increment_parsed()

void increment_parsed ( )
inlineprotected

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

Definition at line 5800 of file CLI11.hpp.

◆ name()

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

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

Definition at line 3933 of file CLI11.hpp.

◆ operator bool()

operator bool ( ) const
inline

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

Definition at line 4885 of file CLI11.hpp.

◆ operator[]() [1/2]

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

Shortcut bracket operator for getting a pointer to an option.

Definition at line 5259 of file CLI11.hpp.

◆ operator[]() [2/2]

const Option* operator[] ( const char *  option_name) const
inline

Shortcut bracket operator for getting a pointer to an option.

Definition at line 5262 of file CLI11.hpp.

◆ option_defaults()

OptionDefaults* option_defaults ( )
inline

Get the OptionDefault object, to set option defaults.

Definition at line 4054 of file CLI11.hpp.

◆ parse() [1/4]

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

Definition at line 4918 of file CLI11.hpp.

◆ parse() [2/4]

void 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

Definition at line 4936 of file CLI11.hpp.

◆ parse() [3/4]

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

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

Definition at line 4964 of file CLI11.hpp.

◆ parse() [4/4]

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

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

Definition at line 4984 of file CLI11.hpp.

◆ parse_order()

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

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

Definition at line 5380 of file CLI11.hpp.

◆ parsed()

bool parsed ( ) const
inline

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

Definition at line 4051 of file CLI11.hpp.

◆ positionals_at_end()

App* positionals_at_end ( bool  value = true)
inline

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

Definition at line 4015 of file CLI11.hpp.

◆ pre_callback()

virtual void 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.

Reimplemented in main_app.

Definition at line 4894 of file CLI11.hpp.

◆ prefix_command()

App* prefix_command ( bool  allow = true)
inline

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

Definition at line 3991 of file CLI11.hpp.

◆ preparse_callback()

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

Set a callback to execute prior to parsing.

Definition at line 3927 of file CLI11.hpp.

◆ remaining()

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

This returns the missing options from the current subcommand.

Definition at line 5383 of file CLI11.hpp.

◆ remaining_for_passthrough()

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

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

Definition at line 5410 of file CLI11.hpp.

◆ remaining_size()

size_t remaining_size ( bool  recurse = false) const
inline

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

Definition at line 5417 of file CLI11.hpp.

◆ remove_excludes() [1/2]

bool remove_excludes ( Option opt)
inline

Removes an option from the excludes list of this subcommand.

Definition at line 5111 of file CLI11.hpp.

◆ remove_excludes() [2/2]

bool remove_excludes ( App app)
inline

Removes a subcommand from this excludes list of this subcommand.

Definition at line 5122 of file CLI11.hpp.

◆ remove_option()

bool remove_option ( Option opt)
inline

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

Definition at line 4654 of file CLI11.hpp.

◆ remove_subcommand()

bool remove_subcommand ( App subcom)
inline

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

Definition at line 4711 of file CLI11.hpp.

◆ require_option() [1/3]

App* require_option ( )
inline

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

Definition at line 4848 of file CLI11.hpp.

◆ require_option() [2/3]

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

Definition at line 4857 of file CLI11.hpp.

◆ require_option() [3/3]

App* require_option ( size_t  min,
size_t  max 
)
inline

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

Definition at line 4870 of file CLI11.hpp.

◆ require_subcommand() [1/3]

App* require_subcommand ( )
inline

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

Definition at line 4819 of file CLI11.hpp.

◆ require_subcommand() [2/3]

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.

Definition at line 4828 of file CLI11.hpp.

◆ require_subcommand() [3/3]

App* require_subcommand ( size_t  min,
size_t  max 
)
inline

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

Definition at line 4841 of file CLI11.hpp.

◆ required()

App* required ( bool  require = true)
inline

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

Definition at line 3946 of file CLI11.hpp.

◆ run_callback()

void run_callback ( )
inlineprotected

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

Definition at line 5490 of file CLI11.hpp.

◆ set_config()

Option* set_config ( std::string  option_name = "",
std::string  default_filename = "",
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.

Definition at line 4633 of file CLI11.hpp.

◆ set_help_all_flag()

Option* 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.

Definition at line 4235 of file CLI11.hpp.

◆ set_help_flag()

Option* set_help_flag ( std::string  flag_name = "",
const std::string &  help_description = "" 
)
inline

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

Definition at line 4218 of file CLI11.hpp.

◆ validate_positionals()

App* validate_positionals ( bool  validate = true)
inline

Set the subcommand to validate positional arguments before assigning.

Definition at line 3977 of file CLI11.hpp.

Member Data Documentation

◆ allow_config_extras_

bool allow_config_extras_ {false}
protected

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

Definition at line 3716 of file CLI11.hpp.

◆ allow_extras_

bool allow_extras_ {false}
protected

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

Definition at line 3713 of file CLI11.hpp.

◆ allow_windows_style_options_

bool allow_windows_style_options_
protected
Initial value:
{
false
}

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

Definition at line 3813 of file CLI11.hpp.

◆ callback_

std::function<void()> callback_
protected

This is a function that runs when complete. Great for subcommands. Can throw.

Definition at line 3741 of file CLI11.hpp.

◆ config_formatter_

std::shared_ptr<Config> config_formatter_ {new ConfigINI()}
protected

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

Definition at line 3864 of file CLI11.hpp.

◆ config_name_

std::string config_name_
protected

The name of the connected config file.

Definition at line 3855 of file CLI11.hpp.

◆ config_ptr_

Option* config_ptr_ {nullptr}
protected

Pointer to the config option.

Definition at line 3861 of file CLI11.hpp.

◆ config_required_

bool config_required_ {false}
protected

True if ini is required (throws if not present), if false simply keep going.

Definition at line 3858 of file CLI11.hpp.

◆ description_

std::string description_
protected

Description of the current program/subcommand.

Definition at line 3710 of file CLI11.hpp.

◆ disabled_

bool disabled_ {false}
protected

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

Definition at line 3728 of file CLI11.hpp.

◆ disabled_by_default_

bool disabled_by_default_ {false}
protected

If set to true the subcommand will start each parse disabled.

Definition at line 3824 of file CLI11.hpp.

◆ enabled_by_default_

bool enabled_by_default_ {false}
protected

If set to true the subcommand will be reenabled at the start of each parse.

Definition at line 3826 of file CLI11.hpp.

◆ exclude_options_

std::set<Option *> 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

Definition at line 3794 of file CLI11.hpp.

◆ exclude_subcommands_

std::set<App *> exclude_subcommands_
protected

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

Definition at line 3790 of file CLI11.hpp.

◆ failure_message_

std::function<std::string(const App *, const Error &e)> failure_message_ = FailureMessage::simple
protected

The error message printing function INHERITABLE.

Definition at line 3770 of file CLI11.hpp.

◆ fallthrough_

bool fallthrough_ {false}
protected

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

Definition at line 3810 of file CLI11.hpp.

◆ footer_

std::string footer_
protected

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

Definition at line 3758 of file CLI11.hpp.

◆ formatter_

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

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

Definition at line 3767 of file CLI11.hpp.

◆ group_

std::string group_ {"Subcommands"}
protected

The group membership INHERITABLE.

Definition at line 3848 of file CLI11.hpp.

◆ has_automatic_name_

bool has_automatic_name_ {false}
protected

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

Definition at line 3722 of file CLI11.hpp.

◆ help_all_ptr_

Option* help_all_ptr_ {nullptr}
protected

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

Definition at line 3764 of file CLI11.hpp.

◆ help_ptr_

Option* help_ptr_ {nullptr}
protected

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

Definition at line 3761 of file CLI11.hpp.

◆ ignore_case_

bool ignore_case_ {false}
protected

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

Definition at line 3804 of file CLI11.hpp.

◆ ignore_underscore_

bool ignore_underscore_ {false}
protected

If true, the program should ignore underscores INHERITABLE.

Definition at line 3807 of file CLI11.hpp.

◆ immediate_callback_

bool 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

Definition at line 3735 of file CLI11.hpp.

◆ missing_

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

Definition at line 3781 of file CLI11.hpp.

◆ name_

std::string name_
protected

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

Definition at line 3707 of file CLI11.hpp.

◆ Option

friend Option
private

Definition at line 3697 of file CLI11.hpp.

◆ option_defaults_

OptionDefaults option_defaults_
protected

The default values for options, customizable and changeable INHERITABLE.

Definition at line 3748 of file CLI11.hpp.

◆ options_

std::vector<Option_p> options_
protected

The list of options, stored locally.

Definition at line 3751 of file CLI11.hpp.

◆ parent_

App* parent_ {nullptr}
protected

A pointer to the parent if this is a subcommand.

Definition at line 3830 of file CLI11.hpp.

◆ parse_order_

std::vector<Option *> parse_order_
protected

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

Definition at line 3784 of file CLI11.hpp.

◆ parsed_

size_t parsed_ = 0
protected

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

Definition at line 3833 of file CLI11.hpp.

◆ parsed_subcommands_

std::vector<App *> parsed_subcommands_
protected

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

Definition at line 3787 of file CLI11.hpp.

◆ positionals_at_end_

bool positionals_at_end_ {false}
protected

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

Definition at line 3821 of file CLI11.hpp.

◆ pre_parse_callback_

std::function<void(size_t)> pre_parse_callback_
protected

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

Definition at line 3738 of file CLI11.hpp.

◆ pre_parse_called_

bool pre_parse_called_ {false}
protected

Flag indicating that the pre_parse_callback has been triggered.

Definition at line 3731 of file CLI11.hpp.

◆ prefix_command_

bool prefix_command_ {false}
protected

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

Definition at line 3719 of file CLI11.hpp.

◆ require_option_max_

size_t require_option_max_ = 0
protected

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

Definition at line 3845 of file CLI11.hpp.

◆ require_option_min_

size_t require_option_min_ = 0
protected

Minimum required options (not inheritable!)

Definition at line 3842 of file CLI11.hpp.

◆ require_subcommand_max_

size_t require_subcommand_max_ = 0
protected

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

Definition at line 3839 of file CLI11.hpp.

◆ require_subcommand_min_

size_t require_subcommand_min_ = 0
protected

Minimum required subcommands (not inheritable!)

Definition at line 3836 of file CLI11.hpp.

◆ required_

bool required_ {false}
protected

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

Definition at line 3725 of file CLI11.hpp.

◆ subcommands_

std::vector<App_p> subcommands_
protected

Storage for subcommand list.

Definition at line 3801 of file CLI11.hpp.

◆ validate_positionals_

bool validate_positionals_ {false}
protected

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

Definition at line 3828 of file CLI11.hpp.


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