magic.hpp

Go to the documentation of this file.

/* SPDX-FileCopyrightText: Copyright (c) 2022-2025 Oğuz Toraman <oguz.toraman@tutanota.com> */
/* SPDX-License-Identifier: LGPL-3.0-only */
 
#ifndef MAGIC_HPP
#define MAGIC_HPP
 
#include <bitset>
#include <expected>
#include <map>
#include <memory>
#include <optional>
#include <string_view>
#include <vector>
 
#include "magic_exception.hpp"
#include "progress_tracker.hpp"
#include "utility.hpp"
 
namespace recognition {
class magic {
public:
    using flags_mask_t = std::bitset<30uz>;

    using file_type_t = std::string;

    using error_message_t = std::string;

    using expected_file_type_t = std::expected<file_type_t, error_message_t>;

    using types_of_files_t = std::map<std::filesystem::path, file_type_t>;

    using type_of_a_file_t = types_of_files_t::value_type;

    using expected_types_of_files_t = std::map<
        std::filesystem::path,
        expected_file_type_t
    >;

    using expected_type_of_a_file_t = expected_types_of_files_t::value_type;

    using tracker_t = utility::shared_progress_tracker_t;

    enum flags : unsigned long long {
        /* clang-format off */
        none              = 0ULL,       
        debug             = 1ULL << 0,  
        symlink           = 1ULL << 1,  
        compress          = 1ULL << 2,  
        devices           = 1ULL << 3,  
        mime_type         = 1ULL << 4,  
        continue_search   = 1ULL << 5,  
        check_database    = 1ULL << 6,  
        preserve_atime    = 1ULL << 7,  
        raw               = 1ULL << 8,  
        error             = 1ULL << 9,  
        mime_encoding     = 1ULL << 10, 
        mime              = 1ULL << 11, 
        apple             = 1ULL << 12, 
        extension         = 1ULL << 13, 
        compress_transp   = 1ULL << 14, 
        no_compress_fork  = 1ULL << 15, 
        nodesc            = 1ULL << 16, 
        no_check_compress = 1ULL << 17, 
        no_check_tar      = 1ULL << 18, 
        no_check_soft     = 1ULL << 19, 
        no_check_apptype  = 1ULL << 20, 
        no_check_elf      = 1ULL << 21, 
        no_check_text     = 1ULL << 22, 
        no_check_cdf      = 1ULL << 23, 
        no_check_csv      = 1ULL << 24, 
        no_check_tokens   = 1ULL << 25, 
        no_check_encoding = 1ULL << 26, 
        no_check_json     = 1ULL << 27, 
        no_check_simh     = 1ULL << 28, 
        no_check_builtin  = 1ULL << 29  
        /* clang-format on */
    };

    enum class parameters : std::size_t {
        /* clang-format off */
        indir_max      = 0uz, 
        name_max       = 1uz, 
        elf_phnum_max  = 2uz, 
        elf_shnum_max  = 3uz, 
        elf_notes_max  = 4uz, 
        regex_max      = 5uz, 
        bytes_max      = 6uz, 
        encoding_max   = 7uz, 
        elf_shsize_max = 8uz, 
        mag_warn_max   = 9uz  
        /* clang-format on */
    };

    using flags_container_t = std::vector<flags>;

    using parameter_value_map_t = std::map<parameters, std::size_t>;

    using parameter_value_t = parameter_value_map_t::value_type;

    static std::string_view default_database_file;

    magic() noexcept;

    explicit magic(
        flags_mask_t                 flags_mask,
        const std::filesystem::path& database_file = default_database_file
    );

    magic(
        flags_mask_t                 flags_mask,
        const std::nothrow_t&        tag,
        const std::filesystem::path& database_file = default_database_file
    ) noexcept;

    explicit magic(
        const flags_container_t&     flags_container,
        const std::filesystem::path& database_file = default_database_file
    );

    magic(
        const flags_container_t&     flags_container,
        const std::nothrow_t&        tag,
        const std::filesystem::path& database_file = default_database_file
    ) noexcept;

    magic(magic&& other) noexcept;

    magic(const magic&) = delete;

    magic& operator=(magic&& other) noexcept;

    magic& operator=(const magic&) = delete;

    ~magic();

    [[nodiscard]] operator bool() const noexcept;

    [[nodiscard]] static bool check(
        const std::filesystem::path& database_file = default_database_file
    ) noexcept;

    void close() noexcept;

    [[nodiscard]] static bool compile(
        const std::filesystem::path& database_file = default_database_file
    ) noexcept;

    [[nodiscard]] flags_container_t get_flags() const;

    [[nodiscard]] std::optional<flags_container_t> get_flags(
        const std::nothrow_t& tag
    ) const noexcept;

    [[nodiscard]] std::size_t get_parameter(parameters parameter) const;

    [[nodiscard]] std::optional<std::size_t> get_parameter(
        parameters            parameter,
        const std::nothrow_t& tag
    ) const noexcept;

    [[nodiscard]] parameter_value_map_t get_parameters() const;

    [[nodiscard]] std::optional<parameter_value_map_t> get_parameters(
        const std::nothrow_t& tag
    ) const noexcept;

    [[nodiscard]] static std::string get_version() noexcept;

    [[nodiscard]] file_type_t identify_file(
        const std::filesystem::path& path
    ) const;

    [[nodiscard]] expected_file_type_t identify_file(
        const std::filesystem::path& path,
        const std::nothrow_t&        tag
    ) const noexcept;

    [[nodiscard]] types_of_files_t identify_files(
        const std::filesystem::path&       directory,
        std::filesystem::directory_options option = std::filesystem::
            directory_options::follow_directory_symlink
    ) const
    {
        return identify_directory_impl(directory, option);
    }

    [[nodiscard]] types_of_files_t identify_files(
        const std::filesystem::path&       directory,
        tracker_t                          tracker,
        std::filesystem::directory_options option = std::filesystem::
            directory_options::follow_directory_symlink
    ) const
    {
        return identify_directory_impl(directory, option, tracker);
    }

    [[nodiscard]] expected_types_of_files_t identify_files(
        const std::filesystem::path&       directory,
        const std::nothrow_t&              tag,
        std::filesystem::directory_options option = std::filesystem::
            directory_options::follow_directory_symlink
    ) const noexcept
    {
        return identify_directory_impl(directory, tag, option);
    }

    [[nodiscard]] expected_types_of_files_t identify_files(
        const std::filesystem::path&       directory,
        const std::nothrow_t&              tag,
        tracker_t                          tracker,
        std::filesystem::directory_options option = std::filesystem::
            directory_options::follow_directory_symlink
    ) const noexcept
    {
        return identify_directory_impl(directory, tag, option, tracker);
    }

    [[nodiscard]] types_of_files_t identify_files(
        const utility::file_container auto& files
    ) const
    {
        return identify_container_impl(
            {std::ranges::begin(files), std::ranges::end(files)}
        );
    }

    [[nodiscard]] types_of_files_t identify_files(
        const utility::file_container auto& files,
        tracker_t                           tracker
    ) const
    {
        return identify_container_impl(
            {std::ranges::begin(files), std::ranges::end(files)},
            tracker
        );
    }

    [[nodiscard]] expected_types_of_files_t identify_files(
        const utility::file_container auto& files,
        const std::nothrow_t&               tag
    ) const noexcept
    {
        return identify_container_impl(
            {std::ranges::begin(files), std::ranges::end(files)},
            tag
        );
    }

    [[nodiscard]] expected_types_of_files_t identify_files(
        const utility::file_container auto& files,
        const std::nothrow_t&               tag,
        tracker_t                           tracker
    ) const noexcept
    {
        return identify_container_impl(
            {std::ranges::begin(files), std::ranges::end(files)},
            tag,
            tracker
        );
    }

    [[nodiscard]] bool is_database_loaded() const noexcept;

    [[nodiscard]] bool is_open() const noexcept;

    [[nodiscard]] bool is_valid() const noexcept;

    void load_database_file(
        const std::filesystem::path& database_file = default_database_file
    );

    [[nodiscard]] bool load_database_file(
        const std::nothrow_t&        tag,
        const std::filesystem::path& database_file = default_database_file
    ) noexcept;

    void open(flags_mask_t flags_mask);

    [[nodiscard]] bool open(
        flags_mask_t          flags_mask,
        const std::nothrow_t& tag
    ) noexcept;

    void open(const flags_container_t& flags_container);

    [[nodiscard]] bool open(
        const flags_container_t& flags_container,
        const std::nothrow_t&    tag
    ) noexcept;

    void set_flags(flags_mask_t flags_mask);

    [[nodiscard]] bool set_flags(
        flags_mask_t          flags_mask,
        const std::nothrow_t& tag
    ) noexcept;

    void set_flags(const flags_container_t& flags_container);

    [[nodiscard]] bool set_flags(
        const flags_container_t& flags_container,
        const std::nothrow_t&    tag
    ) noexcept;

    void set_parameter(parameters parameter, std::size_t value);

    [[nodiscard]] bool set_parameter(
        parameters            parameter,
        std::size_t           value,
        const std::nothrow_t& tag
    ) noexcept;

    void set_parameters(const parameter_value_map_t& parameters);

    [[nodiscard]] bool set_parameters(
        const parameter_value_map_t& parameters,
        const std::nothrow_t&        tag
    ) noexcept;
 
private:
    class magic_private;
    std::unique_ptr<magic_private> m_impl;
 
    using default_file_container_t = std::vector<std::filesystem::path>;
 
    [[nodiscard]] types_of_files_t identify_directory_impl(
        const std::filesystem::path&       directory,
        std::filesystem::directory_options option,
        tracker_t tracker = utility::make_shared_progress_tracker()
    ) const;
 
    [[nodiscard]] expected_types_of_files_t identify_directory_impl(
        const std::filesystem::path&       directory,
        const std::nothrow_t&              tag,
        std::filesystem::directory_options option,
        tracker_t tracker = utility::make_shared_progress_tracker()
    ) const noexcept;
 
    [[nodiscard]] types_of_files_t identify_container_impl(
        const default_file_container_t& files,
        tracker_t tracker = utility::make_shared_progress_tracker()
    ) const;
 
    [[nodiscard]] expected_types_of_files_t identify_container_impl(
        const default_file_container_t& files,
        const std::nothrow_t&           tag,
        tracker_t tracker = utility::make_shared_progress_tracker()
    ) const noexcept;
 
    friend std::string to_string(flags);
    friend std::string to_string(parameters);
};

[[nodiscard]] std::string to_string(
    const magic::type_of_a_file_t& type_of_a_file,
    const std::string&             type_separator = " -> "
);

[[nodiscard]] std::string to_string(
    const magic::types_of_files_t& types_of_files,
    const std::string&             type_separator = " -> ",
    const std::string&             file_separator = "\n"
);

[[nodiscard]] std::string to_string(
    const magic::expected_file_type_t& expected_file_type
);

[[nodiscard]] std::string to_string(
    const magic::expected_type_of_a_file_t& expected_type_of_a_file,
    const std::string&                      type_separator = " -> "
);

[[nodiscard]] std::string to_string(
    const magic::expected_types_of_files_t& expected_types_of_files,
    const std::string&                      type_separator = " -> ",
    const std::string&                      file_separator = "\n"
);

[[nodiscard]] std::string to_string(magic::flags flag);

[[nodiscard]] std::string to_string(
    const magic::flags_container_t& flags,
    const std::string&              separator = ", "
);

[[nodiscard]] std::string to_string(magic::parameters parameter);

[[nodiscard]] std::string to_string(
    const magic::parameter_value_t& parameter_value,
    const std::string&              value_separator = ": "
);

[[nodiscard]] std::string to_string(
    const magic::parameter_value_map_t& parameters,
    const std::string&                  value_separator     = ": ",
    const std::string&                  parameter_separator = ", "
);
} /* namespace recognition */
 
#endif /* MAGIC_HPP */