DOCSEARCHbyAlgolia
Submit Docs

pugixml Documentation

repository·master·Indexed 26 days ago

https://github.com/zeux/pugixml

A lightweight, high-performance C++ XML processing library featuring a DOM-like interface, XPath 1.0 support, and full Unicode capabilities. It provides tools for parsing XML from files or buffers, navigating tree nodes, and performing complex queries. The library supports multiple build configurations, including header-only mode and shared library (DLL) builds, and offers customizable memory management and parsing options.

Tokens
15K
Snippets
22
Records
76
Agent score
82%

What's inside pugixml

  1. Overview of pugixml capabilities

    master

    pugixml is a C++ XML processing library designed for high performance. It provides:

    • A DOM-like interface with rich traversal and modification capabilities.
    • An extremely fast XML parser that constructs a DOM tree from XML files or memory buffers.
    • An XPath 1.0 implementation for performing complex, data-driven queries on the tree.
    • Full Unicode support, including Unicode interface variants and automatic conversions between different Unicode encodings during parsing and saving.

  2. Overview of pugixml

    master
    pugixml is a high-performance C++ XML processing library. It provides a DOM-like interface for tree traversal and modification, an extremely fast XML parser for constructing DOM trees from files or buffers, and an XPath 1.0 implementation for complex queries. It includes full Unicode support with automatic encoding conversions during parsing and saving.

  3. Understand the pugixml DOM structure

    master

    pugixml uses a DOM-like tree structure where the entire XML document is stored in memory. All classes and functions are located in the pugi namespace.

    Core Types:

    • xml_document: The root of the tree and owner of the document structure. It provides loading and saving functions. It is a subclass of xml_node.
    • xml_node: A handle to any node in the document (including the document itself). It is a non-polymorphic handle; destroying a handle does not destroy the underlying node.
    • xml_attribute: A handle to an XML attribute.

    Common Node Types:

    • node_document: The root node.
    • node_element: Represents XML elements (tags). They contain names, attributes, and child nodes.
    • node_pcdata: Represents plain text (character data). Note that PCDATA is a separate node type and is a child of an element node, not part of the element node itself.

    Null Handles: xml_node and xml_attribute can be "null" or "empty". You can check for validity using an implicit boolean cast: if (node) { ... } or if (!node) { ... }.

  5. Customize the XML document declaration

    master

    By default, xml_document::save() or xml_document::save_file() will output a default XML declaration if the document lacks one. This default declaration is not customizable.

    To use a custom declaration (e.g., custom version, encoding, or standalone status), you must manually create a node of type node_declaration and add it to the document. Since a declaration node behaves like an element node, you can set its attributes to define the declaration details.

    Note: To preserve an existing declaration during parsing, you must use the parse_declaration flag.

  6. Install pugixml

    master

    To install pugixml, download the latest source distribution archive from the GitHub releases page:

    Extract the files. The library consists of three main files:

    1. pugixml.cpp (source file)
    2. pugixml.hpp (primary header)
    3. pugiconfig.hpp (configuration header)

    Building: To use the library, the easiest method is to compile pugixml.cpp directly along with your existing application code. If you are using an IDE like Visual Studio, Xcode, or Code::Blocks, simply add pugixml.cpp to your project.

  7. Build pugixml as part of another project

    master

    The simplest way to use pugixml is to compile its single source file, pugixml.cpp, directly into your existing library or executable. You must include the primary header pugixml.hpp in your source code.

    #include "pugixml.hpp"

  8. Install pugixml from Git repository

    master

    You can clone the pugixml Git repository to get the library source, documentation, examples, and the full unit test suite. Use the v{version} tag for a specific release or the latest tag to track the most recent stable release. Note that the master branch contains work-in-progress code which may occasionally be broken.

    git clone https://github.com/zeux/pugixml
cd pugixml
git checkout v{version}

  10. Load an XML document

    master

    pugixml provides several ways to load XML data into an xml_document:

    • From a file: Use doc.load_file("path.xml").
    • From a string: Use doc.load_string("...").
    • From a memory buffer:
      • load_buffer: For immutable buffers.
      • load_buffer_inplace: For mutable buffers owned by the caller.
      • load_buffer_inplace_own: For mutable buffers where ownership is transferred to pugixml.
    • From a stream: Use functions that accept objects implementing the std::istream or std::wistream interface.

    Error Handling: Loading functions return an xml_parse_result object. You can check for success by treating the result as a boolean:

    if (doc.load_file("file.xml")) {
    // Success
} else {
    // Handle error using result.status() or result.description()
}

  11. Build pugixml as a standalone shared library (DLL)

    master

    To build pugixml as a shared library using an MSVC-based toolchain, you must explicitly mark exported symbols using the PUGIXML_API macro. This is typically done via pugiconfig.hpp:

    #ifdef _DLL
    #define PUGIXML_API __declspec(dllexport)
#else
    #define PUGIXML_API __declspec(dllimport)
#endif

    Caution: When using STL-related functions, ensure you use the shared runtime library (e.g., /MD or /MDd in MSVC) to ensure a single heap is used for allocations between your application and pugixml.

  12. Assemble a document from XML fragments

    master

    There are three primary ways to assemble an XML document from in-memory buffers or fragments:

    1. Temporary Document (Convenient but slower): Parse the buffer into a temporary xml_document, then use append_copy to move nodes to the target.
    2. Cached Fragments (Faster): Keep xml_document objects that already contain the parsed fragments and use append_copy to move nodes from the cached document to the target.
    3. Direct append_buffer (Fastest): Use xml_node::append_buffer to append the buffer directly to a node. This is typically faster if the buffer is in native encoding (UTF-8 or wchar_t).

    Note: append_buffer only works if the target node is a document or an element. Calling it on other node types results in status_append_invalid_root.

    // Method 1: Using a temporary document
bool append_fragment(pugi::xml_node target, const char* buffer, size_t size)
{
    pugi::xml_document doc;
    if (!doc.load_buffer(buffer, size)) return false;

    for (pugi::xml_node child = doc.first_child(); child; child = child.next_sibling())
        target.append_copy(child);

    return true;
}

// Method 3: Direct append_buffer
xml_parse_result xml_node::append_buffer(const void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);