magic.hpp

Go to the documentation of this file.

/* SPDX-FileCopyrightText: Copyright (c) 2022-2026 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 FlagsMaskT = std::bitset<30uz>;

    using FileTypeT = std::string;

    using ErrorMessageT = std::string;

    using ExpectedFileTypeT = std::expected<FileTypeT, ErrorMessageT>;

    using FileTypeMapT = std::map<std::filesystem::path, FileTypeT>;

    using FileTypeEntryT = FileTypeMapT::value_type;

    using ExpectedFileTypeMapT = std::map<
        std::filesystem::path,
        ExpectedFileTypeT
    >;

    using ExpectedFileTypeEntryT = ExpectedFileTypeMapT::value_type;

    using ProgressTrackerT = Utility::SharedProgressTrackerT;

    enum Flags : unsigned long long {
        /* clang-format off */
        None             = 0ULL,       
        Debug            = 1ULL << 0,  
        Symlink          = 1ULL << 1,  
        Compress         = 1ULL << 2,  
        Devices          = 1ULL << 3,  
        MimeType         = 1ULL << 4,  
        ContinueSearch   = 1ULL << 5,  
        CheckDatabase    = 1ULL << 6,  
        PreserveAtime    = 1ULL << 7,  
        Raw              = 1ULL << 8,  
        Error            = 1ULL << 9,  
        MimeEncoding     = 1ULL << 10, 
        Mime             = 1ULL << 11, 
        Apple            = 1ULL << 12, 
        Extension        = 1ULL << 13, 
        CompressTransp   = 1ULL << 14, 
        NoCompressFork   = 1ULL << 15, 
        Nodesc           = 1ULL << 16, 
        NoCheckCompress  = 1ULL << 17, 
        NoCheckTar       = 1ULL << 18, 
        NoCheckSoft      = 1ULL << 19, 
        NoCheckApptype   = 1ULL << 20, 
        NoCheckElf       = 1ULL << 21, 
        NoCheckText      = 1ULL << 22, 
        NoCheckCdf       = 1ULL << 23, 
        NoCheckCsv       = 1ULL << 24, 
        NoCheckTokens    = 1ULL << 25, 
        NoCheckEncoding  = 1ULL << 26, 
        NoCheckJson      = 1ULL << 27, 
        NoCheckSimh      = 1ULL << 28, 
        NoCheckBuiltin   = 1ULL << 29  
        /* clang-format on */
    };

    enum class Parameters : std::size_t {
        /* clang-format off */
        IndirMax     = 0uz, 
        NameMax      = 1uz, 
        ElfPhnumMax  = 2uz, 
        ElfShnumMax  = 3uz, 
        ElfNotesMax  = 4uz, 
        RegexMax     = 5uz, 
        BytesMax     = 6uz, 
        EncodingMax  = 7uz, 
        ElfShsizeMax = 8uz, 
        MagWarnMax   = 9uz  
        /* clang-format on */
    };

    using FlagsContainerT = std::vector<Flags>;

    using ParameterValueMapT = std::map<Parameters, std::size_t>;

    using ParameterValueT = ParameterValueMapT::value_type;

    static std::string_view DEFAULT_DATABASE_FILE;


    Magic() noexcept;

    explicit Magic(
        FlagsMaskT                   flags_mask,
        const std::filesystem::path& database_file = DEFAULT_DATABASE_FILE
    );

    Magic(
        FlagsMaskT                   flags_mask,
        const std::nothrow_t&        tag,
        const std::filesystem::path& database_file = DEFAULT_DATABASE_FILE
    ) noexcept;

    explicit Magic(
        const FlagsContainerT&       flags_container,
        const std::filesystem::path& database_file = DEFAULT_DATABASE_FILE
    );

    Magic(
        const FlagsContainerT&       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]] FlagsContainerT GetFlags() const;

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



    [[nodiscard]] std::size_t GetParameter(Parameters parameter) const;

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

    [[nodiscard]] ParameterValueMapT GetParameters() const;

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



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



    [[nodiscard]] FileTypeT IdentifyFile(
        const std::filesystem::path& path
    ) const;

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

    [[nodiscard]] FileTypeMapT IdentifyFiles(
        const std::filesystem::path&       directory,
        std::filesystem::directory_options option = std::filesystem::
            directory_options::follow_directory_symlink
    ) const
    {
        return IdentifyDirectoryImpl(directory, option);
    }

    [[nodiscard]] FileTypeMapT IdentifyFiles(
        const std::filesystem::path&       directory,
        ProgressTrackerT                   progress_tracker,
        std::filesystem::directory_options option = std::filesystem::
            directory_options::follow_directory_symlink
    ) const
    {
        return IdentifyDirectoryImpl(directory, option, progress_tracker);
    }

    [[nodiscard]] ExpectedFileTypeMapT IdentifyFiles(
        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 IdentifyDirectoryImpl(directory, tag, option);
    }

    [[nodiscard]] ExpectedFileTypeMapT IdentifyFiles(
        const std::filesystem::path&       directory,
        const std::nothrow_t&              tag,
        ProgressTrackerT                   progress_tracker,
        std::filesystem::directory_options option = std::filesystem::
            directory_options::follow_directory_symlink
    ) const noexcept
    {
        return IdentifyDirectoryImpl(directory, tag, option, progress_tracker);
    }

    [[nodiscard]] FileTypeMapT IdentifyFiles(
        const Utility::FileContainer auto& files
    ) const
    {
        return IdentifyContainerImpl(
            {std::ranges::begin(files), std::ranges::end(files)}
        );
    }

    [[nodiscard]] FileTypeMapT IdentifyFiles(
        const Utility::FileContainer auto& files,
        ProgressTrackerT                   progress_tracker
    ) const
    {
        return IdentifyContainerImpl(
            {std::ranges::begin(files), std::ranges::end(files)},
            progress_tracker
        );
    }

    [[nodiscard]] ExpectedFileTypeMapT IdentifyFiles(
        const Utility::FileContainer auto& files,
        const std::nothrow_t&              tag
    ) const noexcept
    {
        return IdentifyContainerImpl(
            {std::ranges::begin(files), std::ranges::end(files)},
            tag
        );
    }

    [[nodiscard]] ExpectedFileTypeMapT IdentifyFiles(
        const Utility::FileContainer auto& files,
        const std::nothrow_t&              tag,
        ProgressTrackerT                   progress_tracker
    ) const noexcept
    {
        return IdentifyContainerImpl(
            {std::ranges::begin(files), std::ranges::end(files)},
            tag,
            progress_tracker
        );
    }



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

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

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



    void LoadDatabaseFile(
        const std::filesystem::path& database_file = DEFAULT_DATABASE_FILE
    );

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



    void Open(FlagsMaskT flags_mask);

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

    void Open(const FlagsContainerT& flags_container);

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



    void SetFlags(FlagsMaskT flags_mask);

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

    void SetFlags(const FlagsContainerT& flags_container);

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



    void SetParameter(Parameters parameter, std::size_t value);

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

    void SetParameters(const ParameterValueMapT& parameters);

    [[nodiscard]] bool SetParameters(
        const ParameterValueMapT& parameters,
        const std::nothrow_t&     tag
    ) noexcept;

 
private:
    class MagicPrivate;

    std::unique_ptr<MagicPrivate> m_impl;

    using DefaultFileContainerT = std::vector<std::filesystem::path>;

    [[nodiscard]] FileTypeMapT IdentifyDirectoryImpl(
        const std::filesystem::path&       directory,
        std::filesystem::directory_options option,
        ProgressTrackerT progress_tracker = Utility::MakeSharedProgressTracker()
    ) const;

    [[nodiscard]] ExpectedFileTypeMapT IdentifyDirectoryImpl(
        const std::filesystem::path&       directory,
        const std::nothrow_t&              tag,
        std::filesystem::directory_options option,
        ProgressTrackerT progress_tracker = Utility::MakeSharedProgressTracker()
    ) const noexcept;

    [[nodiscard]] FileTypeMapT IdentifyContainerImpl(
        const DefaultFileContainerT& files,
        ProgressTrackerT progress_tracker = Utility::MakeSharedProgressTracker()
    ) const;

    [[nodiscard]] ExpectedFileTypeMapT IdentifyContainerImpl(
        const DefaultFileContainerT& files,
        const std::nothrow_t&        tag,
        ProgressTrackerT progress_tracker = Utility::MakeSharedProgressTracker()
    ) const noexcept;

    friend std::string ToString(Flags);

    friend std::string ToString(Parameters);
};


[[nodiscard]] std::string ToString(
    const Magic::FileTypeEntryT& file_type_entry,
    const std::string&           type_separator = " -> "
);

[[nodiscard]] std::string ToString(
    const Magic::FileTypeMapT& file_type_map,
    const std::string&         type_separator = " -> ",
    const std::string&         file_separator = "\n"
);

[[nodiscard]] std::string ToString(
    const Magic::ExpectedFileTypeT& expected_file_type
);

[[nodiscard]] std::string ToString(
    const Magic::ExpectedFileTypeEntryT& expected_file_type_entry,
    const std::string&                   type_separator = " -> "
);

[[nodiscard]] std::string ToString(
    const Magic::ExpectedFileTypeMapT& expected_file_type_map,
    const std::string&                 type_separator = " -> ",
    const std::string&                 file_separator = "\n"
);

[[nodiscard]] std::string ToString(Magic::Flags flag);

[[nodiscard]] std::string ToString(
    const Magic::FlagsContainerT& flags,
    const std::string&            separator = ", "
);

[[nodiscard]] std::string ToString(Magic::Parameters parameter);

[[nodiscard]] std::string ToString(
    const Magic::ParameterValueT& parameter_value,
    const std::string&            value_separator = ": "
);

[[nodiscard]] std::string ToString(
    const Magic::ParameterValueMapT& parameters,
    const std::string&               value_separator     = ": ",
    const std::string&               parameter_separator = ", "
);

} /* namespace Recognition */
 
#endif /* MAGIC_HPP */