MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
XmlDocument.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "XmlReader.hpp"
4
6
7namespace MayaFlux::IO {
8
9/**
10 * @class XmlDocument
11 * @brief A parsed XML document that owns its rows and hierarchy.
12 *
13 * Reads a file once and keeps the preorder Composite rows with their parent
14 * index, so element views stay valid for as long as the document lives and no
15 * reader has to stay open. Any consumer can bind described records from the
16 * views, walk the forest, or select a branch as a Region. The document is
17 * immutable and shared.
18 *
19 * Usage:
20 * @code
21 * std::string error;
22 * auto document = XmlDocument::load("scene.xml", error);
23 * if (document) {
24 * auto root = document->root_element();
25 * auto branch = document->forest().subtree_region(3);
26 * }
27 * @endcode
28 */
29class MAYAFLUX_API XmlDocument {
30public:
31 /**
32 * @brief Parse a file into an owning document.
33 * @param error Receives the reason when nullptr is returned.
34 */
35 [[nodiscard]] static std::shared_ptr<const XmlDocument> load(
36 const std::string& path, std::string& error);
37
38 /**
39 * @brief Take ownership of rows in the XML node layout.
40 * @param rows Rows laid out as xml_composite_layout in document order.
41 * @param error Receives the reason when nullptr is returned.
42 * @return The document, or nullptr when the layout differs or a row's
43 * parent does not precede it.
44 */
45 [[nodiscard]] static std::shared_ptr<const XmlDocument> from_rows(
46 Kakshya::CompositeArray rows, std::string& error);
47
48 /** @brief The rows together with their parent index. */
49 [[nodiscard]] const Kakshya::CompositeForest& forest() const noexcept { return *m_forest; }
50
51 /** @brief Borrow the document root element. */
52 [[nodiscard]] std::optional<XmlElementView> root_element() const noexcept;
53
54 /** @brief Borrow an element by its row index. */
55 [[nodiscard]] std::optional<XmlElementView> element_at(uint64_t row) const noexcept;
56
57private:
58 explicit XmlDocument(std::shared_ptr<const Kakshya::CompositeForest> forest) noexcept
59 : m_forest(std::move(forest))
60 {
61 }
62
63 std::shared_ptr<const Kakshya::CompositeForest> m_forest;
64};
65
66}
std::shared_ptr< const Kakshya::CompositeForest > m_forest
static std::shared_ptr< const XmlDocument > from_rows(Kakshya::CompositeArray rows, std::string &error)
Take ownership of rows in the XML node layout.
XmlDocument(std::shared_ptr< const Kakshya::CompositeForest > forest) noexcept
const Kakshya::CompositeForest & forest() const noexcept
The rows together with their parent index.
static std::shared_ptr< const XmlDocument > load(const std::string &path, std::string &error)
Parse a file into an owning document.
Borrowed XML element with named attributes and immediate child elements.
Definition XmlReader.hpp:30
Owns a sequence of values that share a CompositeLayout.
A Composite array together with the index of its parent links.