CLI::Option Class Reference

#include <CLI11.hpp>

Inheritance diagram for CLI::Option:

Collaboration diagram for CLI::Option:

Public Member Functions
Basic
	Option (const Option &)=delete
Option &	operator= (const Option &)=delete
std::size_t	count () const
	Count the total number of times an option was passed.
bool	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
Option *	expected (int value)
	Set the number of expected arguments.
Option *	expected (int value_min, int value_max)
	Set the range of expected arguments.
Option *	allow_extra_args (bool value=true)
bool	get_allow_extra_args () const
	Get the current value of allow extra args.
Option *	run_callback_for_default (bool value=true)
bool	get_run_callback_for_default () const
	Get the current value of run_callback_for_default.
Option *	check (Validator validator, const std::string &validator_name="")
	Adds a Validator with a built in type name.
Option *	check (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).
Option *	transform (Validator Validator, const std::string &Validator_name="")
	Adds a transforming Validator with a built in type name.
Option *	transform (const std::function< std::string(std::string)> &func, std::string transform_description="", std::string transform_name="")
	Adds a Validator-like function that can change result.
Option *	each (const std::function< void(std::string)> &func)
	Adds a user supplied function to run on each item passed in (communicate though lambda capture)
Validator *	get_validator (const std::string &Validator_name="")
	Get a named Validator.
Validator *	get_validator (int index)
	Get a Validator by index NOTE: this may not be the order of definition.
Option *	needs (Option *opt)
	Sets required options.
template<typename T = App>
Option *	needs (std::string opt_name)
	Can find a string if needed.
template<typename A , typename B , typename... ARG>
Option *	needs (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.
Option *	excludes (Option *opt)
	Sets excluded options.
template<typename T = App>
Option *	excludes (std::string opt_name)
	Can find a string if needed.
template<typename A , typename B , typename... ARG>
Option *	excludes (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.
Option *	envname (std::string name)
	Sets environment variable to read if no option given.
template<typename T = App>
Option *	ignore_case (bool value=true)
template<typename T = App>
Option *	ignore_underscore (bool value=true)
Option *	multi_option_policy (MultiOptionPolicy value=MultiOptionPolicy::Throw)
	Take the last argument if given multiple times (or another policy)
Option *	disable_flag_override (bool value=true)
	Disable flag overrides values, e.g. –flag=is not allowed.
Accessors
int	get_type_size () const
	The number of arguments the option expects.
int	get_type_size_min () const
	The minimum number of arguments the option expects.
int	get_type_size_max () const
	The maximum 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_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_expected_min () const
	The number of times the option expects to be included.
int	get_expected_max () const
	The max number of times the option expects to be included.
int	get_items_expected_min () const
	The total min number of expected string values to be used.
int	get_items_expected_max () const
	Get the maximum number of items expected to be returned and used for the callback.
int	get_items_expected () const
	The total min number of expected string values to be used.
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.
Option *	description (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)
Parser tools
void	run_callback ()
	Process the callback.
const std::string &	matching_name (const Option &other) const
	If options share any of the same names, find it.
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 (const std::string &name, std::string input_value) const
Option *	add_result (std::string s)
	Puts a result at the end.
Option *	add_result (std::string s, int &results_added)
	Puts a result at the end and get a count of the number of arguments actually added.
Option *	add_result (std::vector< std::string > s)
	Puts a result at the end.
results_t	results () const
	Get a copy of the results.
results_t	reduced_results () const
	Get a copy of the results.
template<typename T , enable_if_t<!std::is_const< T >::value, detail::enabler > = detail::dummy>
void	results (T &output) const
	Get the results as a specified type.
template<typename T >
T	as () const
	Return the results as the specified type.
bool	get_callback_run () const
	See if the callback has been run already.
Public Member Functions inherited from CLI::OptionBase< Option >
Option *	group (const std::string &name)
	Changes the group membership.
Option *	required (bool value=true)
	Set the option as required.
Option *	mandatory (bool value=true)
	Support Plumbum term.
Option *	always_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 delimiter 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.
Option *	take_last ()
	Set the multi option policy to take last.
Option *	take_first ()
	Set the multi option policy to take last.
Option *	take_all ()
	Set the multi option policy to take all arguments.
Option *	join ()
	Set the multi option policy to join.
Option *	join (char delim)
	Set the multi option policy to join with a specific delimiter.
Option *	configurable (bool value=true)
	Allow in a configuration file.
Option *	delimiter (char value='\0')
	Allow in a configuration file.

Protected Member Functions
	Option (std::string option_name, std::string option_description, callback_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 (--long) 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_max_ {1}
int	type_size_min_ {1}
	The minimum number of arguments an option should be expecting.
int	expected_min_ {1}
	The minimum number of expected values.
int	expected_max_ {1}
	The maximum number of expected values.
std::vector< Validator >	validators_ {}
	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
App *	parent_ {nullptr}
	Remember the parent app.
callback_t	callback_ {}
	Options store a callback to do all the work.
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 handling multiple arguments beyond the expected Max.

Parsing results
enum class	option_state { parsing = 0 , validated = 2 , reduced = 4 , callback_run = 6 }
	enumeration for the option state machine More...
results_t	results_ {}
	complete Results of parsing
results_t	proc_results_ {}
	results after reduction
option_state	current_option_state_ {option_state::parsing}
	Whether the callback has run (needed for INI parsing)
bool	allow_extra_args_ {false}
	Specify that extra args beyond type_size_max should be allowed.
bool	flag_like_ {false}
	Specify that the option should act like a flag vs regular option.
bool	run_callback_for_default_ {false}
	Control option to run the callback to set the default.

Custom options
Option *	type_name_fn (std::function< std::string()> typefun)
	Set the type function to run when displayed on this option.
Option *	type_name (std::string typeval)
	Set a custom option typestring.
Option *	type_size (int option_type_size)
	Set a custom option size.
Option *	type_size (int option_type_size_min, int option_type_size_max)
	Set a custom option type size range.
Option *	default_function (const std::function< std::string()> &func)
	Set a capture function for the default. Mostly used by App.
Option *	capture_default_str ()
	Capture the default value from the original value (if it can be captured)
Option *	default_str (std::string val)
	Set the default value string representation (does not change the contained value)
template<typename X >
Option *	default_val (const X &val)
std::string	get_type_name () const
	Get the full typename for this option.

Detailed Description

Definition at line 3532 of file CLI11.hpp.

Member Enumeration Documentation

option_state

enum class CLI::Option::option_state

strongprotected

Enumerator
parsing	The option is currently collecting parsed results.
validated	the results have been validated
reduced	a subset of results has been generated
callback_run	the callback has been executed

Definition at line 3619 of file CLI11.hpp.

                            {
        parsing = 0,      
        validated = 2,    
        reduced = 4,      
        callback_run = 6, 
    };

Constructor & Destructor Documentation

Option() [1/2]

CLI::Option::Option ( std::string option_name, std::string option_description, callback_t callback, App * parent )

inlineprotected

Definition at line 3636 of file CLI11.hpp.

        : description_(std::move(option_description)), parent_(parent), callback_(std::move(callback)) {
        std::tie(snames_, lnames_, pname_) = detail::get_names(detail::split_names(option_name));
    }

Here is the call graph for this function:

Option() [2/2]

CLI::Option::Option ( const Option & )

delete

Member Function Documentation

add_result() [1/3]

Option * CLI::Option::add_result ( std::string s )

inline

Definition at line 4223 of file CLI11.hpp.

                                    {
        _add_result(std::move(s), results_);
        current_option_state_ = option_state::parsing;
        return this;
    }

Here is the caller graph for this function:

add_result() [2/3]

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

inline

Definition at line 4230 of file CLI11.hpp.

                                                        {
        results_added = _add_result(std::move(s), results_);
        current_option_state_ = option_state::parsing;
        return this;
    }

add_result() [3/3]

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

inline

Definition at line 4237 of file CLI11.hpp.

                                               {
        for(auto &str : s) {
            _add_result(std::move(str), results_);
        }
        current_option_state_ = option_state::parsing;
        return this;
    }

allow_extra_args()

Option * CLI::Option::allow_extra_args ( bool value = true )

inline

Set the value of allow_extra_args which allows extra value arguments on the flag or option to be included with each instance

Definition at line 3710 of file CLI11.hpp.

                                                {
        allow_extra_args_ = value;
        return this;
    }

Here is the caller graph for this function:

as()

template<typename T >

T CLI::Option::as ( ) const

inline

Definition at line 4300 of file CLI11.hpp.

                                       {
        T output;
        results(output);
        return output;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

capture_default_str()

Option * CLI::Option::capture_default_str ( )

inline

Definition at line 4371 of file CLI11.hpp.

                                  {
        if(default_function_) {
            default_str_ = default_function_();
        }
        return this;
    }

check() [1/2]

Option * CLI::Option::check ( std::function< std::string(const std::string &)> Validator, std::string Validator_description = "", std::string Validator_name = "" )

inline

Definition at line 3736 of file CLI11.hpp.

                                                 {
        validators_.emplace_back(Validator, std::move(Validator_description), std::move(Validator_name));
        validators_.back().non_modifying();
        return this;
    }

check() [2/2]

Option * CLI::Option::check ( Validator validator, const std::string & validator_name = "" )

inline

Definition at line 3727 of file CLI11.hpp.

                                                                             {
        validator.non_modifying();
        validators_.push_back(std::move(validator));
        if(!validator_name.empty())
            validators_.back().name(validator_name);
        return this;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

check_fname()

bool CLI::Option::check_fname ( std::string name ) const

inline

Definition at line 4170 of file CLI11.hpp.

                                           {
        if(fnames_.empty()) {
            return false;
        }
        return (detail::find_member(std::move(name), fnames_, ignore_case_, ignore_underscore_) >= 0);
    }

Here is the call graph for this function:

Here is the caller graph for this function:

check_lname()

bool CLI::Option::check_lname ( std::string name ) const

inline

Definition at line 4165 of file CLI11.hpp.

                                           {
        return (detail::find_member(std::move(name), lnames_, ignore_case_, ignore_underscore_) >= 0);
    }

Here is the call graph for this function:

Here is the caller graph for this function:

check_name()

bool CLI::Option::check_name ( std::string name ) const

inline

Definition at line 4140 of file CLI11.hpp.

                                          {
 
        if(name.length() > 2 && name[0] == '-' && name[1] == '-')
            return check_lname(name.substr(2));
        if(name.length() > 1 && name.front() == '-')
            return check_sname(name.substr(1));
 
        std::string local_pname = pname_;
        if(ignore_underscore_) {
            local_pname = detail::remove_underscore(local_pname);
            name = detail::remove_underscore(name);
        }
        if(ignore_case_) {
            local_pname = detail::to_lower(local_pname);
            name = detail::to_lower(name);
        }
        return name == local_pname;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

check_sname()

bool CLI::Option::check_sname ( std::string name ) const

inline

Definition at line 4160 of file CLI11.hpp.

                                           {
        return (detail::find_member(std::move(name), snames_, ignore_case_) >= 0);
    }

Here is the call graph for this function:

Here is the caller graph for this function:

clear()

void CLI::Option::clear ( )

inline

Definition at line 3658 of file CLI11.hpp.

                 {
        results_.clear();
        current_option_state_ = option_state::parsing;
    }

Here is the caller graph for this function:

count()

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

inline

Definition at line 3649 of file CLI11.hpp.

{ return results_.size(); }

Here is the caller graph for this function:

default_function()

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

inline

Definition at line 4365 of file CLI11.hpp.

                                                                   {
        default_function_ = func;
        return this;
    }

default_str()

Option * CLI::Option::default_str ( std::string val )

inline

Definition at line 4379 of file CLI11.hpp.

                                       {
        default_str_ = std::move(val);
        return this;
    }

Here is the caller graph for this function:

default_val()

template<typename X >

Option * CLI::Option::default_val ( const X & val )

inline

Set the default value and validate the results and run the callback if appropriate to set the value into the bound value only available for types that can be converted to a string

Definition at line 4386 of file CLI11.hpp.

                                                            {
        std::string val_str = detail::to_string(val);
        auto old_option_state = current_option_state_;
        results_t old_results{std::move(results_)};
        results_.clear();
        try {
            add_result(val_str);
            if(run_callback_for_default_) {
                run_callback(); // run callback sets the state we need to reset it again
                current_option_state_ = option_state::parsing;
            } else {
                _validate_results(results_);
                current_option_state_ = old_option_state;
            }
        } catch(const CLI::Error &) {
            // this should be done
            results_ = std::move(old_results);
            current_option_state_ = old_option_state;
            throw;
        }
        results_ = std::move(old_results);
        default_str_ = std::move(val_str);
        return this;
    }

Here is the call graph for this function:

description()

Option * CLI::Option::description ( std::string option_description )

inline

Definition at line 4018 of file CLI11.hpp.

                                                      {
        description_ = std::move(option_description);
        return this;
    }

Here is the caller graph for this function:

disable_flag_override()

Option * CLI::Option::disable_flag_override ( bool value = true )

inline

Definition at line 3946 of file CLI11.hpp.

                                                     {
        disable_flag_override_ = value;
        return this;
    }

each()

Option * CLI::Option::each ( const std::function< void(std::string)> & func )

inline

Definition at line 3769 of file CLI11.hpp.

                                                           {
        validators_.emplace_back(
            [func](std::string &inout) {
                func(inout);
                return std::string{};
            },
            std::string{});
        return this;
    }

empty()

bool CLI::Option::empty ( ) const

inline

Definition at line 3652 of file CLI11.hpp.

{ return results_.empty(); }

Here is the caller graph for this function:

envname()

Option * CLI::Option::envname ( std::string name )

inline

Definition at line 3877 of file CLI11.hpp.

                                    {
        envname_ = std::move(name);
        return this;
    }

excludes() [1/3]

template<typename A , typename B , typename... ARG>

Option * CLI::Option::excludes ( A opt, B opt1, ARG... args )

inline

Definition at line 3860 of file CLI11.hpp.

                                                                                                    {
        excludes(opt);
        return excludes(opt1, args...);
    }

Here is the call graph for this function:

excludes() [2/3]

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

inline

Definition at line 3835 of file CLI11.hpp.

                                  {
        if(opt == this) {
            throw(IncorrectConstruction("and option cannot exclude itself"));
        }
        excludes_.insert(opt);
 
        // Help text should be symmetric - excluding a should exclude b
        opt->excludes_.insert(this);
 
        // Ignoring the insert return value, excluding twice is now allowed.
        // (Mostly to allow both directions to be excluded by user, even though the library does it for you.)
 
        return this;
    }

Here is the caller graph for this function:

excludes() [3/3]

template<typename T = App>

Option * CLI::Option::excludes ( std::string opt_name )

inline

Definition at line 3851 of file CLI11.hpp.

                                                                     {
        auto opt = dynamic_cast<T *>(parent_)->get_option_no_throw(opt_name);
        if(opt == nullptr) {
            throw IncorrectConstruction::MissingOption(opt_name);
        }
        return excludes(opt);
    }

Here is the call graph for this function:

expected() [1/2]

Option * CLI::Option::expected ( int value )

inline

Definition at line 3668 of file CLI11.hpp.

                                {
        if(value < 0) {
            expected_min_ = -value;
            if(expected_max_ < expected_min_) {
                expected_max_ = expected_min_;
            }
            allow_extra_args_ = true;
            flag_like_ = false;
        } else if(value == detail::expected_max_vector_size) {
            expected_min_ = 1;
            expected_max_ = detail::expected_max_vector_size;
            allow_extra_args_ = true;
            flag_like_ = false;
        } else {
            expected_min_ = value;
            expected_max_ = value;
            flag_like_ = (expected_min_ == 0);
        }
        return this;
    }

Here is the caller graph for this function:

expected() [2/2]

Option * CLI::Option::expected ( int value_min, int value_max )

inline

Definition at line 3690 of file CLI11.hpp.

                                                   {
        if(value_min < 0) {
            value_min = -value_min;
        }
 
        if(value_max < 0) {
            value_max = detail::expected_max_vector_size;
        }
        if(value_max < value_min) {
            expected_min_ = value_max;
            expected_max_ = value_min;
        } else {
            expected_max_ = value_max;
            expected_min_ = value_min;
        }
 
        return this;
    }

get_allow_extra_args()

bool CLI::Option::get_allow_extra_args ( ) const

inline

Definition at line 3715 of file CLI11.hpp.

{ return allow_extra_args_; }

Here is the caller graph for this function:

get_callback()

callback_t CLI::Option::get_callback ( ) const

inline

Definition at line 3975 of file CLI11.hpp.

{ return callback_; }

get_callback_run()

bool CLI::Option::get_callback_run ( ) const

inline

Definition at line 4307 of file CLI11.hpp.

{ return (current_option_state_ == option_state::callback_run); }

Here is the caller graph for this function:

get_default_str()

std::string CLI::Option::get_default_str ( ) const

inline

Definition at line 3972 of file CLI11.hpp.

{ return default_str_; }

Here is the caller graph for this function:

get_description()

const std::string & CLI::Option::get_description ( ) const

inline

Definition at line 4015 of file CLI11.hpp.

{ return description_; }

Here is the caller graph for this function:

get_envname()

std::string CLI::Option::get_envname ( ) const

inline

Definition at line 3963 of file CLI11.hpp.

{ return envname_; }

Here is the caller graph for this function:

get_excludes()

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

inline

Definition at line 3969 of file CLI11.hpp.

{ return excludes_; }

Here is the caller graph for this function:

get_expected()

int CLI::Option::get_expected ( ) const

inline

Definition at line 3987 of file CLI11.hpp.

{ return expected_min_; }

Here is the caller graph for this function:

get_expected_max()

int CLI::Option::get_expected_max ( ) const

inline

Definition at line 3992 of file CLI11.hpp.

{ return expected_max_; }

Here is the caller graph for this function:

get_expected_min()

int CLI::Option::get_expected_min ( ) const

inline

Definition at line 3990 of file CLI11.hpp.

{ return expected_min_; }

Here is the caller graph for this function:

get_flag_value()

std::string CLI::Option::get_flag_value ( const std::string & name, std::string input_value ) const

inline

Get the value that goes for a flag, nominally gets the default value but allows for overrides if not disabled

Definition at line 4179 of file CLI11.hpp.

                                                                                 {
        static const std::string trueString{"true"};
        static const std::string falseString{"false"};
        static const std::string emptyString{"{}"};
        // check for disable flag override_
        if(disable_flag_override_) {
            if(!((input_value.empty()) || (input_value == emptyString))) {
                auto default_ind = detail::find_member(name, fnames_, ignore_case_, ignore_underscore_);
                if(default_ind >= 0) {
                    // We can static cast this to std::size_t because it is more than 0 in this block
                    if(default_flag_values_[static_cast<std::size_t>(default_ind)].second != input_value) {
                        throw(ArgumentMismatch::FlagOverride(name));
                    }
                } else {
                    if(input_value != trueString) {
                        throw(ArgumentMismatch::FlagOverride(name));
                    }
                }
            }
        }
        auto ind = detail::find_member(name, fnames_, ignore_case_, ignore_underscore_);
        if((input_value.empty()) || (input_value == emptyString)) {
            if(flag_like_) {
                return (ind < 0) ? trueString : default_flag_values_[static_cast<std::size_t>(ind)].second;
            } else {
                return (ind < 0) ? default_str_ : default_flag_values_[static_cast<std::size_t>(ind)].second;
            }
        }
        if(ind < 0) {
            return input_value;
        }
        if(default_flag_values_[static_cast<std::size_t>(ind)].second == falseString) {
            try {
                auto val = detail::to_flag_value(input_value);
                return (val == 1) ? falseString : (val == (-1) ? trueString : std::to_string(-val));
            } catch(const std::invalid_argument &) {
                return input_value;
            }
        } else {
            return input_value;
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

get_fnames()

const std::vector< std::string > & CLI::Option::get_fnames ( ) const

inline

Definition at line 3984 of file CLI11.hpp.

{ return fnames_; }

get_items_expected()

int CLI::Option::get_items_expected ( ) const

inline

Definition at line 4003 of file CLI11.hpp.

{ return get_items_expected_min(); }

Here is the call graph for this function:

Here is the caller graph for this function:

get_items_expected_max()

int CLI::Option::get_items_expected_max ( ) const

inline

Definition at line 3998 of file CLI11.hpp.

                                       {
        int t = type_size_max_;
        return detail::checked_multiply(t, expected_max_) ? t : detail::expected_max_vector_size;
    }

Here is the call graph for this function:

get_items_expected_min()

int CLI::Option::get_items_expected_min ( ) const

inline

Definition at line 3995 of file CLI11.hpp.

{ return type_size_min_ * expected_min_; }

Here is the caller graph for this function:

get_lnames()

const std::vector< std::string > & CLI::Option::get_lnames ( ) const

inline

Definition at line 3978 of file CLI11.hpp.

{ return lnames_; }

Here is the caller graph for this function:

get_name()

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

inline

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

Definition at line 4031 of file CLI11.hpp.

                                 {
        if(get_group().empty())
            return {}; // Hidden
 
        if(all_options) {
 
            std::vector<std::string> name_list;
 
            if((positional && (!pname_.empty())) || (snames_.empty() && lnames_.empty())) {
                name_list.push_back(pname_);
            }
            if((get_items_expected() == 0) && (!fnames_.empty())) {
                for(const std::string &sname : snames_) {
                    name_list.push_back("-" + sname);
                    if(check_fname(sname)) {
                        name_list.back() += "{" + get_flag_value(sname, "") + "}";
                    }
                }
 
                for(const std::string &lname : lnames_) {
                    name_list.push_back("--" + lname);
                    if(check_fname(lname)) {
                        name_list.back() += "{" + get_flag_value(lname, "") + "}";
                    }
                }
            } else {
                for(const std::string &sname : snames_)
                    name_list.push_back("-" + sname);
 
                for(const std::string &lname : lnames_)
                    name_list.push_back("--" + lname);
            }
 
            return detail::join(name_list);
        }
 
        // This returns the positional name no matter what
        if(positional)
            return pname_;
 
        // Prefer long name
        if(!lnames_.empty())
            return std::string(2, '-') + lnames_[0];
 
        // Or short name if no long name
        if(!snames_.empty())
            return std::string(1, '-') + snames_[0];
 
        // If positional is the only name, it's okay to use that
        return pname_;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

get_needs()

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

inline

Definition at line 3966 of file CLI11.hpp.

{ return needs_; }

Here is the caller graph for this function:

get_positional()

bool CLI::Option::get_positional ( ) const

inline

Definition at line 4006 of file CLI11.hpp.

{ return pname_.length() > 0; }

Here is the caller graph for this function:

get_run_callback_for_default()

bool CLI::Option::get_run_callback_for_default ( ) const

inline

Definition at line 3724 of file CLI11.hpp.

{ return run_callback_for_default_; }

get_snames()

const std::vector< std::string > & CLI::Option::get_snames ( ) const

inline

Definition at line 3981 of file CLI11.hpp.

{ return snames_; }

get_type_name()

std::string CLI::Option::get_type_name ( ) const

inline

Definition at line 4412 of file CLI11.hpp.

                                    {
        std::string full_type_name = type_name_();
        if(!validators_.empty()) {
            for(auto &Validator : validators_) {
                std::string vtype = Validator.get_description();
                if(!vtype.empty()) {
                    full_type_name += ":" + vtype;
                }
            }
        }
        return full_type_name;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

get_type_size()

int CLI::Option::get_type_size ( ) const

inline

Definition at line 3955 of file CLI11.hpp.

{ return type_size_min_; }

Here is the caller graph for this function:

get_type_size_max()

int CLI::Option::get_type_size_max ( ) const

inline

Definition at line 3960 of file CLI11.hpp.

{ return type_size_max_; }

Here is the caller graph for this function:

get_type_size_min()

int CLI::Option::get_type_size_min ( ) const

inline

Definition at line 3958 of file CLI11.hpp.

{ return type_size_min_; }

Here is the caller graph for this function:

get_validator() [1/2]

Validator * CLI::Option::get_validator ( const std::string & Validator_name = "" )

inline

Definition at line 3779 of file CLI11.hpp.

                                                                   {
        for(auto &Validator : validators_) {
            if(Validator_name == Validator.get_name()) {
                return &Validator;
            }
        }
        if((Validator_name.empty()) && (!validators_.empty())) {
            return &(validators_.front());
        }
        throw OptionNotFound(std::string{"Validator "} + Validator_name + " Not Found");
    }

Here is the call graph for this function:

get_validator() [2/2]

Validator * CLI::Option::get_validator ( int index )

inline

Definition at line 3792 of file CLI11.hpp.

                                        {
        // This is an signed int so that it is not equivalent to a pointer.
        if(index >= 0 && index < static_cast<int>(validators_.size())) {
            return &(validators_[static_cast<decltype(validators_)::size_type>(index)]);
        }
        throw OptionNotFound("Validator index is not valid");
    }

has_description()

bool CLI::Option::has_description ( ) const

inline

Definition at line 4012 of file CLI11.hpp.

{ return description_.length() > 0; }

Here is the caller graph for this function:

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.

Definition at line 3886 of file CLI11.hpp.

                                                                       {
        if(!ignore_case_ && value) {
            ignore_case_ = value;
            auto *parent = dynamic_cast<T *>(parent_);
            for(const Option_p &opt : parent->options_) {
                if(opt.get() == this) {
                    continue;
                }
                auto &omatch = opt->matching_name(*this);
                if(!omatch.empty()) {
                    ignore_case_ = false;
                    throw OptionAlreadyAdded("adding ignore case caused a name conflict with " + omatch);
                }
            }
        } else {
            ignore_case_ = value;
        }
        return this;
    }

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.

Definition at line 3910 of file CLI11.hpp.

                                                                             {
 
        if(!ignore_underscore_ && value) {
            ignore_underscore_ = value;
            auto *parent = dynamic_cast<T *>(parent_);
            for(const Option_p &opt : parent->options_) {
                if(opt.get() == this) {
                    continue;
                }
                auto &omatch = opt->matching_name(*this);
                if(!omatch.empty()) {
                    ignore_underscore_ = false;
                    throw OptionAlreadyAdded("adding ignore underscore caused a name conflict with " + omatch);
                }
            }
        } else {
            ignore_underscore_ = value;
        }
        return this;
    }

matching_name()

const std::string & CLI::Option::matching_name ( const Option & other ) const

inline

Definition at line 4116 of file CLI11.hpp.

                                                              {
        static const std::string estring;
        for(const std::string &sname : snames_)
            if(other.check_sname(sname))
                return sname;
        for(const std::string &lname : lnames_)
            if(other.check_lname(lname))
                return lname;
 
        if(ignore_case_ ||
           ignore_underscore_) { // We need to do the inverse, in case we are ignore_case or ignore underscore
            for(const std::string &sname : other.snames_)
                if(check_sname(sname))
                    return sname;
            for(const std::string &lname : other.lnames_)
                if(check_lname(lname))
                    return lname;
        }
        return estring;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

multi_option_policy()

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

inline

Definition at line 3932 of file CLI11.hpp.

                                                                                  {
        if(value != multi_option_policy_) {
            if(multi_option_policy_ == MultiOptionPolicy::Throw && expected_max_ == detail::expected_max_vector_size &&
               expected_min_ > 1) { // this bizarre condition is to maintain backwards compatibility
                                    // with the previous behavior of expected_ with vectors
                expected_max_ = expected_min_;
            }
            multi_option_policy_ = value;
            current_option_state_ = option_state::parsing;
        }
        return this;
    }

Here is the caller graph for this function:

needs() [1/3]

template<typename A , typename B , typename... ARG>

Option * CLI::Option::needs ( A opt, B opt1, ARG... args )

inline

Definition at line 3818 of file CLI11.hpp.

                                                                                                 {
        needs(opt);
        return needs(opt1, args...);
    }

Here is the call graph for this function:

needs() [2/3]

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

inline

Definition at line 3801 of file CLI11.hpp.

                               {
        if(opt != this) {
            needs_.insert(opt);
        }
        return this;
    }

Here is the caller graph for this function:

needs() [3/3]

template<typename T = App>

Option * CLI::Option::needs ( std::string opt_name )

inline

Definition at line 3809 of file CLI11.hpp.

                                                                  {
        auto opt = dynamic_cast<T *>(parent_)->get_option_no_throw(opt_name);
        if(opt == nullptr) {
            throw IncorrectConstruction::MissingOption(opt_name);
        }
        return needs(opt);
    }

Here is the call graph for this function:

nonpositional()

bool CLI::Option::nonpositional ( ) const

inline

Definition at line 4009 of file CLI11.hpp.

{ return (snames_.size() + lnames_.size()) > 0; }

Here is the caller graph for this function:

operator bool()

CLI::Option::operator bool ( ) const

inlineexplicit

Definition at line 3655 of file CLI11.hpp.

{ return !empty(); }

Here is the call graph for this function:

operator=()

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

delete

operator==()

bool CLI::Option::operator== ( const Option & other ) const

inline

Definition at line 4137 of file CLI11.hpp.

{ return !matching_name(other).empty(); }

Here is the call graph for this function:

reduced_results()

results_t CLI::Option::reduced_results ( ) const

inline

Definition at line 4249 of file CLI11.hpp.

                                      {
        results_t res = proc_results_.empty() ? results_ : proc_results_;
        if(current_option_state_ < option_state::reduced) {
            if(current_option_state_ == option_state::parsing) {
                res = results_;
                _validate_results(res);
            }
            if(!res.empty()) {
                results_t extra;
                _reduce_results(extra, res);
                if(!extra.empty()) {
                    res = std::move(extra);
                }
            }
        }
        return res;
    }

Here is the caller graph for this function:

remove_excludes()

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

inline

Definition at line 3866 of file CLI11.hpp.

                                      {
        auto iterator = std::find(std::begin(excludes_), std::end(excludes_), opt);
 
        if(iterator == std::end(excludes_)) {
            return false;
        }
        excludes_.erase(iterator);
        return true;
    }

remove_needs()

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

inline

Definition at line 3824 of file CLI11.hpp.

                                   {
        auto iterator = std::find(std::begin(needs_), std::end(needs_), opt);
 
        if(iterator == std::end(needs_)) {
            return false;
        }
        needs_.erase(iterator);
        return true;
    }

results() [1/2]

results_t CLI::Option::results ( ) const

inline

Definition at line 4246 of file CLI11.hpp.

{ return results_; }

Here is the caller graph for this function:

results() [2/2]

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

void CLI::Option::results ( T & output ) const

inline

Definition at line 4269 of file CLI11.hpp.

                                  {
        bool retval;
        if(current_option_state_ >= option_state::reduced || (results_.size() == 1 && validators_.empty())) {
            const results_t &res = (proc_results_.empty()) ? results_ : proc_results_;
            retval = detail::lexical_conversion<T, T>(res, output);
        } else {
            results_t res;
            if(results_.empty()) {
                if(!default_str_.empty()) {
                    //_add_results takes an rvalue only
                    _add_result(std::string(default_str_), res);
                    _validate_results(res);
                    results_t extra;
                    _reduce_results(extra, res);
                    if(!extra.empty()) {
                        res = std::move(extra);
                    }
                } else {
                    res.emplace_back();
                }
            } else {
                res = reduced_results();
            }
            retval = detail::lexical_conversion<T, T>(res, output);
        }
        if(!retval) {
            throw ConversionError(get_name(), results_);
        }
    }

Here is the call graph for this function:

run_callback()

void CLI::Option::run_callback ( )

inline

Definition at line 4091 of file CLI11.hpp.

                        {
 
        if(current_option_state_ == option_state::parsing) {
            _validate_results(results_);
            current_option_state_ = option_state::validated;
        }
 
        if(current_option_state_ < option_state::reduced) {
            _reduce_results(proc_results_, results_);
            current_option_state_ = option_state::reduced;
        }
        if(current_option_state_ >= option_state::reduced) {
            current_option_state_ = option_state::callback_run;
            if(!(callback_)) {
                return;
            }
            const results_t &send_results = proc_results_.empty() ? results_ : proc_results_;
            bool local_result = callback_(send_results);
 
            if(!local_result)
                throw ConversionError(get_name(), results_);
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

run_callback_for_default()

Option * CLI::Option::run_callback_for_default ( bool value = true )

inline

Set the value of run_callback_for_default which controls whether the callback function should be called to set the default This is controlled automatically but could be manipulated by the user.

Definition at line 3719 of file CLI11.hpp.

                                                        {
        run_callback_for_default_ = value;
        return this;
    }

Here is the caller graph for this function:

transform() [1/2]

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

inline

Definition at line 3753 of file CLI11.hpp.

                                                     {
        validators_.insert(validators_.begin(),
                           Validator(
                               [func](std::string &val) {
                                   val = func(val);
                                   return std::string{};
                               },
                               std::move(transform_description),
                               std::move(transform_name)));
 
        return this;
    }

transform() [2/2]

Option * CLI::Option::transform ( Validator Validator, const std::string & Validator_name = "" )

inline

Definition at line 3745 of file CLI11.hpp.

                                                                                 {
        validators_.insert(validators_.begin(), std::move(Validator));
        if(!Validator_name.empty())
            validators_.front().name(Validator_name);
        return this;
    }

type_name()

Option * CLI::Option::type_name ( std::string typeval )

inline

Definition at line 4320 of file CLI11.hpp.

                                         {
        type_name_fn([typeval]() { return typeval; });
        return this;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

type_name_fn()

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

inline

Definition at line 4314 of file CLI11.hpp.

                                                           {
        type_name_ = std::move(typefun);
        return this;
    }

Here is the caller graph for this function:

type_size() [1/2]

Option * CLI::Option::type_size ( int option_type_size )

inline

Definition at line 4326 of file CLI11.hpp.

                                            {
        if(option_type_size < 0) {
            // this section is included for backwards compatibility
            type_size_max_ = -option_type_size;
            type_size_min_ = -option_type_size;
            expected_max_ = detail::expected_max_vector_size;
        } else {
            type_size_max_ = option_type_size;
            if(type_size_max_ < detail::expected_max_vector_size) {
                type_size_min_ = option_type_size;
            }
            if(type_size_max_ == 0)
                required_ = false;
        }
        return this;
    }

Here is the caller graph for this function:

type_size() [2/2]

Option * CLI::Option::type_size ( int option_type_size_min, int option_type_size_max )

inline

Definition at line 4343 of file CLI11.hpp.

                                                                          {
        if(option_type_size_min < 0 || option_type_size_max < 0) {
            // this section is included for backwards compatibility
            expected_max_ = detail::expected_max_vector_size;
            option_type_size_min = (std::abs)(option_type_size_min);
            option_type_size_max = (std::abs)(option_type_size_max);
        }
 
        if(option_type_size_min > option_type_size_max) {
            type_size_max_ = option_type_size_min;
            type_size_min_ = option_type_size_max;
        } else {
            type_size_min_ = option_type_size_min;
            type_size_max_ = option_type_size_max;
        }
        if(type_size_max_ == 0) {
            required_ = false;
        }
        return this;
    }

Member Data Documentation

allow_extra_args_

bool CLI::Option::allow_extra_args_ {false}

protected

Definition at line 3628 of file CLI11.hpp.

{false};

callback_

callback_t CLI::Option::callback_ {}

protected

Definition at line 3608 of file CLI11.hpp.

{};

current_option_state_

option_state CLI::Option::current_option_state_ {option_state::parsing}

protected

Definition at line 3626 of file CLI11.hpp.

{option_state::parsing};

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

Definition at line 3547 of file CLI11.hpp.

{};

default_function_

std::function<std::string()> CLI::Option::default_function_ {}

protected

Definition at line 3574 of file CLI11.hpp.

{};

default_str_

std::string CLI::Option::default_str_ {}

protected

Definition at line 3566 of file CLI11.hpp.

{};

description_

std::string CLI::Option::description_ {}

protected

Definition at line 3563 of file CLI11.hpp.

{};

envname_

std::string CLI::Option::envname_ {}

protected

Definition at line 3556 of file CLI11.hpp.

{};

excludes_

std::set<Option *> CLI::Option::excludes_ {}

protected

Definition at line 3598 of file CLI11.hpp.

{};

expected_max_

int CLI::Option::expected_max_ {1}

protected

Definition at line 3589 of file CLI11.hpp.

{1};

expected_min_

int CLI::Option::expected_min_ {1}

protected

Definition at line 3587 of file CLI11.hpp.

{1};

flag_like_

bool CLI::Option::flag_like_ {false}

protected

Definition at line 3630 of file CLI11.hpp.

{false};

fnames_

std::vector<std::string> CLI::Option::fnames_ {}

protected

Definition at line 3550 of file CLI11.hpp.

{};

lnames_

std::vector<std::string> CLI::Option::lnames_ {}

protected

Definition at line 3543 of file CLI11.hpp.

{};

needs_

std::set<Option *> CLI::Option::needs_ {}

protected

Definition at line 3595 of file CLI11.hpp.

{};

parent_

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

protected

Definition at line 3605 of file CLI11.hpp.

{nullptr};

pname_

std::string CLI::Option::pname_ {}

protected

Definition at line 3553 of file CLI11.hpp.

{};

proc_results_

results_t CLI::Option::proc_results_ {}

protected

Definition at line 3617 of file CLI11.hpp.

{};

results_

results_t CLI::Option::results_ {}

protected

Definition at line 3615 of file CLI11.hpp.

{};

run_callback_for_default_

bool CLI::Option::run_callback_for_default_ {false}

protected

Definition at line 3632 of file CLI11.hpp.

{false};

snames_

std::vector<std::string> CLI::Option::snames_ {}

protected

Definition at line 3540 of file CLI11.hpp.

{};

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.

Definition at line 3571 of file CLI11.hpp.

{[]() { return std::string(); }};

type_size_max_

int CLI::Option::type_size_max_ {1}

protected

The number of arguments that make up one option. max is the nominal type size, min is the minimum number of strings

Definition at line 3582 of file CLI11.hpp.

{1};

type_size_min_

int CLI::Option::type_size_min_ {1}

protected

Definition at line 3584 of file CLI11.hpp.

{1};

validators_

std::vector<Validator> CLI::Option::validators_ {}

protected

Definition at line 3592 of file CLI11.hpp.

{};

---

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

• programs/clio/CLI11.hpp