validators.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: BSD-3-Clause
 
#pragma once
 
#include <algorithm>
#include <concepts>
#include <exception>
#include <filesystem>
#include <fstream>
#include <ranges>
#include <regex>
#include <sstream>
 
#include <seqan3/argument_parser/exceptions.hpp>
#include <seqan3/core/debug_stream/detail/to_string.hpp>
#include <seqan3/core/debug_stream/range.hpp>
#include <seqan3/io/detail/misc.hpp>
#include <seqan3/io/detail/safe_filesystem_entry.hpp>
#include <seqan3/utility/concept.hpp>
#include <seqan3/utility/type_list/traits.hpp>
#include <seqan3/utility/type_pack/traits.hpp>
#include <seqan3/utility/type_traits/basic.hpp>
#include <seqan3/utility/views/join_with.hpp>
 
SEQAN3_DEPRECATED_HEADER("This header and its functionality is deprecated and will be removed in a future version of SeqAn. Please use the sharg-parser (url: https://github.com/seqan/sharg-parser) instead.");
 
namespace seqan3
{
 
template <typename validator_type>
concept validator =
    std::copyable<std::remove_cvref_t<validator_type>>
    && requires (validator_type validator, typename std::remove_reference_t<validator_type>::option_value_type value) {
           typename std::remove_reference_t<validator_type>::option_value_type;
 
           { validator(value) } -> std::same_as<void>;
           { validator.get_help_page_message() } -> std::same_as<std::string>;
       };
 
template <arithmetic 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_}
    {}
    arithmetic_range_validator(option_value_type const min_, option_value_type const max_) : min{min_}, max{max_} {…}
 
    void operator()(option_value_type const & cmp) const
    {
        if (!((cmp <= max) && (cmp >= min)))
            throw validation_error{detail::to_string("Value ", cmp, " is not in range [", min, ",", max, "].")};
    }
    void operator()(option_value_type const & cmp) const {…}
 
    template <std::ranges::forward_range range_type>
        requires arithmetic<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);
                      });
    }
    void operator()(range_type const & range) const {…}
 
    std::string get_help_page_message() const
    {
        return detail::to_string("Value must be in range [", min, ",", max, "].");
    }
    std::string get_help_page_message() const {…}
 
private:
    option_value_type min{};
 
    option_value_type max{};
};
class arithmetic_range_validator {…};
 
template <typename 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)
    {
        values.clear();
        std::ranges::move(std::move(rng), std::back_inserter(values));
    }
    value_list_validator(range_type rng) {…}
 
    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)), ...);
    }
    value_list_validator(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 ", std::views::all(values), ".")};
    }
    void operator()(option_value_type const & cmp) const {…}
 
    template <std::ranges::forward_range range_type>
        requires std::convertible_to<std::ranges::range_value_t<range_type>, option_value_type>
    void operator()(range_type const & range) const
    {
        std::for_each(std::ranges::begin(range),
                      std::ranges::end(range),
                      [&](auto cmp)
                      {
                          (*this)(cmp);
                      });
    }
    void operator()(range_type const & range) const {…}
 
    std::string get_help_page_message() const
    {
        return detail::to_string("Value must be one of ", std::views::all(values), ".");
    }
    std::string get_help_page_message() const {…}
 
private:
    std::vector<option_value_type> values{};
};
class value_list_validator {…};
 
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);
                      });
    }
    void operator()(range_type const & v) const {…}
 
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{detail::to_string("The given filename ",
                                                     path.string(),
                                                     " has no extension. Expected"
                                                     " one of the following valid extensions:",
                                                     extensions,
                                                     "!")};
 
        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::ranges::find_if(extensions, case_insensitive_ends_with) == extensions.end())
        {
            throw validation_error{detail::to_string("Expected one of the following valid extensions: ",
                                                     extensions,
                                                     "! Got ",
                                                     all_extensions,
                                                     " instead!")};
        }
    }
    void validate_filename(std::filesystem::path const & path) const {…}
 
    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{};
            std::filesystem::directory_iterator{path, ec}; // if directory iterator cannot be created, ec will be set.
            if (static_cast<bool>(ec))
                throw validation_error{detail::to_string("Cannot read the directory ", path, "!")};
        }
        else
        {
            // Must be a regular file.
            if (!std::filesystem::is_regular_file(path))
                throw validation_error{detail::to_string("Expected a regular file ", path, "!")};
 
            std::ifstream file{path};
            if (!file.is_open() || !file.good())
                throw validation_error{detail::to_string("Cannot read the file ", path, "!")};
        }
    }
    void validate_readability(std::filesystem::path const & path) const {…}
 
    void validate_writeability(std::filesystem::path const & path) const
    {
        std::ofstream file{path};
        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{detail::to_string("Cannot write ", path, "!")};
 
        file_guard.remove();
    }
    void validate_writeability(std::filesystem::path const & path) const {…}
 
    std::string valid_extensions_help_page_message() const
    {
        if (extensions.empty())
            return "";
        else
            return detail::to_string(" Valid file extensions are: [",
                                     extensions | views::join_with(std::string{", "}),
                                     "].");
    }
    std::string valid_extensions_help_page_message() const {…}
 
    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()};
        return suffix_length > str_length ? false
                                          : std::ranges::equal(str.substr(str_length - suffix_length),
                                                               suffix,
                                                               [](char const chr1, char const chr2)
                                                               {
                                                                   return std::tolower(chr1) == std::tolower(chr2);
                                                               });
    }
    bool case_insensitive_string_ends_with(std::string_view str, std::string_view suffix) const {…}
 
    std::vector<std::string> extensions{};
};
class file_validator_base {…};
 
template <typename file_t = void>
class input_file_validator : public file_validator_base
{
public:
    static_assert(std::same_as<file_t, void> || detail::has_type_valid_formats<file_t>,
                  "Expected either a template type with a static member called valid_formats (a file type) or void.");
 
    // Import from base class.
    using typename file_validator_base::option_value_type;
 
    input_file_validator()
    {
        if constexpr (!std::same_as<file_t, void>)
            file_validator_base::extensions = detail::valid_file_extensions<typename file_t::valid_formats>();
    }
    input_file_validator() {…}
 
    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)
        requires std::same_as<file_t, void>
        : file_validator_base{}
    {
        file_validator_base::extensions = std::move(extensions);
    }
    explicit input_file_validator(std::vector<std::string> 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{detail::to_string("The file ", file, " 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());
        }
    }
    virtual void operator()(std::filesystem::path const & file) const override {…}
 
    std::string get_help_page_message() const
    {
        return "The input file must exist and read permissions must be granted." + valid_extensions_help_page_message();
    }
    std::string get_help_page_message() const {…}
};
class input_file_validator : public file_validator_base {…};
 
enum class output_file_open_options
{
    open_or_create,
    create_new
};
enum class output_file_open_options {…};
 
template <typename file_t = void>
class output_file_validator : public file_validator_base
{
public:
    static_assert(std::same_as<file_t, void> || detail::has_type_valid_formats<file_t>,
                  "Expected either a template type with a static member called valid_formats (a file type) or void.");
 
    // Import from base class.
    using typename file_validator_base::option_value_type;
 
    output_file_validator() : output_file_validator{output_file_open_options::create_new}
    {}
    output_file_validator() : output_file_validator{output_file_open_options::create_new} {…}
 
    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 = default_extensions()) :
        file_validator_base{},
        mode{mode}
    {
        file_validator_base::extensions = std::move(extensions);
    }
    explicit output_file_validator(output_file_open_options const mode, {…}
 
    // Import base constructor.
    using file_validator_base::file_validator_base;
 
    static std::vector<std::string> default_extensions()
    {
        if constexpr (!std::same_as<file_t, void>)
            return detail::valid_file_extensions<typename file_t::valid_formats>();
        return {};
    }
    static std::vector<std::string> default_extensions() {…}
 
    // Import the base::operator()
    using file_validator_base::operator();
 
    virtual void operator()(std::filesystem::path const & file) const override
    {
        try
        {
            if ((mode == output_file_open_options::create_new) && std::filesystem::exists(file))
                throw validation_error{detail::to_string("The file ", file, " 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());
        }
    }
    virtual void operator()(std::filesystem::path const & file) const override {…}
 
    std::string get_help_page_message() const
    {
        if (mode == output_file_open_options::open_or_create)
            return "Write permissions must be granted." + valid_extensions_help_page_message();
        else // mode == create_new
            return "The output file must not exist already and write permissions must be granted."
                 + valid_extensions_help_page_message();
    }
    std::string get_help_page_message() const {…}
 
private:
    output_file_open_options mode{output_file_open_options::create_new};
};
class output_file_validator : public file_validator_base {…};
 
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{detail::to_string("The directory ", dir, " does not exists!")};
 
            if (!std::filesystem::is_directory(dir))
                throw validation_error{detail::to_string("The path ", dir, " 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());
        }
    }
    virtual void operator()(std::filesystem::path const & dir) const override {…}
 
    std::string get_help_page_message() const
    {
        return detail::to_string("An existing, readable path for the input directory.");
    }
    std::string get_help_page_message() const {…}
};
class input_directory_validator : public file_validator_base {…};
 
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{detail::to_string("Cannot create directory: ", dir, "!")};
 
        try
        {
            if (!dir_exists)
            {
                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());
        }
    }
    virtual void operator()(std::filesystem::path const & dir) const override {…}
 
    std::string get_help_page_message() const
    {
        return detail::to_string("A valid path for the output directory.");
    }
    std::string get_help_page_message() const {…}
};
class output_directory_validator : public file_validator_base {…};
 
class regex_validator
{
public:
    using option_value_type = std::string;
 
    regex_validator(std::string const & pattern_) : pattern{pattern_}
    {}
    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{detail::to_string("Value ", cmp, " did not match the pattern ", pattern, ".")};
    }
    void operator()(option_value_type const & cmp) const {…}
 
    template <std::ranges::forward_range range_type>
        requires std::convertible_to<std::ranges::range_reference_t<range_type>, option_value_type const &>
    void operator()(range_type const & v) const
    {
        for (auto && file_name : v)
        {
            // note: we explicitly copy/construct any reference type other than `std::string &`
            (*this)(static_cast<option_value_type const &>(file_name));
        }
    }
    void operator()(range_type const & v) const {…}
 
    std::string get_help_page_message() const
    {
        return detail::to_string("Value must match the pattern '", pattern, "'.");
    }
    std::string get_help_page_message() const {…}
 
private:
    std::string pattern;
};
class regex_validator {…};
 
namespace detail
{
 
template <typename option_value_t>
struct default_validator
{
    using option_value_type = 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 detail::to_string(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)};
}
auto operator|(validator1_type && vali1, validator2_type && vali2) {…}
 
} // namespace seqan3