Validators.hpp

Go to the documentation of this file.

// Copyright (c) 2017-2026, 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"
 
#include "Error.hpp"
#include "Macros.hpp"
#include "StringTools.hpp"
#include "TypeTools.hpp"
 
// [CLI11:public_includes:set]
#include <cmath>
#include <cstdint>
#include <functional>
#include <iostream>
#include <limits>
#include <memory>
#include <string>
#include <utility>
#include <vector>
// [CLI11:public_includes:end]
 
// [CLI11:validators_hpp_filesystem:verbatim]
 
#if defined CLI11_HAS_FILESYSTEM && CLI11_HAS_FILESYSTEM > 0
#include <filesystem>  // NOLINT(build/include)
#else
#include <sys/stat.h>
#include <sys/types.h>
#endif
 
// [CLI11:validators_hpp_filesystem:end]
 
namespace CLI {
// [CLI11:validators_hpp:verbatim]
 
class Option;



class Validator {
  protected:
    std::function<std::string()> desc_function_{[]() { return std::string{}; }};

    std::function<std::string(std::string &)> func_{[](std::string &) { return std::string{}; }};
    std::string name_{};
    int application_index_ = -1;
    bool active_{true};
    bool non_modifying_{false};
 
    Validator(std::string validator_desc, std::function<std::string(std::string &)> func)
        : desc_function_([validator_desc]() { return validator_desc; }), func_(std::move(func)) {}
 
  public:
    Validator() = default;
    explicit Validator(std::string validator_desc) : desc_function_([validator_desc]() { return validator_desc; }) {}
    Validator(std::function<std::string(std::string &)> op, std::string validator_desc, std::string validator_name = "")
        : desc_function_([validator_desc]() { return validator_desc; }), func_(std::move(op)),
          name_(std::move(validator_name)) {}

    Validator &operation(std::function<std::string(std::string &)> op) {
        func_ = std::move(op);
        return *this;
    }

    std::string operator()(std::string &str) const;

    std::string operator()(const std::string &str) const {
        std::string value = str;
        return (active_) ? func_(value) : std::string{};
    }

    Validator &description(std::string validator_desc) {
        desc_function_ = [validator_desc]() { return validator_desc; };
        return *this;
    }

    CLI11_NODISCARD Validator description(std::string validator_desc) const;

    CLI11_NODISCARD std::string get_description() const {
        if(active_) {
            return desc_function_();
        }
        return std::string{};
    }

    Validator &name(std::string validator_name) {
        name_ = std::move(validator_name);
        return *this;
    }

    CLI11_NODISCARD Validator name(std::string validator_name) const {
        Validator newval(*this);
        newval.name_ = std::move(validator_name);
        return newval;
    }

    CLI11_NODISCARD const std::string &get_name() const { return name_; }
    Validator &active(bool active_val = true) {
        active_ = active_val;
        return *this;
    }

    CLI11_NODISCARD Validator active(bool active_val = true) const {
        Validator newval(*this);
        newval.active_ = active_val;
        return newval;
    }

    Validator &non_modifying(bool no_modify = true) {
        non_modifying_ = no_modify;
        return *this;
    }

    Validator &application_index(int app_index) {
        application_index_ = app_index;
        return *this;
    }

    CLI11_NODISCARD Validator application_index(int app_index) const {
        Validator newval(*this);
        newval.application_index_ = app_index;
        return newval;
    }

    CLI11_NODISCARD int get_application_index() const { return application_index_; }
    CLI11_NODISCARD bool get_active() const { return active_; }

    CLI11_NODISCARD bool get_modifying() const { return !non_modifying_; }

    Validator operator&(const Validator &other) const;

    Validator operator|(const Validator &other) const;

    Validator operator!() const;
 
  private:
    void _merge_description(const Validator &val1, const Validator &val2, const std::string &merger);
};

using CustomValidator = Validator;
 
// The implementation of the built in validators is using the Validator class;
// the user is only expected to use the const (static) versions (since there's no setup).
// Therefore, this is in detail.
namespace detail {

enum class path_type : std::uint8_t { nonexistent, file, directory };

CLI11_INLINE path_type check_path(const char *file) noexcept;
 
// Static is not needed here, because global const implies static.

class ExistingFileValidator : public Validator {
  public:
    ExistingFileValidator();
};

class ExistingDirectoryValidator : public Validator {
  public:
    ExistingDirectoryValidator();
};

class ExistingPathValidator : public Validator {
  public:
    ExistingPathValidator();
};

class NonexistentPathValidator : public Validator {
  public:
    NonexistentPathValidator();
};
 
class EscapedStringTransformer : public Validator {
  public:
    EscapedStringTransformer();
};
 
}  // namespace detail

CLI11_MODULE_INLINE const detail::ExistingFileValidator ExistingFile;

CLI11_MODULE_INLINE const detail::ExistingDirectoryValidator ExistingDirectory;

CLI11_MODULE_INLINE const detail::ExistingPathValidator ExistingPath;

CLI11_MODULE_INLINE const detail::NonexistentPathValidator NonexistentPath;

CLI11_MODULE_INLINE const detail::EscapedStringTransformer EscapedString;

class FileOnDefaultPath : public Validator {
  public:
    explicit FileOnDefaultPath(std::string default_path, bool enableErrorReturn = true);
};

class Range : public Validator {
  public:
    template <typename T>
    Range(T min_val, T max_val, const std::string &validator_name = std::string{}) : Validator(validator_name) {
        if(validator_name.empty()) {
            std::stringstream out;
            out << detail::type_name<T>() << " in [" << min_val << " - " << max_val << "]";
            description(out.str());
        }
 
        func_ = [min_val, max_val](std::string &input) {
            using CLI::detail::lexical_cast;
            T val;
            bool converted = lexical_cast(input, val);
            if((!converted) || (val < min_val || val > max_val)) {
                std::stringstream out;
                out << "Value " << input << " not in range [";
                out << min_val << " - " << max_val << "]";
                return out.str();
            }
            return std::string{};
        };
    }

    template <typename T>
    explicit Range(T max_val, const std::string &validator_name = std::string{})
        : Range(static_cast<T>(0), max_val, validator_name) {}
};

CLI11_MODULE_INLINE const Range NonNegativeNumber((std::numeric_limits<double>::max)(), "NONNEGATIVE");

CLI11_MODULE_INLINE const
    Range PositiveNumber((std::numeric_limits<double>::min)(), (std::numeric_limits<double>::max)(), "POSITIVE");
 
namespace detail {
// the following suggestion was made by Nikita Ofitserov(@himikof)
// done in templates to prevent compiler warnings on negation of unsigned numbers

template <typename T>
inline typename std::enable_if<std::is_signed<T>::value, T>::type overflowCheck(const T &a, const T &b) {
    if((a > 0) == (b > 0)) {
        return ((std::numeric_limits<T>::max)() / (std::abs)(a) < (std::abs)(b));
    }
    return ((std::numeric_limits<T>::min)() / (std::abs)(a) > -(std::abs)(b));
}

template <typename T>
inline typename std::enable_if<!std::is_signed<T>::value, T>::type overflowCheck(const T &a, const T &b) {
    return ((std::numeric_limits<T>::max)() / a < b);
}

template <typename T> typename std::enable_if<std::is_integral<T>::value, bool>::type checked_multiply(T &a, T b) {
    if(a == 0 || b == 0 || a == 1 || b == 1) {
        a *= b;
        return true;
    }
    if(a == (std::numeric_limits<T>::min)() || b == (std::numeric_limits<T>::min)()) {
        return false;
    }
    if(overflowCheck(a, b)) {
        return false;
    }
    a *= b;
    return true;
}

template <typename T>
typename std::enable_if<std::is_floating_point<T>::value, bool>::type checked_multiply(T &a, T b) {
    T c = a * b;
    if(std::isinf(c) && !std::isinf(a) && !std::isinf(b)) {
        return false;
    }
    a = c;
    return true;
}

CLI11_INLINE std::pair<std::string, std::string> split_program_name(std::string commandline);
 
}  // namespace detail
 
// [CLI11:validators_hpp:end]
}  // namespace CLI
 
#ifndef CLI11_COMPILE
#include "impl/Validators_inl.hpp"  // IWYU pragma: export
#endif