CLI11
C++11 Command Line Interface Parser
Protected Member Functions | List of all members
CLI::Option Class Reference
Inheritance diagram for CLI::Option:
CLI::OptionBase< Option >

Public Member Functions

Basic
size_t count () const
 Count the total number of times an option was passed.
 
size_t empty () const
 True if the option was not passed.
 
 operator bool () const
 This class is true if option is passed.
 
void clear ()
 Clear the parsed results (mostly for testing)
 
Setting options
Optionexpected (int value)
 Set the number of expected arguments (Flags don't use this)
 
Optioncheck (Validator validator, std::string validator_name="")
 Adds a Validator with a built in type name.
 
Optioncheck (std::function< std::string(const std::string &)> validator, std::string validator_description="", std::string validator_name="")
 Adds a Validator. Takes a const string& and returns an error message (empty if conversion/check is okay).
 
Optiontransform (Validator validator, std::string validator_name="")
 Adds a transforming validator with a built in type name.
 
Optiontransform (std::function< std::string(std::string)> func, std::string transform_description="", std::string transform_name="")
 Adds a validator-like function that can change result.
 
Optioneach (std::function< void(std::string)> func)
 Adds a user supplied function to run on each item passed in (communicate though lambda capture)
 
Validatorget_validator (const std::string &validator_name="")
 Get a named Validator.
 
Optionneeds (Option *opt)
 Sets required options.
 
template<typename T = App>
Optionneeds (std::string opt_name)
 Can find a string if needed.
 
template<typename A , typename B , typename... ARG>
Optionneeds (A opt, B opt1, ARG... args)
 Any number supported, any mix of string and Opt.
 
bool remove_needs (Option *opt)
 Remove needs link from an option. Returns true if the option really was in the needs list.
 
Optionexcludes (Option *opt)
 Sets excluded options.
 
template<typename T = App>
Optionexcludes (std::string opt_name)
 Can find a string if needed.
 
template<typename A , typename B , typename... ARG>
Optionexcludes (A opt, B opt1, ARG... args)
 Any number supported, any mix of string and Opt.
 
bool remove_excludes (Option *opt)
 Remove needs link from an option. Returns true if the option really was in the needs list.
 
Optionenvname (std::string name)
 Sets environment variable to read if no option given.
 
template<typename T = App>
Optionignore_case (bool value=true)
 
template<typename T = App>
Optionignore_underscore (bool value=true)
 
Optionmulti_option_policy (MultiOptionPolicy value=MultiOptionPolicy::Throw)
 Take the last argument if given multiple times (or another policy)
 
Optiondisable_flag_override (bool value=true)
 disable flag overrides
 
Accessors
int get_type_size () const
 The number of arguments the option expects.
 
std::string get_envname () const
 The environment variable associated to this value.
 
std::set< Option * > get_needs () const
 The set of options needed.
 
std::set< Option * > get_excludes () const
 The set of options excluded.
 
std::string get_defaultval () const
 The default value (for help printing) DEPRECATED Use get_default_str() instead.
 
std::string get_default_str () const
 The default value (for help printing)
 
callback_t get_callback () const
 Get the callback function.
 
const std::vector< std::string > get_lnames () const
 Get the long names.
 
const std::vector< std::string > get_snames () const
 Get the short names.
 
const std::vector< std::string > get_fnames () const
 get the flag names with specified default values
 
int get_expected () const
 The number of times the option expects to be included.
 
int get_items_expected () const
 The total number of expected values (including the type) This is positive if exactly this number is expected, and negative for at least N values. More...
 
bool get_positional () const
 True if the argument can be given directly.
 
bool nonpositional () const
 True if option has at least one non-positional name.
 
bool has_description () const
 True if option has description.
 
const std::string & get_description () const
 Get the description.
 
Optiondescription (std::string option_description)
 Set the description.
 
Help tools
std::string get_name (bool positional=false, bool all_options=false) const
 Gets a comma separated list of names. Will include / prefer the positional name if positional is true. If all_options is false, pick just the most descriptive name to show. Use get_name(true) to get the positional name (replaces get_pname) More...
 
Parser tools
void run_callback ()
 Process the callback.
 
bool operator== (const Option &other) const
 If options share any of the same names, they are equal (not counting positional)
 
bool check_name (std::string name) const
 Check a name. Requires "-" or "--" for short / long, supports positional name.
 
bool check_sname (std::string name) const
 Requires "-" to be removed from string.
 
bool check_lname (std::string name) const
 Requires "--" to be removed from string.
 
bool check_fname (std::string name) const
 Requires "--" to be removed from string.
 
std::string get_flag_value (std::string name, std::string input_value) const
 
Optionadd_result (std::string s)
 Puts a result at the end.
 
Optionadd_result (std::string s, int &results_added)
 Puts a result at the end and get a count of the number of arguments actually added.
 
Optionadd_result (std::vector< std::string > s)
 Puts a result at the end.
 
std::vector< std::string > results () const
 Get a copy of the results.
 
template<typename T , enable_if_t<!is_vector< T >::value &&!std::is_const< T >::value, detail::enabler > = detail::dummy>
void results (T &output) const
 get the results as a particular type
 
template<typename T >
void results (std::vector< T > &output) const
 get the results as a vector of a particular type
 
template<typename T >
as () const
 return the results as a particular type
 
bool get_callback_run () const
 See if the callback has been run already.
 
- Public Member Functions inherited from CLI::OptionBase< Option >
Optiongroup (std::string name)
 Changes the group membership.
 
Optionrequired (bool value=true)
 Set the option as required.
 
Optionmandatory (bool value=true)
 Support Plumbum term.
 
Optionalways_capture_default (bool value=true)
 
const std::string & get_group () const
 Get the group of this option.
 
bool get_required () const
 True if this is a required option.
 
bool get_ignore_case () const
 The status of ignore case.
 
bool get_ignore_underscore () const
 The status of ignore_underscore.
 
bool get_configurable () const
 The status of configurable.
 
bool get_disable_flag_override () const
 The status of configurable.
 
char get_delimiter () const
 Get the current delimeter char.
 
bool get_always_capture_default () const
 Return true if this will automatically capture the default value for help printing.
 
MultiOptionPolicy get_multi_option_policy () const
 The status of the multi option policy.
 
Optiontake_last ()
 Set the multi option policy to take last.
 
Optiontake_first ()
 Set the multi option policy to take last.
 
Optionjoin ()
 Set the multi option policy to take last.
 
Optionconfigurable (bool value=true)
 Allow in a configuration file.
 
Optiondelimiter (char value='\0')
 Allow in a configuration file.
 

Protected Member Functions

 Option (std::string option_name, std::string option_description, std::function< bool(results_t)> callback, App *parent)
 Making an option by hand is not defined, it must be made by the App class.
 
- Protected Member Functions inherited from CLI::OptionBase< Option >
void copy_to (T *other) const
 Copy the contents to another similar class (one based on OptionBase)
 

Protected Attributes

Names
std::vector< std::string > snames_
 A list of the short names (-a) without the leading dashes.
 
std::vector< std::string > lnames_
 A list of the long names (--a) without the leading dashes.
 
std::vector< std::pair< std::string, std::string > > default_flag_values_
 
std::vector< std::string > fnames_
 a list of flag names with specified default values;
 
std::string pname_
 A positional name.
 
std::string envname_
 If given, check the environment for this option.
 
Help
std::string description_
 The description for help strings.
 
std::string default_str_
 A human readable default value, either manually set, captured, or captured by default.
 
std::function< std::string()> type_name_ {[]() { return std::string(); }}
 
std::function< std::string()> default_function_
 Run this function to capture a default (ignore if empty)
 
Configuration
int type_size_ {1}
 
int expected_ {1}
 The number of expected values, type_size_ must be < 0. Ignored for flag. N < 0 means at least -N values.
 
std::vector< Validatorvalidators_
 A list of validators to run on each value parsed.
 
std::set< Option * > needs_
 A list of options that are required with this option.
 
std::set< Option * > excludes_
 A list of options that are excluded with this option.
 
Other
Appparent_
 Remember the parent app.
 
callback_t callback_
 Options store a callback to do all the work.
 
Parsing results
results_t results_
 Results of parsing.
 
bool callback_run_ {false}
 Whether the callback has run (needed for INI parsing)
 
- Protected Attributes inherited from CLI::OptionBase< Option >
std::string group_
 The group membership.
 
bool required_
 True if this is a required option.
 
bool ignore_case_
 Ignore the case when matching (option, not value)
 
bool ignore_underscore_
 Ignore underscores when matching (option, not value)
 
bool configurable_
 Allow this option to be given in a configuration file.
 
bool disable_flag_override_
 Disable overriding flag values with '=value'.
 
char delimiter_
 Specify a delimiter character for vector arguments.
 
bool always_capture_default_
 Automatically capture default value.
 
MultiOptionPolicy multi_option_policy_
 Policy for multiple arguments when expected_ == 1 (can be set on bool flags, too)
 

Custom options

Optiontype_name_fn (std::function< std::string()> typefun)
 Set the type function to run when displayed on this option.
 
Optiontype_name (std::string typeval)
 Set a custom option typestring.
 
Optiontype_size (int option_type_size)
 Set a custom option size.
 
Optiondefault_function (const std::function< std::string()> &func)
 Set a capture function for the default. Mostly used by App.
 
Optioncapture_default_str ()
 Capture the default value from the original value (if it can be captured)
 
Optiondefault_str (std::string val)
 Set the default value string representation (does not change the contained value)
 
Optiondefault_val (std::string val)
 Set the default value string representation and evaluate into the bound value.
 
std::string get_type_name () const
 Get the full typename for this option.
 

Member Function Documentation

◆ get_items_expected()

int CLI::Option::get_items_expected ( ) const
inline

The total number of expected values (including the type) This is positive if exactly this number is expected, and negative for at least N values.

v = fabs(size_type*expected) !MultiOptionPolicyThrow | Expected < 0 | Expected == 0 | Expected > 0 Size < 0 | -v | 0 | -v Size == 0 | 0 | 0 | 0 Size > 0 | -v | 0 | -v // Expected must be 1

MultiOptionPolicy::Throw | Expected < 0 | Expected == 0 | Expected > 0 Size < 0 | -v | 0 | v Size == 0 | 0 | 0 | 0 Size > 0 | v | 0 | v // Expected must be 1

◆ get_name()

std::string CLI::Option::get_name ( bool  positional = false,
bool  all_options = false 
) const
inline

Gets a comma separated list of names. Will include / prefer the positional name if positional is true. If all_options is false, pick just the most descriptive name to show. Use get_name(true) to get the positional name (replaces get_pname)

The all list will never include a positional unless asked or that's the only name.

◆ ignore_case()

template<typename T = App>
Option* CLI::Option::ignore_case ( bool  value = true)
inline

Ignore case

The template hides the fact that we don't have the definition of App yet. You are never expected to add an argument to the template here.

◆ ignore_underscore()

template<typename T = App>
Option* CLI::Option::ignore_underscore ( bool  value = true)
inline

Ignore underscores in the option names

The template hides the fact that we don't have the definition of App yet. You are never expected to add an argument to the template here.

Member Data Documentation

◆ default_flag_values_

std::vector<std::pair<std::string, std::string> > CLI::Option::default_flag_values_
protected

A list of the flag names with the appropriate default value, the first part of the pair should be duplicates of what is in snames or lnames but will trigger a particular response on a flag

◆ type_name_

std::function<std::string()> CLI::Option::type_name_ {[]() { return std::string(); }}
protected

A human readable type value, set when App creates this

This is a lambda function so "types" can be dynamic, such as when a set prints its contents.

◆ type_size_

int CLI::Option::type_size_ {1}
protected

The number of arguments that make up one option. -1=unlimited (vector-like), 0=flag, 1=normal option, 2=complex/pair, etc. Set only when the option is created; this is intrinsic to the type. Eventually, -2 may mean vector of pairs.


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