Option.hpp

Go to the documentation of this file.

// Copyright (c) 2017-2025, University of Cincinnati, developed by Henry Schreiner
// under NSF AWARD 1414736 and by the respective contributors.
// All rights reserved.
//
// SPDX-License-Identifier: BSD-3-Clause
 
#pragma once
 
// IWYU pragma: private, include "CLI/CLI.hpp"
 
// [CLI11:public_includes:set]
#include <algorithm>
#include <functional>
#include <memory>
#include <set>
#include <string>
#include <tuple>
#include <utility>
#include <vector>
// [CLI11:public_includes:end]
 
#include "Error.hpp"
#include "Macros.hpp"
#include "Split.hpp"
#include "StringTools.hpp"
#include "Validators.hpp"
 
namespace CLI {
// [CLI11:option_hpp:verbatim]
 
using results_t = std::vector<std::string>;
using callback_t = std::function<bool(const results_t &)>;
 
class Option;
class App;
class ConfigBase;
 
using Option_p = std::unique_ptr<Option>;
using Validator_p = std::shared_ptr<Validator>;

enum class MultiOptionPolicy : char {
    Throw,      
    TakeLast,   
    TakeFirst,  
    Join,       
    TakeAll,    
    Sum,        
    Reverse,    
};

enum class CallbackPriority : std::uint8_t {
    FirstPreHelp = 0,
    First = 1,
    PreRequirementsCheckPreHelp = 2,
    PreRequirementsCheck = 3,
    NormalPreHelp = 4,
    Normal = 5,
    LastPreHelp = 6,
    Last = 7
};  // namespace CLI

template <typename CRTP> class OptionBase {
    friend App;
    friend ConfigBase;
 
  protected:
    std::string group_ = std::string("OPTIONS");

    bool required_{false};

    bool ignore_case_{false};

    bool ignore_underscore_{false};

    bool configurable_{true};

    bool disable_flag_override_{false};

    char delimiter_{'\0'};

    bool always_capture_default_{false};

    MultiOptionPolicy multi_option_policy_{MultiOptionPolicy::Throw};

    CallbackPriority callback_priority_{CallbackPriority::Normal};

    template <typename T> void copy_to(T *other) const;
 
  public:
    // setters

    CRTP *group(const std::string &name) {
        if(!detail::valid_alias_name_string(name)) {
            throw IncorrectConstruction("Group names may not contain newlines or null characters");
        }
        group_ = name;
        return static_cast<CRTP *>(this);
    }

    CRTP *required(bool value = true) {
        required_ = value;
        return static_cast<CRTP *>(this);
    }

    CRTP *mandatory(bool value = true) { return required(value); }
 
    CRTP *always_capture_default(bool value = true) {
        always_capture_default_ = value;
        return static_cast<CRTP *>(this);
    }
 
    // Getters

    CLI11_NODISCARD const std::string &get_group() const { return group_; }

    CLI11_NODISCARD bool get_required() const { return required_; }

    CLI11_NODISCARD bool get_ignore_case() const { return ignore_case_; }

    CLI11_NODISCARD bool get_ignore_underscore() const { return ignore_underscore_; }

    CLI11_NODISCARD bool get_configurable() const { return configurable_; }

    CLI11_NODISCARD bool get_disable_flag_override() const { return disable_flag_override_; }

    CLI11_NODISCARD char get_delimiter() const { return delimiter_; }

    CLI11_NODISCARD bool get_always_capture_default() const { return always_capture_default_; }

    CLI11_NODISCARD MultiOptionPolicy get_multi_option_policy() const { return multi_option_policy_; }

    CLI11_NODISCARD CallbackPriority get_callback_priority() const { return callback_priority_; }
 
    // Shortcuts for multi option policy

    CRTP *take_last() {
        auto *self = static_cast<CRTP *>(this);
        self->multi_option_policy(MultiOptionPolicy::TakeLast);
        return self;
    }

    CRTP *take_first() {
        auto *self = static_cast<CRTP *>(this);
        self->multi_option_policy(MultiOptionPolicy::TakeFirst);
        return self;
    }

    CRTP *take_all() {
        auto self = static_cast<CRTP *>(this);
        self->multi_option_policy(MultiOptionPolicy::TakeAll);
        return self;
    }

    CRTP *join() {
        auto *self = static_cast<CRTP *>(this);
        self->multi_option_policy(MultiOptionPolicy::Join);
        return self;
    }

    CRTP *join(char delim) {
        auto self = static_cast<CRTP *>(this);
        self->delimiter_ = delim;
        self->multi_option_policy(MultiOptionPolicy::Join);
        return self;
    }

    CRTP *configurable(bool value = true) {
        configurable_ = value;
        return static_cast<CRTP *>(this);
    }

    CRTP *delimiter(char value = '\0') {
        delimiter_ = value;
        return static_cast<CRTP *>(this);
    }
};

class OptionDefaults : public OptionBase<OptionDefaults> {
  public:
    OptionDefaults() = default;
 
    // Methods here need a different implementation if they are Option vs. OptionDefault

    OptionDefaults *callback_priority(CallbackPriority value = CallbackPriority::Normal) {
        callback_priority_ = value;
        return this;
    }

    OptionDefaults *multi_option_policy(MultiOptionPolicy value = MultiOptionPolicy::Throw) {
        multi_option_policy_ = value;
        return this;
    }

    OptionDefaults *ignore_case(bool value = true) {
        ignore_case_ = value;
        return this;
    }

    OptionDefaults *ignore_underscore(bool value = true) {
        ignore_underscore_ = value;
        return this;
    }

    OptionDefaults *disable_flag_override(bool value = true) {
        disable_flag_override_ = value;
        return this;
    }

    OptionDefaults *delimiter(char value = '\0') {
        delimiter_ = value;
        return this;
    }
};
 
class Option : public OptionBase<Option> {
    friend App;
    friend ConfigBase;
 
  protected:

    std::vector<std::string> snames_{};

    std::vector<std::string> lnames_{};

    std::vector<std::pair<std::string, std::string>> default_flag_values_{};

    std::vector<std::string> fnames_{};

    std::string pname_{};

    std::string envname_{};


    std::string description_{};

    std::string default_str_{};

    std::string option_text_{};

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

    std::function<std::string()> default_function_{};


    int type_size_max_{1};
    int type_size_min_{1};

    int expected_min_{1};
    int expected_max_{1};

    std::vector<Validator_p> validators_{};

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

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


    App *parent_{nullptr};

    callback_t callback_{};


    results_t results_{};
    mutable results_t proc_results_{};
    enum class option_state : char {
        parsing = 0,       
        validated = 2,     
        reduced = 4,       
        callback_run = 6,  
    };

    option_state current_option_state_{option_state::parsing};
    bool allow_extra_args_{false};
    bool flag_like_{false};
    bool run_callback_for_default_{false};
    bool inject_separator_{false};
    bool trigger_on_result_{false};
    bool force_callback_{false};

    Option(std::string option_name,
           std::string option_description,
           callback_t callback,
           App *parent,
           bool allow_non_standard = false)
        : description_(std::move(option_description)), parent_(parent), callback_(std::move(callback)) {
        std::tie(snames_, lnames_, pname_) = detail::get_names(detail::split_names(option_name), allow_non_standard);
    }
 
  public:
 
    Option(const Option &) = delete;
    Option &operator=(const Option &) = delete;

    CLI11_NODISCARD std::size_t count() const { return results_.size(); }

    CLI11_NODISCARD bool empty() const { return results_.empty(); }

    explicit operator bool() const { return !empty() || force_callback_; }

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


    Option *expected(int value);

    Option *expected(int value_min, int value_max);

    Option *allow_extra_args(bool value = true) {
        allow_extra_args_ = value;
        return this;
    }

    CLI11_NODISCARD bool get_allow_extra_args() const { return allow_extra_args_; }
    Option *trigger_on_parse(bool value = true) {
        trigger_on_result_ = value;
        return this;
    }

    CLI11_NODISCARD bool get_trigger_on_parse() const { return trigger_on_result_; }

    Option *force_callback(bool value = true) {
        force_callback_ = value;
        return this;
    }

    CLI11_NODISCARD bool get_force_callback() const { return force_callback_; }

    Option *run_callback_for_default(bool value = true) {
        run_callback_for_default_ = value;
        return this;
    }

    CLI11_NODISCARD bool get_run_callback_for_default() const { return run_callback_for_default_; }

    Option *callback_priority(CallbackPriority value = CallbackPriority::Normal) {
        callback_priority_ = value;
        return this;
    }

    Option *check(Validator_p validator);

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

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

    Option *transform(Validator_p validator);

    Option *transform(Validator validator, const std::string &transform_name = "");

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

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

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

    Validator *get_validator(int index);

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

    template <typename T = App> Option *needs(std::string opt_name) {
        auto opt = static_cast<T *>(parent_)->get_option_no_throw(opt_name);
        if(opt == nullptr) {
            throw IncorrectConstruction::MissingOption(opt_name);
        }
        return needs(opt);
    }

    template <typename A, typename B, typename... ARG> Option *needs(A opt, B opt1, ARG... args) {
        needs(opt);
        return needs(opt1, args...);  // NOLINT(readability-suspicious-call-argument)
    }

    bool remove_needs(Option *opt);

    Option *excludes(Option *opt);

    template <typename T = App> Option *excludes(std::string opt_name) {
        auto opt = static_cast<T *>(parent_)->get_option_no_throw(opt_name);
        if(opt == nullptr) {
            throw IncorrectConstruction::MissingOption(opt_name);
        }
        return excludes(opt);
    }

    template <typename A, typename B, typename... ARG> Option *excludes(A opt, B opt1, ARG... args) {
        excludes(opt);
        return excludes(opt1, args...);
    }

    bool remove_excludes(Option *opt);

    Option *envname(std::string name) {
        envname_ = std::move(name);
        return this;
    }

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

    Option *disable_flag_override(bool value = true) {
        disable_flag_override_ = value;
        return this;
    }


    CLI11_NODISCARD int get_type_size() const { return type_size_min_; }

    CLI11_NODISCARD int get_type_size_min() const { return type_size_min_; }
    CLI11_NODISCARD int get_type_size_max() const { return type_size_max_; }

    CLI11_NODISCARD bool get_inject_separator() const { return inject_separator_; }

    CLI11_NODISCARD std::string get_envname() const { return envname_; }

    CLI11_NODISCARD std::set<Option *> get_needs() const { return needs_; }

    CLI11_NODISCARD std::set<Option *> get_excludes() const { return excludes_; }

    CLI11_NODISCARD std::string get_default_str() const { return default_str_; }

    CLI11_NODISCARD callback_t get_callback() const { return callback_; }

    CLI11_NODISCARD const std::vector<std::string> &get_lnames() const { return lnames_; }

    CLI11_NODISCARD const std::vector<std::string> &get_snames() const { return snames_; }

    CLI11_NODISCARD const std::vector<std::string> &get_fnames() const { return fnames_; }
    CLI11_NODISCARD const std::string &get_single_name() const {
        if(!lnames_.empty()) {
            return lnames_[0];
        }
        if(!snames_.empty()) {
            return snames_[0];
        }
        if(!pname_.empty()) {
            return pname_;
        }
        return envname_;
    }

    CLI11_NODISCARD int get_expected() const { return expected_min_; }

    CLI11_NODISCARD int get_expected_min() const { return expected_min_; }
    CLI11_NODISCARD int get_expected_max() const { return expected_max_; }

    CLI11_NODISCARD int get_items_expected_min() const { return type_size_min_ * expected_min_; }

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

    CLI11_NODISCARD int get_items_expected() const { return get_items_expected_min(); }

    CLI11_NODISCARD bool get_positional() const { return !pname_.empty(); }

    CLI11_NODISCARD bool nonpositional() const { return (!lnames_.empty() || !snames_.empty()); }

    CLI11_NODISCARD bool has_description() const { return !description_.empty(); }

    CLI11_NODISCARD const std::string &get_description() const { return description_; }

    Option *description(std::string option_description) {
        description_ = std::move(option_description);
        return this;
    }
 
    Option *option_text(std::string text) {
        option_text_ = std::move(text);
        return this;
    }
 
    CLI11_NODISCARD const std::string &get_option_text() const { return option_text_; }


    CLI11_NODISCARD std::string get_name(bool positional = false,  
                                         bool all_options = false  
    ) const;


    void run_callback();

    CLI11_NODISCARD const std::string &matching_name(const Option &other) const;

    bool operator==(const Option &other) const { return !matching_name(other).empty(); }

    CLI11_NODISCARD bool check_name(const std::string &name) const;

    CLI11_NODISCARD bool check_sname(std::string name) const {
        return (detail::find_member(std::move(name), snames_, ignore_case_) >= 0);
    }

    CLI11_NODISCARD bool check_lname(std::string name) const {
        return (detail::find_member(std::move(name), lnames_, ignore_case_, ignore_underscore_) >= 0);
    }

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

    CLI11_NODISCARD std::string get_flag_value(const std::string &name, std::string input_value) const;

    Option *add_result(std::string s);

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

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

    CLI11_NODISCARD const results_t &results() const { return results_; }

    CLI11_NODISCARD results_t reduced_results() const;

    template <typename T> void results(T &output) const {
        bool retval = false;
        if(current_option_state_ >= option_state::reduced || (results_.size() == 1 && validators_.empty())) {
            const results_t &res = (proc_results_.empty()) ? results_ : proc_results_;
            if(!res.empty()) {
                retval = detail::lexical_conversion<T, T>(res, output);
            } else {
                results_t res2;
                res2.emplace_back();
                proc_results_ = std::move(res2);
                retval = detail::lexical_conversion<T, T>(proc_results_, 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();
            }
            // store the results in a stable location if the output is a view
            proc_results_ = std::move(res);
            retval = detail::lexical_conversion<T, T>(proc_results_, output);
        }
        if(!retval) {
            throw ConversionError(get_name(), results_);
        }
    }

    template <typename T> CLI11_NODISCARD T as() const {
        T output;
        results(output);
        return output;
    }

    CLI11_NODISCARD bool get_callback_run() const { return (current_option_state_ == option_state::callback_run); }


    Option *type_name_fn(std::function<std::string()> typefun) {
        type_name_ = std::move(typefun);
        return this;
    }

    Option *type_name(std::string typeval) {
        type_name_fn([typeval]() { return typeval; });
        return this;
    }

    Option *type_size(int option_type_size);

    Option *type_size(int option_type_size_min, int option_type_size_max);

    void inject_separator(bool value = true) { inject_separator_ = value; }

    Option *default_function(const std::function<std::string()> &func) {
        default_function_ = func;
        return this;
    }

    Option *capture_default_str() {
        if(default_function_) {
            default_str_ = default_function_();
        }
        return this;
    }

    Option *default_str(std::string val) {
        default_str_ = std::move(val);
        return this;
    }

    template <typename X> Option *default_val(const X &val) {
        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 trigger_on_result_ is set the callback already ran
            if(run_callback_for_default_ && !trigger_on_result_) {
                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 ConversionError &err) {
            // this should be done
            results_ = std::move(old_results);
            current_option_state_ = old_option_state;
 
            throw ConversionError(
                get_name(), std::string("given default value(\"") + val_str + "\") produces an error : " + err.what());
        } catch(const CLI::Error &) {
            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;
    }

    CLI11_NODISCARD std::string get_type_name() const;
 
  private:
    void _validate_results(results_t &res) const;

    void _reduce_results(results_t &out, const results_t &original) const;
 
    // Run a result through the Validators
    std::string _validate(std::string &result, int index) const;

    int _add_result(std::string &&result, std::vector<std::string> &res) const;
};
 
// [CLI11:option_hpp:end]
}  // namespace CLI
 
#ifndef CLI11_COMPILE
#include "impl/Option_inl.hpp"  // IWYU pragma: export
#endif