XLDocument.hpp

Go to the documentation of this file.

#ifndef OPENXLSX_XLDOCUMENT_HPP
#define OPENXLSX_XLDOCUMENT_HPP
 
#ifdef _MSC_VER    // conditionally enable MSVC specific pragmas to avoid other compilers warning about unknown pragmas
#    pragma warning(push)
#    pragma warning(disable : 4251)
#    pragma warning(disable : 4275)
#endif    // _MSC_VER
 
// ===== External Includes ===== //
#include <algorithm>    // std::find_if
#include <gsl/gsl>
#include <list>
#include <map>
#include <memory>          // std::unique_ptr
#include <shared_mutex>    // std::shared_mutex
#include <string>
#include <string_view>
#include <unordered_map>    // O(1) shared string lookup
 
// ===== OpenXLSX Includes ===== //
#include "IZipArchive.hpp"
#include "OpenXLSX-Exports.hpp"
#include "XLChart.hpp"
#include "XLCommandQuery.hpp"
#include "XLComments.hpp"
#include "XLContentTypes.hpp"
#include "XLDrawing.hpp"
#include "XLProperties.hpp"
#include "XLRelationships.hpp"
#include "XLSharedStrings.hpp"
#include "XLStringArena.hpp"
#include "XLStyles.hpp"
#include "XLTables.hpp"
#include "XLThreadedComments.hpp"
#include "XLWorkbook.hpp"
#include "XLXmlData.hpp"
#include "XLZipArchive.hpp"
#include "XLInternalAccess.hpp"
 
namespace OpenXLSX
{
    constexpr const unsigned int pugi_parse_settings = pugi::parse_default | pugi::parse_ws_pcdata;
 
    constexpr const bool XLForceOverwrite = true;     // readability constant for 2nd parameter of XLDocument::saveAs
    constexpr const bool XLDoNotOverwrite = false;    //  "
 
    enum class XLProperty {
        Title,
        Subject,
        Creator,
        Keywords,
        Description,
        LastModifiedBy,
        LastPrinted,
        CreationDate,
        ModificationDate,
        Category,
        Application,
        DocSecurity,
        ScaleCrop,
        Manager,
        Company,
        LinksUpToDate,
        SharedDoc,
        HyperlinkBase,
        HyperlinksChanged,
        AppVersion
    };
 
    class OPENXLSX_EXPORT XLDocument final
    {
    public:
        struct SharedFormula
        {
            std::string formula;
            uint32_t    baseRow;
            uint16_t    baseCol;
        };
 
        // =========================================================================
        // 受限的内部特权 API (Restricted Internal API)
        // 只有持有 XLInternalAccess 通行证的类才能调用，普通用户代码无法编译。
        // =========================================================================
 
        [[nodiscard]] XLXmlData* getXmlData(XLInternalAccess, std::string_view path, bool doNotThrow = false) {
            return getXmlData(path, doNotThrow);
        }
 
        [[nodiscard]] const XLXmlData* getXmlData(XLInternalAccess, std::string_view path, bool doNotThrow = false) const {
            return getXmlData(path, doNotThrow);
        }
 
        XLXmlData* addXmlData(XLInternalAccess, const std::string& path, const std::string& id, XLContentType type) {
            return &m_data.emplace_back(this, path, id, type);
        }
 
        std::map<void*, std::unordered_map<uint32_t, SharedFormula>>& sharedFormulas(XLInternalAccess) const {
            return m_sharedFormulas;
        }
 
        //---------- Public Member Functions
    public:
        explicit XLDocument(const IZipArchive& zipArchive = XLZipArchive());
 
        explicit XLDocument(std::string_view docPath, const IZipArchive& zipArchive = XLZipArchive());
 
        explicit XLDocument(const std::string& docPath, const IZipArchive& zipArchive = XLZipArchive());
 
        XLDocument(const XLDocument& other)     = delete;
        XLDocument(XLDocument&& other) noexcept = default;
        ~XLDocument();
        XLDocument& operator=(const XLDocument& other)     = delete;
        XLDocument& operator=(XLDocument&& other) noexcept = default;
 
        void showWarnings();
        void suppressWarnings();
 
        void open(std::string_view fileName);
 
        void open(std::string_view fileName, const std::string& password);
 
        void create(std::string_view fileName, bool forceOverwrite = XLForceOverwrite);
 
        [[deprecated]] void create(const std::string& fileName);
 
        void close();
 
        void save();
        void addStreamedFile(std::string_view pathInZip, std::string_view tempFilePath);
 
        void saveAs(std::string_view fileName, bool forceOverwrite = XLForceOverwrite);
 
        void saveAs(std::string_view fileName, const std::string& password, bool forceOverwrite = XLForceOverwrite);
 
        [[deprecated]] void saveAs(const std::string& fileName);
 
        [[nodiscard]] std::string name() const;
 
        [[nodiscard]] const std::string& path() const;
 
        [[nodiscard]] XLContentTypes& contentTypes();
 
        [[nodiscard]]
        bool hasMacro() const;
 
        void deleteMacro();
 
        XLCustomProperties& customProperties();
 
        [[nodiscard]] uint32_t nextTableId() const;
 
        [[nodiscard]] XLWorkbook workbook() const;
 
        [[nodiscard]] std::string property(XLProperty prop) const;
 
        void setProperty(XLProperty prop, std::string_view value);
 
        void deleteProperty(XLProperty theProperty);
 
        [[nodiscard]] explicit operator bool() const;
 
        [[nodiscard]] bool isOpen() const;
 
        void setCompressionLevel(int level);
 
        int compressionLevel() const;
 
        void setDefaultAuthor(const std::string& author);
 
        std::string defaultAuthor() const;
 
        [[nodiscard]] XLStyles& styles();
 
        [[nodiscard]] bool hasSheetRelationships(uint16_t sheetXmlNo, bool isChartsheet = false) const;
        [[nodiscard]] bool hasSheetVmlDrawing(uint16_t sheetXmlNo) const;
        [[nodiscard]] bool hasSheetComments(uint16_t sheetXmlNo) const;
        [[nodiscard]] bool hasSheetThreadedComments(uint16_t sheetXmlNo) const;
        [[nodiscard]] bool hasSheetDrawing(uint16_t sheetXmlNo) const;
        [[nodiscard]] bool hasSheetTables(uint16_t sheetXmlNo) const;
 
        XLRelationships sheetRelationships(uint16_t sheetXmlNo, bool isChartsheet = false);
        XLDrawing       sheetDrawing(uint16_t sheetXmlNo);
        XLDrawing       createDrawing();
        XLDrawing       drawing(std::string_view path);
        XLVmlDrawing    sheetVmlDrawing(uint16_t sheetXmlNo);
        XLComments      sheetComments(uint16_t sheetXmlNo);
        XLThreadedComments sheetThreadedComments(uint16_t sheetXmlNo);
        XLTables        sheetTables(uint16_t sheetXmlNo);
 
        class XLChart createChart(XLChartType type = XLChartType::Bar);
 
        class XLPivotTable           createPivotTable();
        class XLPivotCacheDefinition createPivotCacheDefinition();
        class XLPivotCacheRecords    createPivotCacheRecords(std::string_view cacheDefPath);
 
        std::string createTableSlicerCache(uint32_t tableId, uint32_t tableColumnId, std::string_view name, std::string_view sourceName);
 
        std::string createPivotSlicerCache(uint32_t         pivotCacheId,
                                           uint32_t         sheetId,
                                           std::string_view pivotTableName,
                                           std::string_view name,
                                           std::string_view sourceName);
 
        std::string createSlicer(std::string_view name, std::string_view cacheName, std::string_view caption);
 
        std::string addImage(std::string_view name, std::string_view data);
 
        [[nodiscard]] std::string getImage(std::string_view path) const;
 
        XLRelationships drawingRelationships(std::string_view drawingPath);
        XLRelationships xmlRelationships(std::string_view xmlPath);
        XLRelationships& workbookRelationships() { return m_wbkRelationships; }
 
        [[nodiscard]] IZipArchive&       archive() { return m_archive; }
        [[nodiscard]] const IZipArchive& archive() const { return m_archive; }
 
        [[nodiscard]] XLAppProperties&       appProperties() { return m_appProperties; }
        [[nodiscard]] const XLAppProperties& appProperties() const { return m_appProperties; }
 
        [[nodiscard]] XLProperties&       coreProperties() { return m_coreProperties; }
        [[nodiscard]] const XLProperties& coreProperties() const { return m_coreProperties; }
 
        bool validateSheetName(std::string_view sheetName, bool throwOnInvalid = false);
 
        bool execCommand(const XLCommand& command);
 
        [[nodiscard]] XLQuery execQuery(const XLQuery& query) const;
        XLQuery               execQuery(const XLQuery& query);
 
        void setSavingDeclaration(XLXmlSavingDeclaration const& savingDeclaration);
 
        [[nodiscard]] const XLSharedStrings& sharedStrings() const { return m_sharedStrings; }
 
        bool hasPersons() const;
 
        XLPersons& persons();
 
        void cleanupSharedStrings();
 
        void setFormulaNeedsRecalculation(bool status = true) { m_formulaNeedsRecalculation = status; }
 
    public:
        [[nodiscard]] std::string extractXmlFromArchive(std::string_view path);
 
    protected:
        [[nodiscard]] XLXmlData*       getXmlData(std::string_view path, bool doNotThrow = false);
        [[nodiscard]] const XLXmlData* getXmlData(std::string_view path, bool doNotThrow = false) const;
        [[nodiscard]] bool             hasXmlData(std::string_view path) const;
 
    public:
        std::shared_mutex& mutex() const { return *m_docMutex; }
 
    private:
        bool        m_suppressWarnings{true};
        std::string m_filePath{};
        std::string m_defaultAuthor{"System Admin"};
 
        XLXmlSavingDeclaration m_xmlSavingDeclaration;
 
        mutable std::list<XLXmlData>                                         m_data{};
        mutable XLSharedStringsState                                         m_sharedStringsState{};
        mutable std::unique_ptr<std::shared_mutex>                           m_docMutex{std::make_unique<std::shared_mutex>()};
        mutable XLSharedStrings                                              m_sharedStrings{};
        mutable std::map<void*, std::unordered_map<uint32_t, SharedFormula>> m_sharedFormulas{};
        std::map<std::string, std::string>                                   m_unhandledEntries{};
 
        bool m_formulaNeedsRecalculation{false};
        bool m_isEncryptedSession{false};
        std::string m_encryptionPassword{""};
        std::string m_tempDecryptedPath{""};
 
        XLRelationships    m_docRelationships{};
        XLRelationships    m_wbkRelationships{};
        XLContentTypes     m_contentTypes{};
        XLAppProperties    m_appProperties{};
        XLProperties       m_coreProperties{};
        XLCustomProperties m_customProperties{};
        XLStyles           m_styles{};
        XLWorkbook         m_workbook{};
        XLPersons          m_persons{};
        IZipArchive        m_archive{};
    };
 
    [[nodiscard]] OPENXLSX_EXPORT std::string BinaryAsHexString(gsl::span<const std::byte> data);
    [[nodiscard]] OPENXLSX_EXPORT uint16_t    ExcelPasswordHash(std::string_view password);
    [[nodiscard]] OPENXLSX_EXPORT std::string ExcelPasswordHashAsString(std::string_view password);
 
    [[nodiscard]] std::string getPathARelativeToPathB(std::string_view pathA, std::string_view pathB);
    [[nodiscard]] std::string eliminateDotAndDotDotFromPath(std::string_view path);
 
}    // namespace OpenXLSX
 
#ifdef _MSC_VER    // conditionally enable MSVC specific pragmas to avoid other compilers warning about unknown pragmas
#    pragma warning(pop)
#endif    // _MSC_VER
 
#endif    // OPENXLSX_XLDOCUMENT_HPP