MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
XmlReader.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "CompositeReader.hpp"
4
6
7namespace MayaFlux::IO {
8
9/**
10 * @brief Composite row layout used by the XML reader and writer.
11 *
12 * Rows are in document preorder. The optional parent field holds the global
13 * index of the owning element or declaration; top-level nodes have no parent.
14 * Attribute rows immediately follow their owner and precede child nodes.
15 * Kind is element, attribute, text, cdata, comment, pi, declaration, or
16 * doctype. Name and value are present where that node kind supplies them.
17 */
18[[nodiscard]] MAYAFLUX_API Kakshya::CompositeLayout xml_composite_layout();
19
21
22struct XmlFieldView;
23class XmlDocument;
24
25/**
26 * @brief Borrowed XML element with named attributes and immediate child elements.
27 * @note The view and its strings are invalid after the reader is closed,
28 * reopened, moved, or destroyed.
29 */
30class MAYAFLUX_API XmlElementView {
31public:
32 [[nodiscard]] uint64_t row() const noexcept { return m_row; }
33 [[nodiscard]] std::string_view name() const noexcept;
34 [[nodiscard]] std::optional<std::string_view> attribute(std::string_view name) const noexcept;
35
36 /**
37 * @brief Visit attributes and immediate child elements in document order.
38 * @return False if a boolean visitor stops traversal; true otherwise.
39 */
40 template <typename Fn>
41 bool for_each_field(Fn&& visitor) const;
42
43private:
44 friend class XmlReader;
45 friend class XmlDocument;
46
47 XmlElementView(const Kakshya::CompositeArray& rows,
48 const Kakshya::ForestIndex& forest, size_t row) noexcept
49 : m_rows(&rows)
50 , m_forest(&forest)
51 , m_row(row)
52 {
53 }
54
57 size_t m_row;
58};
59
60/**
61 * @brief One attribute or immediate child element borrowed from an XML element.
62 * Attribute value is text; element is present only for a child element.
63 */
66 std::string_view name;
67 std::string_view value;
68 uint64_t row;
69 std::optional<XmlElementView> element;
70};
71
72template <typename Fn>
73bool XmlElementView::for_each_field(Fn&& visitor) const
74{
75 const size_t end = m_row + m_forest->subtree_size(m_row);
76 for (size_t index = m_row + 1; index < end; index += m_forest->subtree_size(index)) {
77 const auto source = m_rows->at(index);
78 if (!source)
79 continue;
80
81 const auto kind = source->text("kind");
82 if (!kind || (*kind != "attribute" && *kind != "element"))
83 continue;
84
85 const auto field_name = source->text("name");
86 if (!field_name)
87 continue;
88
89 const XmlFieldView field {
90 .kind = *kind == "attribute" ? XmlFieldKind::Attribute : XmlFieldKind::Element,
91 .name = *field_name,
92 .value = source->text("value").value_or(std::string_view {}),
93 .row = static_cast<uint64_t>(index),
94 .element = *kind == "element"
95 ? std::optional<XmlElementView>(XmlElementView(*m_rows, *m_forest, index))
96 : std::nullopt,
97 };
98 if constexpr (std::same_as<std::invoke_result_t<Fn&, const XmlFieldView&>, bool>) {
99 if (!std::invoke(visitor, field))
100 return false;
101 } else {
102 std::invoke(visitor, field);
103 }
104 }
105 return true;
106}
107
108/**
109 * @class XmlReader
110 * @brief Read an XML document into preorder Composite rows.
111 *
112 * The complete document is parsed on open(). Bounded reads copy rows from
113 * that owning array and retain global parent indices. This is not streaming
114 * XML input. Parsed character data, CDATA, comments, processing instructions,
115 * declarations, and doctypes remain separate rows. Entity references are
116 * expanded by pugixml, so the result preserves document semantics rather
117 * than original source bytes.
118 *
119 * Usage:
120 * @code
121 * XmlReader reader;
122 * if (reader.open("controls.xml")) {
123 * auto layout = reader.get_layout();
124 * auto nodes = reader.read_composite();
125 * }
126 * @endcode
127 *
128 * @note The input limit is 64 MiB, one million rows, and 256 element levels.
129 * A batch is not a standalone document because its parent indices refer to
130 * the complete preorder sequence.
131 */
132class MAYAFLUX_API XmlReader : public CompositeReader {
133public:
134 /** @brief Accept paths with the .xml extension. */
135 [[nodiscard]] bool can_read(const std::string& filepath) const override;
136
137 /**
138 * @brief Parse an XML file and establish the fixed node layout.
139 * @return True for a parsed document with one root element.
140 */
141 bool open(const std::string& filepath,
142 FileReadOptions options = FileReadOptions::ALL) override;
143
144 /** @brief Release parsed rows and reset the read position. */
145 void close() override;
146
147 /** @brief Whether parsed rows are available. */
148 [[nodiscard]] bool is_open() const override { return m_rows.has_value(); }
149
150 /** @brief XML format, MIME type, and source file size. */
151 [[nodiscard]] std::optional<FileMetadata> get_metadata() const override;
152
153 /** @brief XML nodes do not declare FileRegion values. */
154 [[nodiscard]] std::vector<FileRegion> get_regions() const override { return {}; }
155
156 /** @brief Copy all rows remaining after the current position. */
157 [[nodiscard]] std::optional<Kakshya::CompositeArray> read_composite() override;
158
159 /**
160 * @brief Copy at most max_elements rows and advance the position.
161 * @return An empty array at end of document, or nullopt on failure.
162 */
163 [[nodiscard]] std::optional<Kakshya::CompositeArray> read_next(size_t max_elements) override;
164
165 /** @brief Copy the finalized node layout while open. */
166 [[nodiscard]] std::optional<Kakshya::CompositeLayout> get_layout() const override;
167
168 /** @brief Borrow the document root element, independent of the row read position. */
169 [[nodiscard]] std::optional<XmlElementView> root_element() const noexcept;
170
171 /** @brief Borrow an element by its global XML row index. */
172 [[nodiscard]] std::optional<XmlElementView> element_at(uint64_t row) const noexcept;
173
174 /** @brief Borrow the parsed XML rows while the reader remains open. */
175 [[nodiscard]] const Kakshya::CompositeArray* rows_view() const noexcept
176 {
177 return m_rows ? &*m_rows : nullptr;
178 }
179
180 /**
181 * @brief Move the parsed rows out and close the reader.
182 * @return The rows, or nullopt when no document is open. Borrowed views
183 * and rows_view() are invalid afterwards.
184 */
185 [[nodiscard]] std::optional<Kakshya::CompositeArray> take_rows();
186
187 /** @brief Global index of the next row. */
188 [[nodiscard]] std::vector<uint64_t> get_read_position() const override { return { m_position }; }
189
190 /** @brief Seek to one row index, including the end position. */
191 bool seek(const std::vector<uint64_t>& position) override;
192
193 /** @brief Supported extension without a dot. */
194 [[nodiscard]] std::vector<std::string> get_supported_extensions() const override { return { "xml" }; }
195
196 /** @brief The parser loads the complete XML document on open(). */
197 [[nodiscard]] bool supports_streaming() const override { return false; }
198
199 /** @brief Suggested size for bounded Composite copies. */
200 [[nodiscard]] uint64_t get_preferred_chunk_size() const override { return 1024; }
201
202 /** @brief The document is exposed as one row axis. */
203 [[nodiscard]] size_t get_num_dimensions() const override { return 1; }
204
205 /** @brief Total number of rows while open. */
206 [[nodiscard]] std::vector<uint64_t> get_dimension_sizes() const override;
207
208private:
209 std::optional<Kakshya::CompositeArray> m_rows;
210 std::optional<Kakshya::ForestIndex> m_forest;
211 std::string m_filepath;
212 uint64_t m_position {};
213};
214
215}
Typed FileReader boundary for schema-bearing Composite data.
const Kakshya::CompositeArray * m_rows
Definition XmlReader.hpp:55
XmlElementView(const Kakshya::CompositeArray &rows, const Kakshya::ForestIndex &forest, size_t row) noexcept
Definition XmlReader.hpp:47
uint64_t row() const noexcept
Definition XmlReader.hpp:32
bool for_each_field(Fn &&visitor) const
Visit attributes and immediate child elements in document order.
Definition XmlReader.hpp:73
const Kakshya::ForestIndex * m_forest
Definition XmlReader.hpp:56
Borrowed XML element with named attributes and immediate child elements.
Definition XmlReader.hpp:30
std::vector< uint64_t > get_read_position() const override
Global index of the next row.
const Kakshya::CompositeArray * rows_view() const noexcept
Borrow the parsed XML rows while the reader remains open.
uint64_t get_preferred_chunk_size() const override
Suggested size for bounded Composite copies.
std::vector< FileRegion > get_regions() const override
XML nodes do not declare FileRegion values.
bool can_read(const std::string &filepath) const override
Accept paths with the .xml extension.
Definition XmlReader.cpp:95
std::vector< std::string > get_supported_extensions() const override
Supported extension without a dot.
bool open(const std::string &filepath, FileReadOptions options=FileReadOptions::ALL) override
Parse an XML file and establish the fixed node layout.
size_t get_num_dimensions() const override
The document is exposed as one row axis.
void close() override
Release parsed rows and reset the read position.
std::optional< Kakshya::CompositeArray > m_rows
std::optional< Kakshya::ForestIndex > m_forest
bool supports_streaming() const override
The parser loads the complete XML document on open().
bool is_open() const override
Whether parsed rows are available.
Read an XML document into preorder Composite rows.
Owns a sequence of values that share a CompositeLayout.
Parent, child, depth and subtree structure over rows linked by parent index.
FileReadOptions
Generic options for file reading behavior.
@ ALL
All options enabled.
Kakshya::CompositeLayout xml_composite_layout()
Composite row layout used by the XML reader and writer.
Definition XmlReader.cpp:13
std::string_view name
Definition XmlReader.hpp:66
std::string_view value
Definition XmlReader.hpp:67
std::optional< XmlElementView > element
Definition XmlReader.hpp:69
One attribute or immediate child element borrowed from an XML element.
Definition XmlReader.hpp:64