validators.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2006-2026, Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2026, Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: BSD-3-Clause
 
#pragma once
 
#include <algorithm>
#include <any>
#include <concepts>
#include <exception>
#include <fstream>
#include <ranges>
#include <regex>
 
#include <sharg/detail/safe_filesystem_entry.hpp>
#include <sharg/detail/to_string.hpp>
#include <sharg/exceptions.hpp>
 
namespace sharg
{
 
// clang-format off
template <typename validator_type>
concept validator = std::copyable<std::remove_cvref_t<validator_type>> &&
                    requires { typename std::remove_reference_t<validator_type>::option_value_type; } &&
                    requires(validator_type validator,
                             typename std::remove_reference_t<validator_type>::option_value_type value)
                    {
                        {validator(value)} -> std::same_as<void>;
                        {validator.get_help_page_message()} -> std::same_as<std::string>;
                    };
// clang-format on
 
template <typename option_value_t>
    requires std::is_arithmetic_v<option_value_t>
class arithmetic_range_validator
{
public:
    using option_value_type = option_value_t;
 
    arithmetic_range_validator(option_value_type const min_, option_value_type const max_) :
        min{min_},
        max{max_},
        valid_range_str{"[" + std::to_string(min_) + "," + std::to_string(max_) + "]"}
    {}
 
    void operator()(option_value_type const & cmp) const
    {
        if (!((cmp <= max) && (cmp >= min)))
            throw validation_error{"Value " + std::to_string(cmp) + " is not in range " + valid_range_str + "."};
    }
 
    template <std::ranges::forward_range range_type>
        requires std::is_arithmetic_v<std::ranges::range_value_t<range_type>>
    void operator()(range_type const & range) const
    {
        std::for_each(range.begin(),
                      range.end(),
                      [&](auto cmp)
                      {
                          (*this)(cmp);
                      });
    }
 
    std::string get_help_page_message() const
    {
        return std::string{"Value must be in range "} + valid_range_str + ".";
    }
 
private:
    option_value_type min{};
 
    option_value_type max{};
 
    std::string valid_range_str{};
};
 
template <parsable option_value_t>
class value_list_validator
{
public:
    using option_value_type = option_value_t;
 
    value_list_validator() = default;                                         
    value_list_validator(value_list_validator const &) = default;             
    value_list_validator(value_list_validator &&) = default;                  
    value_list_validator & operator=(value_list_validator const &) = default; 
    value_list_validator & operator=(value_list_validator &&) = default;      
    ~value_list_validator() = default;                                        
 
    template <std::ranges::forward_range range_type>
        requires std::constructible_from<option_value_type, std::ranges::range_rvalue_reference_t<range_type>>
    value_list_validator(range_type rng) // No &&, because rng will be moved.
    {
        std::move(rng.begin(), rng.end(), std::back_inserter(values));
    }
 
    template <typename... option_types>
        requires ((std::constructible_from<option_value_type, option_types> && ...))
    value_list_validator(option_types &&... opts)
    {
        (values.emplace_back(std::forward<option_types>(opts)), ...);
    }
 
    void operator()(option_value_type const & cmp) const
    {
        if (!(std::find(values.begin(), values.end(), cmp) != values.end()))
            throw validation_error{detail::to_string("Value ", cmp, " is not one of ", values, ".")};
    }
 
    template <std::ranges::forward_range range_type>
        requires std::convertible_to<std::ranges::range_value_t<range_type>, option_value_type>
              && (!std::same_as<std::remove_cvref_t<range_type>, std::filesystem::path>)
    void operator()(range_type const & range) const
    {
        std::for_each(std::ranges::begin(range),
                      std::ranges::end(range),
                      [&](auto && cmp)
                      {
                          (*this)(cmp);
                      });
    }
 
    std::string get_help_page_message() const
    {
        return detail::to_string("Value must be one of ", values, ".");
    }
 
private:
    std::vector<option_value_type> values{};
};
 
template <typename option_type, typename... option_types>
    requires (std::constructible_from<std::string, std::decay_t<option_types>> && ...
              && std::constructible_from<std::string, std::decay_t<option_type>>)
value_list_validator(option_type, option_types...) -> value_list_validator<std::string>;
 
template <typename range_type>
    requires (std::ranges::forward_range<std::decay_t<range_type>>
              && std::constructible_from<std::string, std::ranges::range_value_t<range_type>>)
value_list_validator(range_type && rng) -> value_list_validator<std::string>;
 
template <typename option_type, typename... option_types>
value_list_validator(option_type, option_types...) -> value_list_validator<option_type>;
 
template <typename range_type>
    requires (std::ranges::forward_range<std::decay_t<range_type>>)
value_list_validator(range_type && rng) -> value_list_validator<std::ranges::range_value_t<range_type>>;
 
class file_validator_base
{
public:
    using option_value_type = std::string;
 
    file_validator_base() = default;                                        
    file_validator_base(file_validator_base const &) = default;             
    file_validator_base(file_validator_base &&) = default;                  
    file_validator_base & operator=(file_validator_base const &) = default; 
    file_validator_base & operator=(file_validator_base &&) = default;      
    virtual ~file_validator_base() = default;                               
 
    virtual void operator()(std::filesystem::path const & path) const = 0;
 
    template <std::ranges::forward_range range_type>
        requires (std::convertible_to<std::ranges::range_value_t<range_type>, std::filesystem::path const &>
                  && !std::convertible_to<range_type, std::filesystem::path const &>)
    void operator()(range_type const & v) const
    {
        std::for_each(v.begin(),
                      v.end(),
                      [&](auto && cmp)
                      {
                          this->operator()(cmp);
                      });
    }
 
protected:
    void validate_filename(std::filesystem::path const & path) const
    {
        // If no valid extensions are given we can safely return here.
        if (extensions.empty())
            return;
 
        // Check if extension is available.
        if (!path.has_extension())
        {
            throw validation_error{"The given filename " + path.string()
                                   + " has no extension. Expected one of the "
                                     "following valid extensions:"
                                   + extensions_str + "!"};
        }
 
        std::string file_path{path.filename().string()};
 
        // Leading dot indicates a hidden file is not part of the extension.
        if (file_path.front() == '.')
            file_path.erase(0, 1);
 
        // Store a string_view containing all extensions for a better error message.
        std::string const all_extensions{file_path.substr(file_path.find('.') + 1)};
 
        // Compares the extensions in lower case.
        auto case_insensitive_ends_with = [&](std::string const & ext)
        {
            return case_insensitive_string_ends_with(file_path, ext);
        };
 
        // Check if requested extension is present.
        if (std::find_if(extensions.begin(), extensions.end(), case_insensitive_ends_with) == extensions.end())
        {
            throw validation_error{"Expected one of the following valid extensions: " + extensions_str + "! Got "
                                   + all_extensions + " instead!"};
        }
    }
 
    void validate_readability(std::filesystem::path const & path) const
    {
        // Check if input directory is readable.
        if (std::filesystem::is_directory(path))
        {
            std::error_code ec{};
            // if directory iterator cannot be created, ec will be set.
            std::filesystem::directory_iterator{path, ec}; // NOLINT(bugprone-unused-raii)
            if (static_cast<bool>(ec))
                throw validation_error{"Cannot read the directory \"" + path.string() + "\"!"};
        }
        else
        {
            // Must be a regular file.
            if (!std::filesystem::is_regular_file(path))
                throw validation_error{"Expected a regular file \"" + path.string() + "\"!"};
 
            std::ifstream file{path};
            if (!file.is_open() || !file.good())
                throw validation_error{"Cannot read the file \"" + path.string() + "\"!"};
        }
    }
 
    void validate_writeability(std::filesystem::path const & path) const
    {
        // Contingency check. This case should already be handled by the output_file_validator.
        // Opening a file handle on a directory would delete its contents.
        // LCOV_EXCL_START
        if (std::filesystem::is_directory(path))
            throw validation_error{"\"" + path.string() + "\" is a directory. Cannot validate writeability."};
        // LCOV_EXCL_STOP
 
        // Validation happens before the application runs, and the application may still fail. Truncating or removing
        // an existing file here would destroy it. Opening it for appending checks the permissions without changing it.
        if (std::filesystem::exists(path))
        {
            std::ofstream file{path, std::ios::app};
            if (!file.is_open() || !file.good())
                throw validation_error{"Cannot write \"" + path.string() + "\"!"};
            return;
        }
 
        std::ofstream file{path};
        sharg::detail::safe_filesystem_entry file_guard{path};
 
        bool is_open = file.is_open();
        bool is_good = file.good();
        file.close();
 
        if (!is_good || !is_open)
            throw validation_error{"Cannot write \"" + path.string() + "\"!"};
 
        file_guard.remove();
    }
 
    std::string valid_extensions_help_page_message() const
    {
        if (extensions.empty())
            return "";
        else
            return "Valid file extensions are: " + extensions_str + ".";
    }
 
    bool case_insensitive_string_ends_with(std::string_view str, std::string_view suffix) const
    {
        size_t const suffix_length{suffix.size()};
        size_t const str_length{str.size()};
 
        if (suffix_length > str_length)
            return false;
 
        for (size_t j = 0, s_start = str_length - suffix_length; j < suffix_length; ++j)
            if (std::tolower(str[s_start + j]) != std::tolower(suffix[j]))
                return false;
 
        return true;
    }
 
    std::vector<std::string> extensions{};
 
    std::string extensions_str{};
};
 
class input_file_validator : public file_validator_base
{
public:
    // Import from base class.
    using typename file_validator_base::option_value_type;
 
    input_file_validator() = default;                                         
    input_file_validator(input_file_validator const &) = default;             
    input_file_validator(input_file_validator &&) = default;                  
    input_file_validator & operator=(input_file_validator const &) = default; 
    input_file_validator & operator=(input_file_validator &&) = default;      
    virtual ~input_file_validator() = default;                                
 
    explicit input_file_validator(std::vector<std::string> extensions) : file_validator_base{}
    {
        file_validator_base::extensions_str = detail::to_string(extensions);
        file_validator_base::extensions = std::move(extensions);
    }
 
    // Import base class constructor.
    using file_validator_base::file_validator_base;
 
    // Import the base::operator()
    using file_validator_base::operator();
 
    virtual void operator()(std::filesystem::path const & file) const override
    {
        try
        {
            if (!std::filesystem::exists(file))
                throw validation_error{"The file \"" + file.string() + "\" does not exist!"};
 
            // Check if file is regular and can be opened for reading.
            validate_readability(file);
 
            // Check extension.
            validate_filename(file);
        }
        // LCOV_EXCL_START
        catch (std::filesystem::filesystem_error & ex)
        {
            std::throw_with_nested(validation_error{"Unhandled filesystem error!"});
        }
        // LCOV_EXCL_STOP
        catch (...)
        {
            std::rethrow_exception(std::current_exception());
        }
    }
 
    std::string get_help_page_message() const
    {
        return "The input file must exist and read permissions must be granted."
             + ((valid_extensions_help_page_message().empty()) ? std::string{} : std::string{" "})
             + valid_extensions_help_page_message();
    }
};
 
enum class output_file_open_options : uint8_t
{
    open_or_create,
    create_new
};
 
class output_file_validator : public file_validator_base
{
public:
    // Import from base class.
    using typename file_validator_base::option_value_type;
 
    output_file_validator() = default;                                          
    output_file_validator(output_file_validator const &) = default;             
    output_file_validator(output_file_validator &&) = default;                  
    output_file_validator & operator=(output_file_validator const &) = default; 
    output_file_validator & operator=(output_file_validator &&) = default;      
    virtual ~output_file_validator() = default;                                 
 
    explicit output_file_validator(output_file_open_options const mode, std::vector<std::string> extensions) :
        open_mode{mode}
    {
        file_validator_base::extensions_str = detail::to_string(extensions);
        file_validator_base::extensions = std::move(extensions);
    }
 
    explicit output_file_validator(output_file_open_options const mode, auto &&... extensions)
        requires ((std::constructible_from<std::string, decltype(extensions)> && ...))
        : output_file_validator{mode, std::vector<std::string>{std::forward<decltype(extensions)>(extensions)...}}
    {}
 
    explicit output_file_validator(std::vector<std::string> const & extensions) :
        output_file_validator{output_file_open_options::create_new, extensions}
    {}
 
    explicit output_file_validator(auto &&... extensions)
        requires ((std::constructible_from<std::string, decltype(extensions)> && ...))
        : output_file_validator{std::vector<std::string>{std::forward<decltype(extensions)>(extensions)...}}
    {}
 
    // Import base constructor.
    using file_validator_base::file_validator_base;
 
    // Import the base::operator()
    using file_validator_base::operator();
 
    virtual void operator()(std::filesystem::path const & file) const override
    {
        if (std::filesystem::is_directory(file))
            throw validation_error{"\"" + file.string() + "\" is a directory. Expected a file."};
 
        try
        {
            if ((open_mode == output_file_open_options::create_new) && std::filesystem::exists(file))
                throw validation_error{"The file \"" + file.string() + "\" already exists!"};
 
            // Check if file has any write permissions.
            validate_writeability(file);
 
            validate_filename(file);
        }
        // LCOV_EXCL_START
        catch (std::filesystem::filesystem_error & ex)
        {
            std::throw_with_nested(validation_error{"Unhandled filesystem error!"});
        }
        // LCOV_EXCL_STOP
        catch (...)
        {
            std::rethrow_exception(std::current_exception());
        }
    }
 
    std::string get_help_page_message() const
    {
        if (open_mode == output_file_open_options::open_or_create)
        {
            return "Write permissions must be granted."
                 + ((valid_extensions_help_page_message().empty()) ? std::string{} : std::string{" "})
                 + valid_extensions_help_page_message();
        }
        else // open_mode == create_new
        {
            return "The output file must not exist already and write permissions must be granted."
                 + ((valid_extensions_help_page_message().empty()) ? std::string{} : std::string{" "})
                 + valid_extensions_help_page_message();
        }
    }
 
private:
    output_file_open_options open_mode{output_file_open_options::create_new};
};
 
class input_directory_validator : public file_validator_base
{
public:
    // Import from base class.
    using typename file_validator_base::option_value_type;
 
    input_directory_validator() = default;                                              
    input_directory_validator(input_directory_validator const &) = default;             
    input_directory_validator(input_directory_validator &&) = default;                  
    input_directory_validator & operator=(input_directory_validator const &) = default; 
    input_directory_validator & operator=(input_directory_validator &&) = default;      
    virtual ~input_directory_validator() = default;                                     
 
    // Import base constructor.
    using file_validator_base::file_validator_base;
 
    // Import the base::operator()
    using file_validator_base::operator();
 
    virtual void operator()(std::filesystem::path const & dir) const override
    {
        try
        {
            if (!std::filesystem::exists(dir))
                throw validation_error{"The directory \"" + dir.string() + "\" does not exists!"};
 
            if (!std::filesystem::is_directory(dir))
                throw validation_error{"The path \"" + dir.string() + "\" is not a directory!"};
 
            // Check if directory has any read permissions.
            validate_readability(dir);
        }
        // LCOV_EXCL_START
        catch (std::filesystem::filesystem_error & ex)
        {
            std::throw_with_nested(validation_error{"Unhandled filesystem error!"});
        }
        // LCOV_EXCL_STOP
        catch (...)
        {
            std::rethrow_exception(std::current_exception());
        }
    }
 
    std::string get_help_page_message() const
    {
        return "An existing, readable path for the input directory.";
    }
};
 
class output_directory_validator : public file_validator_base
{
public:
    // Imported from base class.
    using typename file_validator_base::option_value_type;
 
    output_directory_validator() = default;                                               
    output_directory_validator(output_directory_validator const &) = default;             
    output_directory_validator(output_directory_validator &&) = default;                  
    output_directory_validator & operator=(output_directory_validator const &) = default; 
    output_directory_validator & operator=(output_directory_validator &&) = default;      
    virtual ~output_directory_validator() = default;                                      
 
    // Import base constructor.
    using file_validator_base::file_validator_base;
 
    // Import the base::operator().
    using file_validator_base::operator();
 
    virtual void operator()(std::filesystem::path const & dir) const override
    {
        bool dir_exists = std::filesystem::exists(dir);
        // Make sure the created dir is deleted after we are done.
        std::error_code ec;
        std::filesystem::create_directory(dir, ec); // does nothing and is not treated as error if path already exists.
        // if error code was set or if dummy.txt could not be created within the output dir, throw an error.
        if (static_cast<bool>(ec))
            throw validation_error{"Cannot create directory: \"" + dir.string() + "\"!"};
 
        try
        {
            if (!dir_exists)
            {
                sharg::detail::safe_filesystem_entry dir_guard{dir};
                validate_writeability(dir / "dummy.txt");
                dir_guard.remove_all();
            }
            else
            {
                validate_writeability(dir / "dummy.txt");
            }
        }
        // LCOV_EXCL_START
        catch (std::filesystem::filesystem_error & ex)
        {
            std::throw_with_nested(validation_error{"Unhandled filesystem error!"});
        }
        // LCOV_EXCL_STOP
        catch (...)
        {
            std::rethrow_exception(std::current_exception());
        }
    }
 
    std::string get_help_page_message() const
    {
        return "A valid path for the output directory.";
    }
};
 
class regex_validator
{
public:
    using option_value_type = std::string;
 
    regex_validator(std::string const & pattern_) : pattern{pattern_}
    {}
 
    void operator()(option_value_type const & cmp) const
    {
        std::regex rgx(pattern);
        if (!std::regex_match(cmp, rgx))
            throw validation_error{"Value " + cmp + " did not match the pattern " + pattern + "."};
    }
 
    template <std::ranges::forward_range range_type>
        requires std::convertible_to<std::ranges::range_reference_t<range_type>, std::string const &>
    void operator()(range_type const & v) const
    {
        for (auto && entry : v)
        {
            // note: we explicitly copy/construct any reference type other than `std::string &`
            (*this)(static_cast<std::string const &>(entry));
        }
    }
 
    std::string get_help_page_message() const
    {
        return "Value must match the pattern '" + pattern + "'.";
    }
 
private:
    std::string pattern;
};
 
namespace detail
{
 
struct default_validator
{
    using option_value_type = std::any;
 
    template <typename option_value_t>
    void operator()(option_value_t const & /*cmp*/) const noexcept
    {}
 
    std::string get_help_page_message() const
    {
        return "";
    }
};
 
template <validator validator1_type, validator validator2_type>
    requires std::common_with<typename validator1_type::option_value_type, typename validator2_type::option_value_type>
class validator_chain_adaptor
{
public:
    using option_value_type =
        std::common_type_t<typename validator1_type::option_value_type, typename validator2_type::option_value_type>;
 
    validator_chain_adaptor() = delete;                                                
    validator_chain_adaptor(validator_chain_adaptor const & pf) = default;             
    validator_chain_adaptor & operator=(validator_chain_adaptor const & pf) = default; 
    validator_chain_adaptor(validator_chain_adaptor &&) = default;                     
    validator_chain_adaptor & operator=(validator_chain_adaptor &&) = default;         
 
    validator_chain_adaptor(validator1_type vali1_, validator2_type vali2_) :
        vali1{std::move(vali1_)},
        vali2{std::move(vali2_)}
    {}
 
    ~validator_chain_adaptor() = default;
 
    template <typename cmp_type>
        requires std::invocable<validator1_type, cmp_type const> && std::invocable<validator2_type, cmp_type const>
    void operator()(cmp_type const & cmp) const
    {
        vali1(cmp);
        vali2(cmp);
    }
 
    std::string get_help_page_message() const
    {
        return vali1.get_help_page_message() + " " + vali2.get_help_page_message();
    }
 
private:
    validator1_type vali1;
    validator2_type vali2;
};
 
} // namespace detail
 
template <validator validator1_type, validator validator2_type>
    requires std::common_with<typename std::remove_reference_t<validator1_type>::option_value_type,
                              typename std::remove_reference_t<validator2_type>::option_value_type>
auto operator|(validator1_type && vali1, validator2_type && vali2)
{
    return detail::validator_chain_adaptor{std::forward<validator1_type>(vali1), std::forward<validator2_type>(vali2)};
}
 
} // namespace sharg