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

#include <CLI11.hpp>

Inheritance diagram for Option:
Inheritance graph

Public Member Functions

Basic
size_t count () const
 Count the total number of times an option was passed. More...
 
size_t empty () const
 True if the option was not passed. More...
 
 operator bool () const
 This class is true if option is passed. More...
 
void clear ()
 Clear the parsed results (mostly for testing) More...
 
Setting options
Optionexpected (int value)
 Set the number of expected arguments (Flags don't use this) More...
 
Optioncheck (Validator validator, std::string validator_name="")
 Adds a Validator with a built in type name. More...
 
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). More...
 
Optiontransform (Validator validator, std::string validator_name="")
 Adds a transforming validator with a built in type name. More...
 
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. More...
 
Optioneach (std::function< void(std::string)> func)
 Adds a user supplied function to run on each item passed in (communicate though lambda capture) More...
 
Validatorget_validator (const std::string &validator_name="")
 Get a named Validator. More...
 
Optionneeds (Option *opt)
 Sets required options. More...
 
template<typename T = App>
Optionneeds (std::string opt_name)
 Can find a string if needed. More...
 
template<typename A , typename B , typename... ARG>
Optionneeds (A opt, B opt1, ARG... args)
 Any number supported, any mix of string and Opt. More...
 
bool remove_needs (Option *opt)
 Remove needs link from an option. Returns true if the option really was in the needs list. More...
 
Optionexcludes (Option *opt)
 Sets excluded options. More...
 
template<typename T = App>
Optionexcludes (std::string opt_name)
 Can find a string if needed. More...
 
template<typename A , typename B , typename... ARG>
Optionexcludes (A opt, B opt1, ARG... args)
 Any number supported, any mix of string and Opt. More...
 
bool remove_excludes (Option *opt)
 Remove needs link from an option. Returns true if the option really was in the needs list. More...
 
Optionenvname (std::string name)
 Sets environment variable to read if no option given. More...
 
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) More...
 
Optiondisable_flag_override (bool value=true)
 disable flag overrides More...
 
Accessors
int get_type_size () const
 The number of arguments the option expects. More...
 
std::string get_envname () const
 The environment variable associated to this value. More...
 
std::set< Option * > get_needs () const
 The set of options needed. More...
 
std::set< Option * > get_excludes () const
 The set of options excluded. More...
 
 __attribute__ ((deprecated("Use get_default_str() instead"))) std
 The default value (for help printing) DEPRECATED Use get_default_str() instead. More...
 
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. More...
 
bool operator== (const Option &other) const
 If options share any of the same names, they are equal (not counting positional) More...
 
bool check_name (std::string name) const
 Check a name. Requires "-" or "--" for short / long, supports positional name. More...
 
bool check_sname (std::string name) const
 Requires "-" to be removed from string. More...
 
bool check_lname (std::string name) const
 Requires "--" to be removed from string. More...
 
bool check_fname (std::string name) const
 Requires "--" to be removed from string. More...
 
std::string get_flag_value (std::string name, std::string input_value) const
 
Optionadd_result (std::string s)
 Puts a result at the end. More...
 
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. More...
 
Optionadd_result (std::vector< std::string > s)
 Puts a result at the end. More...
 
std::vector< std::string > results () const
 Get a copy of the results. More...
 
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 More...
 
template<typename T >
void results (std::vector< T > &output) const
 get the results as a vector of a particular type More...
 
template<typename T >
as () const
 return the results as a particular type More...
 
bool get_callback_run () const
 See if the callback has been run already. More...
 
- Public Member Functions inherited from OptionBase< Option >
Optiongroup (std::string name)
 Changes the group membership. More...
 
Optionrequired (bool value=true)
 Set the option as required. More...
 
Optionmandatory (bool value=true)
 Support Plumbum term. More...
 
Optionalways_capture_default (bool value=true)
 
const std::string & get_group () const
 Get the group of this option. More...
 
bool get_required () const
 True if this is a required option. More...
 
bool get_ignore_case () const
 The status of ignore case. More...
 
bool get_ignore_underscore () const
 The status of ignore_underscore. More...
 
bool get_configurable () const
 The status of configurable. More...
 
bool get_disable_flag_override () const
 The status of configurable. More...
 
char get_delimiter () const
 Get the current delimeter char. More...
 
bool get_always_capture_default () const
 Return true if this will automatically capture the default value for help printing. More...
 
MultiOptionPolicy get_multi_option_policy () const
 The status of the multi option policy. More...
 
Optiontake_last ()
 Set the multi option policy to take last. More...
 
Optiontake_first ()
 Set the multi option policy to take last. More...
 
Optionjoin ()
 Set the multi option policy to take last. More...
 
Optionconfigurable (bool value=true)
 Allow in a configuration file. More...
 
Optiondelimiter (char value='\0')
 Allow in a configuration file. More...
 

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. More...
 
- Protected Member Functions inherited from OptionBase< Option >
void copy_to (T *other) const
 Copy the contents to another similar class (one based on OptionBase) More...
 

Protected Attributes

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

Private Attributes

friend App
 

Custom options

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

Detailed Description

Definition at line 2848 of file CLI11.hpp.

Constructor & Destructor Documentation

◆ Option()

Option ( std::string  option_name,
std::string  option_description,
std::function< bool(results_t)>  callback,
App parent 
)
inlineprotected

Making an option by hand is not defined, it must be made by the App class.

Definition at line 2936 of file CLI11.hpp.

Member Function Documentation

◆ __attribute__()

__attribute__ ( (deprecated("Use get_default_str() instead"))  )
inline

The default value (for help printing) DEPRECATED Use get_default_str() instead.

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

Definition at line 3194 of file CLI11.hpp.

◆ _add_result()

int _add_result ( std::string &&  result)
inlineprivate

Definition at line 3640 of file CLI11.hpp.

◆ _validate()

std::string _validate ( std::string &  result)
inlineprivate

Definition at line 3626 of file CLI11.hpp.

◆ add_result() [1/3]

Option* add_result ( std::string  s)
inline

Puts a result at the end.

Definition at line 3475 of file CLI11.hpp.

◆ add_result() [2/3]

Option* add_result ( std::string  s,
int &  results_added 
)
inline

Puts a result at the end and get a count of the number of arguments actually added.

Definition at line 3482 of file CLI11.hpp.

◆ add_result() [3/3]

Option* add_result ( std::vector< std::string >  s)
inline

Puts a result at the end.

Definition at line 3489 of file CLI11.hpp.

◆ as()

T as ( ) const
inline

return the results as a particular type

Definition at line 3545 of file CLI11.hpp.

◆ capture_default_str()

Option* capture_default_str ( )
inline

Capture the default value from the original value (if it can be captured)

Definition at line 3587 of file CLI11.hpp.

◆ check() [1/2]

Option* check ( Validator  validator,
std::string  validator_name = "" 
)
inline

Adds a Validator with a built in type name.

Definition at line 2992 of file CLI11.hpp.

◆ check() [2/2]

Option* check ( std::function< std::string(const std::string &)>  validator,
std::string  validator_description = "",
std::string  validator_name = "" 
)
inline

Adds a Validator. Takes a const string& and returns an error message (empty if conversion/check is okay).

Definition at line 3001 of file CLI11.hpp.

◆ check_fname()

bool check_fname ( std::string  name) const
inline

Requires "--" to be removed from string.

Definition at line 3428 of file CLI11.hpp.

◆ check_lname()

bool check_lname ( std::string  name) const
inline

Requires "--" to be removed from string.

Definition at line 3423 of file CLI11.hpp.

◆ check_name()

bool check_name ( std::string  name) const
inline

Check a name. Requires "-" or "--" for short / long, supports positional name.

Definition at line 3399 of file CLI11.hpp.

◆ check_sname()

bool check_sname ( std::string  name) const
inline

Requires "-" to be removed from string.

Definition at line 3420 of file CLI11.hpp.

◆ clear()

void clear ( )
inline

Clear the parsed results (mostly for testing)

Definition at line 2958 of file CLI11.hpp.

◆ count()

size_t count ( ) const
inline

Count the total number of times an option was passed.

Definition at line 2949 of file CLI11.hpp.

◆ default_function()

Option* default_function ( const std::function< std::string()> &  func)
inline

Set a capture function for the default. Mostly used by App.

Definition at line 3581 of file CLI11.hpp.

◆ default_str()

Option* default_str ( std::string  val)
inline

Set the default value string representation (does not change the contained value)

Definition at line 3595 of file CLI11.hpp.

◆ default_val()

Option* default_val ( std::string  val)
inline

Set the default value string representation and evaluate into the bound value.

Definition at line 3601 of file CLI11.hpp.

◆ disable_flag_override()

Option* disable_flag_override ( bool  value = true)
inline

disable flag overrides

Definition at line 3173 of file CLI11.hpp.

◆ each()

Option* each ( std::function< void(std::string)>  func)
inline

Adds a user supplied function to run on each item passed in (communicate though lambda capture)

Definition at line 3034 of file CLI11.hpp.

◆ empty()

size_t empty ( ) const
inline

True if the option was not passed.

Definition at line 2952 of file CLI11.hpp.

◆ envname()

Option* envname ( std::string  name)
inline

Sets environment variable to read if no option given.

Definition at line 3129 of file CLI11.hpp.

◆ excludes() [1/3]

Option* excludes ( Option opt)
inline

Sets excluded options.

Definition at line 3090 of file CLI11.hpp.

◆ excludes() [2/3]

Option* excludes ( std::string  opt_name)
inline

Can find a string if needed.

Definition at line 3103 of file CLI11.hpp.

◆ excludes() [3/3]

Option* excludes ( opt,
opt1,
ARG...  args 
)
inline

Any number supported, any mix of string and Opt.

Definition at line 3111 of file CLI11.hpp.

◆ expected()

Option* expected ( int  value)
inline

Set the number of expected arguments (Flags don't use this)

Definition at line 2965 of file CLI11.hpp.

◆ get_callback_run()

bool get_callback_run ( ) const
inline

See if the callback has been run already.

Definition at line 3552 of file CLI11.hpp.

◆ get_envname()

std::string get_envname ( ) const
inline

The environment variable associated to this value.

Definition at line 3185 of file CLI11.hpp.

◆ get_excludes()

std::set<Option *> get_excludes ( ) const
inline

The set of options excluded.

Definition at line 3191 of file CLI11.hpp.

◆ get_flag_value()

std::string get_flag_value ( std::string  name,
std::string  input_value 
) const
inline

Definition at line 3435 of file CLI11.hpp.

◆ get_name()

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

Definition at line 3262 of file CLI11.hpp.

◆ get_needs()

std::set<Option *> get_needs ( ) const
inline

The set of options needed.

Definition at line 3188 of file CLI11.hpp.

◆ get_type_name()

std::string get_type_name ( ) const
inline

Get the full typename for this option.

Definition at line 3611 of file CLI11.hpp.

◆ get_type_size()

int get_type_size ( ) const
inline

The number of arguments the option expects.

Definition at line 3182 of file CLI11.hpp.

◆ get_validator()

Validator* get_validator ( const std::string &  validator_name = "")
inline

Get a named Validator.

Definition at line 3044 of file CLI11.hpp.

◆ ignore_case()

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.

Definition at line 3138 of file CLI11.hpp.

◆ ignore_underscore()

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.

Definition at line 3153 of file CLI11.hpp.

◆ multi_option_policy()

Option* multi_option_policy ( MultiOptionPolicy  value = MultiOptionPolicy::Throw)
inline

Take the last argument if given multiple times (or another policy)

Definition at line 3164 of file CLI11.hpp.

◆ needs() [1/3]

Option* needs ( Option opt)
inline

Sets required options.

Definition at line 3056 of file CLI11.hpp.

◆ needs() [2/3]

Option* needs ( std::string  opt_name)
inline

Can find a string if needed.

Definition at line 3064 of file CLI11.hpp.

◆ needs() [3/3]

Option* needs ( opt,
opt1,
ARG...  args 
)
inline

Any number supported, any mix of string and Opt.

Definition at line 3072 of file CLI11.hpp.

◆ operator bool()

operator bool ( ) const
inline

This class is true if option is passed.

Definition at line 2955 of file CLI11.hpp.

◆ operator==()

bool operator== ( const Option other) const
inline

If options share any of the same names, they are equal (not counting positional)

Definition at line 3378 of file CLI11.hpp.

◆ remove_excludes()

bool remove_excludes ( Option opt)
inline

Remove needs link from an option. Returns true if the option really was in the needs list.

Definition at line 3117 of file CLI11.hpp.

◆ remove_needs()

bool remove_needs ( Option opt)
inline

Remove needs link from an option. Returns true if the option really was in the needs list.

Definition at line 3078 of file CLI11.hpp.

◆ results() [1/3]

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

Get a copy of the results.

Definition at line 3498 of file CLI11.hpp.

◆ results() [2/3]

void results ( T &  output) const
inline

get the results as a particular type

Definition at line 3503 of file CLI11.hpp.

◆ results() [3/3]

void results ( std::vector< T > &  output) const
inline

get the results as a vector of a particular type

Definition at line 3530 of file CLI11.hpp.

◆ run_callback()

void run_callback ( )
inline

Process the callback.

Definition at line 3322 of file CLI11.hpp.

◆ transform() [1/2]

Option* transform ( Validator  validator,
std::string  validator_name = "" 
)
inline

Adds a transforming validator with a built in type name.

Definition at line 3010 of file CLI11.hpp.

◆ transform() [2/2]

Option* transform ( std::function< std::string(std::string)>  func,
std::string  transform_description = "",
std::string  transform_name = "" 
)
inline

Adds a validator-like function that can change result.

Definition at line 3018 of file CLI11.hpp.

◆ type_name()

Option* type_name ( std::string  typeval)
inline

Set a custom option typestring.

Definition at line 3565 of file CLI11.hpp.

◆ type_name_fn()

Option* type_name_fn ( std::function< std::string()>  typefun)
inline

Set the type function to run when displayed on this option.

Definition at line 3559 of file CLI11.hpp.

◆ type_size()

Option* type_size ( int  option_type_size)
inline

Set a custom option size.

Definition at line 3571 of file CLI11.hpp.

Member Data Documentation

◆ App

friend App
private

Definition at line 2849 of file CLI11.hpp.

◆ callback_

callback_t callback_
protected

Options store a callback to do all the work.

Definition at line 2921 of file CLI11.hpp.

◆ callback_run_

bool callback_run_ {false}
protected

Whether the callback has run (needed for INI parsing)

Definition at line 2931 of file CLI11.hpp.

◆ default_flag_values_

std::vector<std::pair<std::string, std::string> > 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

Definition at line 2863 of file CLI11.hpp.

◆ default_function_

std::function<std::string()> default_function_
protected

Run this function to capture a default (ignore if empty)

Definition at line 2890 of file CLI11.hpp.

◆ default_str_

std::string default_str_
protected

A human readable default value, either manually set, captured, or captured by default.

Definition at line 2882 of file CLI11.hpp.

◆ description_

std::string description_
protected

The description for help strings.

Definition at line 2879 of file CLI11.hpp.

◆ envname_

std::string envname_
protected

If given, check the environment for this option.

Definition at line 2872 of file CLI11.hpp.

◆ excludes_

std::set<Option *> excludes_
protected

A list of options that are excluded with this option.

Definition at line 2911 of file CLI11.hpp.

◆ expected_

int expected_ {1}
protected

The number of expected values, type_size_ must be < 0. Ignored for flag. N < 0 means at least -N values.

Definition at line 2902 of file CLI11.hpp.

◆ fnames_

std::vector<std::string> fnames_
protected

a list of flag names with specified default values;

Definition at line 2866 of file CLI11.hpp.

◆ lnames_

std::vector<std::string> lnames_
protected

A list of the long names (--a) without the leading dashes.

Definition at line 2859 of file CLI11.hpp.

◆ needs_

std::set<Option *> needs_
protected

A list of options that are required with this option.

Definition at line 2908 of file CLI11.hpp.

◆ parent_

App* parent_
protected

Remember the parent app.

Definition at line 2918 of file CLI11.hpp.

◆ pname_

std::string pname_
protected

A positional name.

Definition at line 2869 of file CLI11.hpp.

◆ results_

results_t results_
protected

Results of parsing.

Definition at line 2928 of file CLI11.hpp.

◆ snames_

std::vector<std::string> snames_
protected

A list of the short names (-a) without the leading dashes.

Definition at line 2856 of file CLI11.hpp.

◆ type_name_

std::function<std::string()> 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.

Definition at line 2887 of file CLI11.hpp.

◆ type_size_

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

Definition at line 2899 of file CLI11.hpp.

◆ validators_

std::vector<Validator> validators_
protected

A list of validators to run on each value parsed.

Definition at line 2905 of file CLI11.hpp.


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