├── .gitignore
├── benchmarks
    └── dishwasher
    │   ├── build.zig.zon
    │   ├── src
    │       ├── gl2.xml
    │       └── main.zig
    │   └── build.zig
├── src
    ├── dishwasher.zig
    ├── stringify.zig
    ├── Scanner.zig
    ├── populate.zig
    └── parse.zig
├── LICENSE
├── README.md
└── docs
    └── index.html


/.gitignore:
--------------------------------------------------------------------------------
1 | .zig-cache
2 | zig-out
3 | 
4 | benchmarks/dishwasher/src/mega.xml
5 | 


--------------------------------------------------------------------------------
/benchmarks/dishwasher/build.zig.zon:
--------------------------------------------------------------------------------
1 | .{
2 |     .name = .benchmarks_dishwasher,
3 |     .version = "0.0.0",
4 |     .fingerprint = 0xadb94a6b532fc55c,
5 |     .dependencies = .{ .dishwasher = .{ .path = "../.." } },
6 |     .paths = .{ "build.zig", "build.zig.zon", "src" },
7 | }
8 | 


--------------------------------------------------------------------------------
/src/dishwasher.zig:
--------------------------------------------------------------------------------
 1 | pub const Scanner = @import("Scanner.zig");
 2 | pub const Populate = @import("populate.zig").Populate;
 3 | 
 4 | pub const parse = @import("parse.zig");
 5 | pub const populate = @import("populate.zig");
 6 | 
 7 | test {
 8 |     _ = @import("Scanner.zig");
 9 |     _ = @import("parse.zig");
10 |     _ = @import("populate.zig");
11 | }
12 | 


--------------------------------------------------------------------------------
/benchmarks/dishwasher/src/gl2.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="hello"?>
 2 | <registry>
 3 |     <comment>
 4 | Copyright 2013-2020 The Khronos Group Inc.
 5 | SPDX-License-Identifier: Apache-2.0
 6 | 
 7 | This file, gl.xml, is the OpenGL and OpenGL API Registry. The canonical
 8 | version of the registry, together with documentation, schema, and Python
 9 | generator scripts used to generate C header files for OpenGL and OpenGL ES,
10 | can always be found in the Khronos Registry at
11 | https://github.com/KhronosGroup/OpenGL-Registry
12 |     </comment>
13 | 
14 |     <!-- SECTION: GL type definitions. -->
15 | </registry>
16 | 


--------------------------------------------------------------------------------
/benchmarks/dishwasher/build.zig:
--------------------------------------------------------------------------------
 1 | const std = @import("std");
 2 | 
 3 | pub fn build(b: *std.Build) void {
 4 |     const target = b.standardTargetOptions(.{});
 5 |     const optimize = b.standardOptimizeOption(.{});
 6 | 
 7 |     const dishwasher = b.dependency("dishwasher", .{});
 8 | 
 9 |     const exe_mod = b.createModule(.{
10 |         .root_source_file = b.path("src/main.zig"),
11 |         .target = target,
12 |         .optimize = optimize,
13 |     });
14 | 
15 |     const exe = b.addExecutable(.{
16 |         .name = "dishwasher-benchmarks",
17 |         .root_module = exe_mod,
18 |     });
19 | 
20 |     exe.root_module.addImport("dishwasher", dishwasher.module("dishwasher"));
21 | 
22 |     b.installArtifact(exe);
23 | 
24 |     const run_cmd = b.addRunArtifact(exe);
25 | 
26 |     run_cmd.step.dependOn(b.getInstallStep());
27 | 
28 |     if (b.args) |args| {
29 |         run_cmd.addArgs(args);
30 |     }
31 | 
32 |     const run_step = b.step("run", "Run the app");
33 |     run_step.dependOn(&run_cmd.step);
34 | }
35 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | 
 2 | 
 3 | Copyright 2024 edqx
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 6 | 
 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 8 | 
 9 | THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
10 | 
11 | 


--------------------------------------------------------------------------------
/benchmarks/dishwasher/src/main.zig:
--------------------------------------------------------------------------------
 1 | const std = @import("std");
 2 | const dishwasher = @import("dishwasher");
 3 | 
 4 | pub fn main() !void {
 5 |     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
 6 | 
 7 |     var times = std.ArrayList(usize).init(gpa.allocator());
 8 |     defer times.deinit();
 9 | 
10 |     const fileData = try std.fs.cwd().readFileAlloc(gpa.allocator(), "./src/gl.xml", 1024 * 1024 * 200);
11 |     defer gpa.allocator().free(fileData);
12 | 
13 |     for (0..100) |_| {
14 |         const us1 = std.time.microTimestamp();
15 |         var ownedDocument = try dishwasher.parse.fromSlice(gpa.allocator(), fileData);
16 |         defer ownedDocument.deinit();
17 |         const us2 = std.time.microTimestamp();
18 |         try times.append(@intCast(@divFloor(us2 - us1, 1000)));
19 |     }
20 | 
21 |     const min = std.mem.min(usize, times.items);
22 |     const max = std.mem.max(usize, times.items);
23 |     var sum: usize = 0;
24 |     for (times.items) |i| sum += i;
25 |     const avg = @as(f32, @floatFromInt(sum)) / @as(f32, @floatFromInt(times.items.len));
26 | 
27 |     try std.io.getStdOut().writer().print("min: {}ms, max: {}ms, avg: {d:2}ms\n", .{ min, max, avg });
28 | }
29 | 


--------------------------------------------------------------------------------
/src/stringify.zig:
--------------------------------------------------------------------------------
 1 | const std = @import("std");
 2 | const Tree = @import("./parse.zig").Tree;
 3 | 
 4 | const Options = struct {
 5 |     const IndentStyle = union(enum) {
 6 |         none: void,
 7 |         tabs: void,
 8 |         spaces: usize,
 9 |     };
10 | 
11 |     const TextFormattingStyle = union(enum) {
12 |         verbatim: void,
13 |         max_width: usize,
14 |     };
15 | 
16 |     indent_style: IndentStyle = .{
17 |         .spaces = 4,
18 |     },
19 | 
20 |     // Whether or not text content should be trimmed and aligned as if whitespace
21 |     // was limited to 1 (one) space.
22 |     format_text_content: TextFormattingStyle = .{ .max_width = 80 },
23 | };
24 | 
25 | fn writeTextFormatted(indentation: usize, text: []const u8, max_width: usize) !void {}
26 | 
27 | fn writeTreeImpl(tree: Tree, options: Options, writer: anytype, depth: usize) !void {
28 |     for (tree.children) |child| {
29 |         switch (child) {
30 |             .elem => |elem_child| {},
31 |             .text => |text_child| {
32 |                 if (options.format_text_content) {
33 |                     writeTextFormatted(text_child.contents, options, writer);
34 |                 } else {
35 |                     writer.write(text_child.contents);
36 |                 }
37 |             },
38 |             .comment => |comment_child| {},
39 |         }
40 |     }
41 | }
42 | 
43 | pub fn writeTree(tree: Tree, options: Options, writer: anytype) !void {
44 |     try writeTreeImpl(tree, options, writer, 0);
45 | }
46 | 
47 | test writeTree {
48 |     var tree: Tree = .{ .children = &.{} };
49 |     var array = std.array_list.Managed(u8).init(std.testing.allocator);
50 |     defer array.deinit();
51 | 
52 |     writeTree(tree, .{}, array.writer());
53 | }
54 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Dishwasher
  2 | 
  3 | A fairly fast XML parser for [Zig](https://ziglang.org).
  4 | 
  5 | **For those on Zig 0.15.2, check out the [0.15.2](https://github.com/edqx/dishwasher/tree/0.15.2) branch**
  6 | 
  7 | Note that this parser isn't strictly spec-compliant, however it will probably
  8 | work with most well-formed xml documents.
  9 | 
 10 | ## Features
 11 | - [x] Pretty speedy
 12 | - [x] Reader API-friendly
 13 | - [x] Can populate structs
 14 | - [x] Can populate dynamic values
 15 | - [x] Compile-time parsing
 16 | - [x] Diagnostics for malformed documents
 17 | - [ ] Stringification (coming soon)
 18 | 
 19 | ### Benchmarks
 20 | 
 21 | Here are the results from the given benchmarks on my pc (i9-14900kf) in different
 22 | optimisation modes, when parsing the [OpenGL XML Spec document](https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/gl.xml)
 23 | fully.
 24 | 
 25 | | Mode | Min | Max | Avg |
 26 | |------|-----|-----|-----|
 27 | | `Debug` | `100ms` | `280ms` | `131ms` |
 28 | | `ReleaseSafe` | `13ms` | `25ms` | `15ms` | 
 29 | | `ReleaseSmall` | `18ms` | `50ms` | `30ms` |
 30 | | `ReleaseFast` | `7ms` | `27ms` | `13ms` |
 31 | 
 32 | _All times are averaged over 100 runs, rounded to the nearest 2sf._
 33 | 
 34 | ## Documentation
 35 | 
 36 | Generate documentation for dishwasher with `zig build docs`, will output browser files at `zig-out/docs`. You can serve
 37 | this however you like, for example with Python: `python -m http.server` or with NodeJS: `npx serve`.
 38 | 
 39 | ## Usage
 40 | 
 41 | Dishwasher has 4 APIs, 3 of which will be most useful.
 42 | 
 43 | - [Parsing API](#parsing-api) - for parsing an entire XML document at runtime.
 44 | - [Populate API](#populate-api) - for mapping an XML document to a given struct.
 45 | - [Comptime Parsing and Populate API](#comptime-parsing-and-populate-api) - for parsing an entire XML document at compile time.
 46 | - [Scanner API](#scanner-api) - for iterating through XML symbols from a slice or reader.
 47 | 
 48 | ### Parsing API
 49 | Dishwasher lets you parse an XML document from either an entire slice or a
 50 | reader into a tree-like structure that represents all nodes.
 51 | 
 52 | All of the parse methods create an arena which is returned back to you so that
 53 | you can deinitialise it when you no longer need the data.
 54 | 
 55 | #### Parse from a slice
 56 | ```zig
 57 | const owned_tree = dishwasher.parse.fromSlice(allocator, xml_text);
 58 | defer owned_tree.deinit(); // all strings and lists will be free'd
 59 | 
 60 | std.debug.assert(owned_tree.tree.children[0] == .elem);
 61 | ```
 62 | 
 63 | #### Parse from a reader
 64 | ```zig
 65 | const owned_tree = dishwasher.parse.fromReader(allocator, file.reader());
 66 | defer owned_tree.deinit();
 67 | 
 68 | std.debug.assert(owned_tree.tree.children[0] == .elem);
 69 | ```
 70 | 
 71 | #### Diagnostics
 72 | You can also get basic information about invalid documents using the parse
 73 | diagnostics struct, and passing it into either `parse.fromSliceDiagnostics`
 74 | or `parse.fromReaderDiagnostics`.
 75 | ```zig
 76 | var diagnostics = dishwasher.parse.Diagnostics.init(allocator);
 77 | defer diagnostics.deinit();
 78 | 
 79 | const parsed = try dishwasher.parse.fromReaderDiagnostics(allocator, file.reader(), &diagnostics);
 80 | defer parsed.deinit();
 81 | 
 82 | for (diagnostics.defects.items) |defect| {
 83 |   std.debug.print("{} from {}..{}", .{ defect.kind, defect.range.start, defect.range.end });
 84 | }
 85 | ```
 86 | 
 87 | #### Tree API
 88 | The returned tree has the following signature:
 89 | ```zig
 90 | const Tree = struct {
 91 |     pub const Node = union(enum) {
 92 |         pub const Elem = struct {
 93 |             pub const Attr = struct {
 94 |                 name: []const u8,
 95 |                 value: ?[]const u8,
 96 |             };
 97 | 
 98 |             tag_name: []const u8,
 99 |             attributes: []const Attr,
100 |             tree: ?Tree,
101 | 
102 |             // Get an attribute given its name.
103 |             pub fn attributeByName(self: Elem, needle: []const u8) ?Attr;
104 |             pub fn attr(self: Elem, needle: []const u8) ?Attr;
105 | 
106 |             // Get the value of an attribute given its name. Note that if the
107 |             // attribute has no value, e.g., <button disabled> this will
108 |             // still return null. Use attr or attributeByName in those
109 |             // cases.
110 |             pub fn attributeValueByName(self: Elem, needle: []const u8) ?[]const u8;
111 |             pub fn attrValue(self: Elem, needle: []const u8) ?[]const u8;
112 |         };
113 | 
114 |         pub const Text = struct {
115 |             contents: []const u8,
116 | 
117 |             // Return the text without any whitespace at the beginning or end.
118 |             pub fn trimmed(self: Text) []const u8;
119 |         }
120 | 
121 |         pub const Comment = struct {
122 |             contents: []const u8,
123 |         };
124 | 
125 |         elem: Elem,
126 |         text: text,
127 |         comment: Comment,
128 |     };
129 | 
130 |     children: []const Node,
131 | 
132 |     // Find an element child by its tag name
133 |     pub fn elementByTagName(self: Tree, needle: []const u8) ?Node.Elem;
134 |     pub fn elem(self: Tree, needle: []const u8) ?Node.Elem;
135 |     
136 |     // Allocate a slice for all of the element children of a given tag name
137 |     // To free the returned slice, you can just call allocator.free(elements)
138 |     // where 'elements' is the returned slice.
139 |     pub fn elementsByTagNameAlloc(self: Tree, allocator: std.mem.Allocator, needle: []const u8) ![]Node.Elem;
140 |     pub fn elemsAlloc(self: Tree, allocator: std.mem.Allocator, needle: []const u8) ![]Node.Elem;
141 | 
142 |     // Get an element by the value of one of its attributes
143 |     pub fn elementByAttributeValue(self: Tree, needle_name: []const u8, needle_value: []const u8) ?Node.Elem;
144 |     pub fn elemByAttr(self: Tree, needle_name: []const u8, needle_value: []const u8) ?Node.Elem;
145 | 
146 |     // Return the inner text (not including the elements) of the tree. Note that the
147 |     // result will be entirely unformatted.
148 |     pub fn concatTextAlloc(self: Tree, allocator: std.mem.Allocator) ![]const u8;
149 |     // Return the inner text (not including the elements) of the tree but without
150 |     // any whitespace at the start or end.
151 |     pub fn concatTextTrimmedAlloc(self: Tree, allocator: std.mem.Allocator) ![]const u8;
152 | }
153 | ```
154 | 
155 | ### Populate API
156 | Often, it's useful to be able to populate a given struct with values from an XML
157 | document. That is, 'reading' the document into the struct.
158 | 
159 | Dishwasher comes with a shaping API so you can dictate how the document should
160 | be read into the struct. Simply declare an `xml_shape` on the struct:
161 | 
162 | ```zig
163 | const Job = struct {
164 |   title: []const u8,
165 |   start_date: []const u8,
166 |   end_date: []const u8,
167 | }
168 | 
169 | const Person = struct {
170 |     pub const xml_shape = .{
171 |         .name = .content_trimmed,
172 |         .age = .{ .attribute, "age" },
173 |         .jobs = .{ .elements, "job", .{
174 |             .start_date = .{ .attribute, "start_date" },
175 |             .end_date = .{ .attribute, "end_date" },
176 |             .title = .content_trimmed,
177 |             .fired = .attribute_exists,
178 |         } },
179 |         .location = .{
180 |             .one_of,
181 |             .{ .element, "house", .content },
182 |             .{ .element, "work", .content },
183 |             .none,
184 |         },
185 |         .apprentice = .{ .maybe, .{ .element, "apprentice", Person } },
186 |         .children = .{ .elements, "child", Person },
187 |     };
188 | 
189 |     name: []const u8,
190 |     age: []const u8,
191 |     jobs: []struct {
192 |         start_date: []const u8,
193 |         end_date: []const u8,
194 |         title: []const u8,
195 |         fired: bool,
196 |     },
197 |     location: union(enum) {
198 |         house: []const u8,
199 |         work: []const u8,
200 |         none: void,
201 |     },
202 |     apprentice: ?*Person,
203 |     children: []Person,
204 | };
205 | 
206 | pub const Register = struct {
207 |     pub const xml_shape = .{
208 |         .people = .{ .elements, "person", Person },
209 |     };
210 | 
211 |     people: []Person,
212 | };
213 | 
214 | const register = try diswasher.Populate(Register).initFromSlice(allocator, xml_text);
215 | defer register.deinit();
216 | 
217 | // register.value: Register
218 | ```
219 | 
220 | Alternatively, you can populate an existing struct:
221 | ```zig
222 | var register: Register = undefined;
223 | const arena = try dishwasher.Populate(Register).fromSlice(allocator, xml_text, &register);
224 | defer arena.deinit();
225 | ```
226 | 
227 | If you want to own all of your values yourself, use:
228 | ```zig
229 | const owned_tree = dishwasher.parse.fromReader(allocator, file.reader());
230 | defer owned_tree.deinit();
231 | 
232 | const register = try dishwasher.Populate(Register).initFromTreeOwned(allocator, owned_tree.tree);
233 | // free 'register' values yourself..
234 | ```
235 | 
236 | #### Dynamic values
237 | If some field accepts any sort of XML document shape, you can instruct it
238 | to accept a `parse.Tree`:
239 | 
240 | ```zig
241 | const Register = struct {
242 |   pub const xml_shape = .{
243 |     .people = .{ .elements, "person", dishwasher.parse.Tree },
244 |   };
245 | 
246 |   people: []dishwasher.parse.Tree,
247 | };
248 | ```
249 | 
250 | > [!NOTE]
251 | > Note that the tree is not duplicated for you, so if you use the `initFromTreeOwned` method, the values in the tree
252 | > will still belong to the arena that was initialised for the tree.
253 | 
254 | #### Free struct
255 | If you use the `initFromTreeOwned` population method, you can free all of the values in an arena-friendly way with:
256 | ```zig
257 | dishwasher.Populate(Register).deinit(allocator, register);
258 | ```
259 | 
260 | ### Comptime Parsing and Populate API
261 | It could be useful to parse an XML document at compile time, for example
262 | for some inline code generation. While comptime doesn't have allocators,
263 | there's a custom API for this:
264 | 
265 | ```zig
266 | const tree = dishwasher.parse.fromSliceComptime(xml_text);
267 | ```
268 | 
269 | Check out the [Tree API](#tree-api) to know what to do with the returned value.
270 | 
271 | #### Comptime Populate API
272 | If you want to populate a struct at compile time, you can use the `*Comptime` methods
273 | on the `Populate` struct:
274 | ```zig
275 | const register = dishwasher.Populate(Register).initFromSliceComptime(xml_text);
276 | ```
277 | 
278 | > [!NOTE]
279 | > Remember that for the target struct, all pointers need to be `*const T` or
280 | > `[]const T`.
281 | 
282 | ### Scanner API
283 | If you want low-level access to the iterator for lexing an XML document,
284 | you can use the Scanner API, which accepts a slice buffer:
285 | ```zig
286 | var xmlScanner = Scanner.fromSlice(xml_text);
287 | while (try xmlScanner.next()) |token| {
288 |   std.debug.print("token kind: ", .{ token.kind });
289 | }
290 | ```
291 | 
292 | If you have a reader and no access to the entire slice, the Reader API
293 | can connect any reader to the Scanner API so you can lex from a reader:
294 | ```zig
295 | var xmlReader = Scanner.staticBufferReader(file.reader());
296 | while (try xmlScanner.next()) |token| {
297 |   std.debug.print("token kind: ", .{ token.kind });
298 | }
299 | ```
300 | 
301 | > [!NOTE]
302 | > If you're given an error about running out of buffer space, try increase
303 | > the reader buffer size with
304 | > ```zig
305 | > const buffer_size = 4096;
306 | > const XmlFileReader = zigScanner.StaticBufferReader(@TypeOf(file.reader()), buffer_size);
307 | > const xmlReader = XmlFileReader.init(file.reader());
308 | > ```
309 | 
310 | #### Comptime Scanner
311 | The scanner works during compile time without any modification.
312 | 
313 | ## License
314 | All dishwasher code is under the MIT license.
315 | 


--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
  1 | <!doctype html>
  2 | <html>
  3 |   <head>
  4 |     <meta charset="utf-8">
  5 |     <meta name="viewport" content="width=device-width, initial-scale=1.0">
  6 |     <title>Zig Documentation</title>
  7 |     <link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNTMgMTQwIj48ZyBmaWxsPSIjRjdBNDFEIj48Zz48cG9seWdvbiBwb2ludHM9IjQ2LDIyIDI4LDQ0IDE5LDMwIi8+PHBvbHlnb24gcG9pbnRzPSI0NiwyMiAzMywzMyAyOCw0NCAyMiw0NCAyMiw5NSAzMSw5NSAyMCwxMDAgMTIsMTE3IDAsMTE3IDAsMjIiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMzEsOTUgMTIsMTE3IDQsMTA2Ii8+PC9nPjxnPjxwb2x5Z29uIHBvaW50cz0iNTYsMjIgNjIsMzYgMzcsNDQiLz48cG9seWdvbiBwb2ludHM9IjU2LDIyIDExMSwyMiAxMTEsNDQgMzcsNDQgNTYsMzIiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMTE2LDk1IDk3LDExNyA5MCwxMDQiLz48cG9seWdvbiBwb2ludHM9IjExNiw5NSAxMDAsMTA0IDk3LDExNyA0MiwxMTcgNDIsOTUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMTUwLDAgNTIsMTE3IDMsMTQwIDEwMSwyMiIvPjwvZz48Zz48cG9seWdvbiBwb2ludHM9IjE0MSwyMiAxNDAsNDAgMTIyLDQ1Ii8+PHBvbHlnb24gcG9pbnRzPSIxNTMsMjIgMTUzLDExNyAxMDYsMTE3IDEyMCwxMDUgMTI1LDk1IDEzMSw5NSAxMzEsNDUgMTIyLDQ1IDEzMiwzNiAxNDEsMjIiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIvPjxwb2x5Z29uIHBvaW50cz0iMTI1LDk1IDEzMCwxMTAgMTA2LDExNyIvPjwvZz48L2c+PC9zdmc+">
  8 |     <style type="text/css">
  9 |       *, *::before, *::after {
 10 |         box-sizing: border-box;
 11 |       }
 12 |       body {
 13 |         font-family: system-ui, -apple-system, Roboto, "Segoe UI", sans-serif;
 14 |         color: #000000;
 15 |       }
 16 |       .hidden {
 17 |         display: none;
 18 |       }
 19 |       table {
 20 |         width: 100%;
 21 |       }
 22 |       a {
 23 |         color: #2A6286;
 24 |       }
 25 |       pre{
 26 |         font-family:"Source Code Pro",monospace;
 27 |         font-size:1em;
 28 |         background-color:#F5F5F5;
 29 |         padding: 1em;
 30 |         margin: 0;
 31 |         overflow-x: auto;
 32 |       }
 33 |       :not(pre) > code {
 34 |         white-space: break-spaces;
 35 |       }
 36 |       code {
 37 |         font-family:"Source Code Pro",monospace;
 38 |         font-size: 0.9em;
 39 |       }
 40 |       code a {
 41 |         color: #000000;
 42 |       }
 43 |       #listFields > div, #listParams > div {
 44 |         margin-bottom: 1em;
 45 |       }
 46 |       #hdrName a {
 47 |         font-size: 0.7em;
 48 |         padding-left: 1em;
 49 |       }
 50 |       .fieldDocs {
 51 |         border: 1px solid #F5F5F5;
 52 |         border-top: 0px;
 53 |         padding: 1px 1em;
 54 |       }
 55 | 
 56 |       #logo {
 57 |         width: 8em;
 58 |         padding: 0.5em 1em;
 59 |       }
 60 | 
 61 |       #navWrap {
 62 |         width: -moz-available;
 63 |         width: -webkit-fill-available;
 64 |         width: stretch;
 65 |         margin-left: 11em;
 66 |       }
 67 | 
 68 |       #search {
 69 |         width: 100%;
 70 |       }
 71 | 
 72 |       nav {
 73 |         width: 10em;
 74 |         float: left;
 75 |       }
 76 |       nav h2 {
 77 |         font-size: 1.2em;
 78 |         text-decoration: underline;
 79 |         margin: 0;
 80 |         padding: 0.5em 0;
 81 |         text-align: center;
 82 |       }
 83 |       nav p {
 84 |         margin: 0;
 85 |         padding: 0;
 86 |         text-align: center;
 87 |       }
 88 |       section {
 89 |         clear: both;
 90 |         padding-top: 1em;
 91 |       }
 92 |       section h1 {
 93 |         border-bottom: 1px dashed;
 94 |         margin: 0 0;
 95 |       }
 96 |       section h2 {
 97 |         font-size: 1.3em;
 98 |         margin: 0.5em 0;
 99 |         padding: 0;
100 |         border-bottom: 1px solid;
101 |       }
102 |       #listNav {
103 |         list-style-type: none;
104 |         margin: 0.5em 0 0 0;
105 |         padding: 0;
106 |         overflow: hidden;
107 |         background-color: #f1f1f1;
108 |       }
109 |       #listNav li {
110 |         float:left;
111 |       }
112 |       #listNav li a {
113 |         display: block;
114 |         color: #000;
115 |         text-align: center;
116 |         padding: .5em .8em;
117 |         text-decoration: none;
118 |       }
119 |       #listNav li a:hover {
120 |         background-color: #555;
121 |         color: #fff;
122 |       }
123 |       #listNav li a.active {
124 |         background-color: #FFBB4D;
125 |         color: #000;
126 |       }
127 | 
128 |       #helpDialog {
129 |         width: 21em;
130 |         height: 21em;
131 |         position: fixed;
132 |         top: 0;
133 |         left: 0;
134 |         background-color: #333;
135 |         color: #fff;
136 |         border: 1px solid #fff;
137 |       }
138 |       #helpDialog h1 {
139 |         text-align: center;
140 |         font-size: 1.5em;
141 |       }
142 |       #helpDialog dt, #helpDialog dd {
143 |         display: inline;
144 |         margin: 0 0.2em;
145 |       }
146 |       kbd {
147 |         color: #000;
148 |         background-color: #fafbfc;
149 |         border-color: #d1d5da;
150 |         border-bottom-color: #c6cbd1;
151 |         box-shadow-color: #c6cbd1;
152 |         display: inline-block;
153 |         padding: 0.3em 0.2em;
154 |         font: 1.2em monospace;
155 |         line-height: 0.8em;
156 |         vertical-align: middle;
157 |         border: solid 1px;
158 |         border-radius: 3px;
159 |         box-shadow: inset 0 -1px 0;
160 |         cursor: default;
161 |       }
162 | 
163 |       #errors {
164 |         background-color: #faa;
165 |         position: fixed;
166 |         left: 0;
167 |         bottom: 0;
168 |         width: 100%;
169 |         max-height: min(20em, 50vh);
170 |         padding: 0.5em;
171 |         overflow: auto;
172 |       }
173 |       #errors h1 {
174 |         font-size: 1.5em;
175 |       }
176 |       #errors pre {
177 |         background-color: #fcc;
178 |       }
179 | 
180 |       #listSearchResults li.selected {
181 |         background-color: #93e196;
182 |       }
183 | 
184 |       #tableFnErrors dt {
185 |         font-weight: bold;
186 |       }
187 | 
188 |       dl > div {
189 |           padding: 0.5em;
190 |           border: 1px solid #c0c0c0;
191 |           margin-top: 0.5em;
192 |       }
193 | 
194 |       td, th {
195 |         text-align: unset;
196 |         vertical-align: top;
197 |         margin: 0;
198 |         padding: 0.5em;
199 |         max-width: 20em;
200 |         text-overflow: ellipsis;
201 |         overflow-x: hidden;
202 |       }
203 | 
204 |       ul.columns {
205 |         column-width: 20em;
206 |       }
207 | 
208 |       .tok-kw {
209 |           color: #333;
210 |           font-weight: bold;
211 |       }
212 |       .tok-str {
213 |           color: #d14;
214 |       }
215 |       .tok-builtin {
216 |           color: #0086b3;
217 |       }
218 |       .tok-comment {
219 |           color: #777;
220 |           font-style: italic;
221 |       }
222 |       .tok-fn {
223 |           color: #900;
224 |           font-weight: bold;
225 |       }
226 |       .tok-null {
227 |           color: #008080;
228 |       }
229 |       .tok-number {
230 |           color: #008080;
231 |       }
232 |       .tok-type {
233 |           color: #458;
234 |           font-weight: bold;
235 |       }
236 | 
237 |       @media (prefers-color-scheme: dark) {
238 |         body {
239 |           background-color: #111;
240 |           color: #bbb;
241 |         }
242 |         pre {
243 |           background-color: #222;
244 |           color: #ccc;
245 |         }
246 |         a {
247 |           color: #88f;
248 |         }
249 |         code a {
250 |           color: #ccc;
251 |         }
252 |         .fieldDocs {
253 |           border-color:#2A2A2A;
254 |         }
255 |         #listNav {
256 |           background-color: #333;
257 |         }
258 |         #listNav li a {
259 |           color: #fff;
260 |         }
261 |         #listNav li a:hover {
262 |           background-color: #555;
263 |           color: #fff;
264 |         }
265 |         #listNav li a.active {
266 |           background-color: #FFBB4D;
267 |           color: #000;
268 |         }
269 |         #listSearchResults li.selected {
270 |           background-color: #000;
271 |         }
272 |         #listSearchResults li.selected a {
273 |           color: #fff;
274 |         }
275 |         #errors {
276 |           background-color: #800;
277 |           color: #fff;
278 |         }
279 |         #errors pre {
280 |           background-color: #a00;
281 |           color: #fff;
282 |         }
283 |         dl > div {
284 |           border-color: #373737;
285 |         }
286 |         .tok-kw {
287 |             color: #eee;
288 |         }
289 |         .tok-str {
290 |             color: #2e5;
291 |         }
292 |         .tok-builtin {
293 |             color: #ff894c;
294 |         }
295 |         .tok-comment {
296 |             color: #aa7;
297 |         }
298 |         .tok-fn {
299 |             color: #B1A0F8;
300 |         }
301 |         .tok-null {
302 |             color: #ff8080;
303 |         }
304 |         .tok-number {
305 |             color: #ff8080;
306 |         }
307 |         .tok-type {
308 |             color: #68f;
309 |         }
310 |       }
311 |     </style>
312 |   </head>
313 |   <body>
314 |     <nav>
315 |       <a class="logo" href="#">
316 |         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 140">
317 |         <g fill="#F7A41D">
318 |           <g>
319 |             <polygon points="46,22 28,44 19,30"/>
320 |             <polygon points="46,22 33,33 28,44 22,44 22,95 31,95 20,100 12,117 0,117 0,22" shape-rendering="crispEdges"/>
321 |             <polygon points="31,95 12,117 4,106"/>
322 |           </g>
323 |           <g>
324 |             <polygon points="56,22 62,36 37,44"/>
325 |             <polygon points="56,22 111,22 111,44 37,44 56,32" shape-rendering="crispEdges"/>
326 |             <polygon points="116,95 97,117 90,104"/>
327 |             <polygon points="116,95 100,104 97,117 42,117 42,95" shape-rendering="crispEdges"/>
328 |             <polygon points="150,0 52,117 3,140 101,22"/>
329 |           </g>
330 |           <g>
331 |             <polygon points="141,22 140,40 122,45"/>
332 |             <polygon points="153,22 153,117 106,117 120,105 125,95 131,95 131,45 122,45 132,36 141,22" shape-rendering="crispEdges"/>
333 |             <polygon points="125,95 130,110 106,117"/>
334 |           </g>
335 |         </g>
336 |         <style>
337 |         #text { fill: #121212 }
338 |         @media (prefers-color-scheme: dark) { #text { fill: #f2f2f2 } }
339 |         </style>
340 |         <g id="text">
341 |           <g>
342 |             <polygon points="260,22 260,37 229,40 177,40 177,22" shape-rendering="crispEdges"/>
343 |             <polygon points="260,37 207,99 207,103 176,103 229,40 229,37"/>
344 |             <polygon points="261,99 261,117 176,117 176,103 206,99" shape-rendering="crispEdges"/>
345 |           </g>
346 |           <rect x="272" y="22" shape-rendering="crispEdges" width="22" height="95"/>
347 |           <g>
348 |             <polygon points="394,67 394,106 376,106 376,81 360,70 346,67" shape-rendering="crispEdges"/>
349 |             <polygon points="360,68 376,81 346,67"/>
350 |             <path d="M394,106c-10.2,7.3-24,12-37.7,12c-29,0-51.1-20.8-51.1-48.3c0-27.3,22.5-48.1,52-48.1    c14.3,0,29.2,5.5,38.9,14l-13,15c-7.1-6.3-16.8-10-25.9-10c-17,0-30.2,12.9-30.2,29.5c0,16.8,13.3,29.6,30.3,29.6    c5.7,0,12.8-2.3,19-5.5L394,106z"/>
351 |           </g>
352 |         </g>
353 |         </svg>
354 |       </a>
355 |     </nav>
356 |     <div id="navWrap">
357 |       <input type="search" id="search" autocomplete="off" spellcheck="false" placeholder="`s` to search, `?` to see more options">
358 |       <div id="sectNav" class="hidden"><ul id="listNav"></ul></div>
359 |     </div>
360 |     <section>
361 |     <p id="status">Loading...</p>
362 |     <h1 id="hdrName" class="hidden"><span></span><a href="#">[src]</a></h1>
363 |     <div id="fnProto" class="hidden">
364 |       <pre><code id="fnProtoCode"></code></pre>
365 |     </div>
366 |     <div id="tldDocs" class="hidden"></div>
367 |     <div id="sectParams" class="hidden">
368 |       <h2>Parameters</h2>
369 |       <div id="listParams">
370 |       </div>
371 |     </div>
372 |     <div id="sectFnErrors" class="hidden">
373 |       <h2>Errors</h2>
374 |       <div id="fnErrorsAnyError">
375 |         <p><span class="tok-type">anyerror</span> means the error set is known only at runtime.</p>
376 |       </div>
377 |       <div id="tableFnErrors"><dl id="listFnErrors"></dl></div>
378 |     </div>
379 |     <div id="sectSearchResults" class="hidden">
380 |       <h2>Search Results</h2>
381 |       <ul id="listSearchResults"></ul>
382 |     </div>
383 |     <div id="sectSearchNoResults" class="hidden">
384 |       <h2>No Results Found</h2>
385 |       <p>Press escape to exit search and then '?' to see more options.</p>
386 |     </div>
387 |     <div id="sectFields" class="hidden">
388 |       <h2>Fields</h2>
389 |       <div id="listFields">
390 |       </div>
391 |     </div>
392 |     <div id="sectTypes" class="hidden">
393 |       <h2>Types</h2>
394 |       <ul id="listTypes" class="columns">
395 |       </ul>
396 |     </div>
397 |     <div id="sectNamespaces" class="hidden">
398 |       <h2>Namespaces</h2>
399 |       <ul id="listNamespaces" class="columns">
400 |       </ul>
401 |     </div>
402 |     <div id="sectGlobalVars" class="hidden">
403 |       <h2>Global Variables</h2>
404 |       <table>
405 |         <tbody id="listGlobalVars">
406 |         </tbody>
407 |       </table>
408 |     </div>
409 |     <div id="sectValues" class="hidden">
410 |       <h2>Values</h2>
411 |       <table>
412 |         <tbody id="listValues">
413 |         </tbody>
414 |       </table>
415 |     </div>
416 |     <div id="sectFns" class="hidden">
417 |       <h2>Functions</h2>
418 |       <dl id="listFns">
419 |       </dl>
420 |     </div>
421 |     <div id="sectErrSets" class="hidden">
422 |       <h2>Error Sets</h2>
423 |       <ul id="listErrSets" class="columns">
424 |       </ul>
425 |     </div>
426 |     <div id="sectDocTests" class="hidden">
427 |       <h2>Example Usage</h2>
428 |       <pre><code id="docTestsCode"></code></pre>
429 |     </div>
430 |     <div id="sectSource" class="hidden">
431 |       <h2>Source Code</h2>
432 |       <pre><code id="sourceText"></code></pre>
433 |     </div>
434 |     </section>
435 |     <div id="helpDialog" class="hidden">
436 |       <h1>Keyboard Shortcuts</h1>
437 |       <dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd></dl>
438 |       <dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this dialog</dd></dl>
439 |       <dl><dt><kbd>s</kbd></dt><dd>Focus the search field</dd></dl>
440 |       <dl><dt><kbd>u</kbd></dt><dd>Go to source code</dd></dl>
441 |       <dl><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd></dl>
442 |       <dl><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd></dl>
443 |       <dl><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd></dl>
444 |     </div>
445 |     <div id="errors" class="hidden">
446 |       <h1>Errors</h1>
447 |       <pre id="errorsText"></pre>
448 |     </div>
449 |     <script src="main.js"></script>
450 |   </body>
451 | </html>
452 | 


--------------------------------------------------------------------------------
/src/Scanner.zig:
--------------------------------------------------------------------------------
  1 | const std = @import("std");
  2 | 
  3 | const Scanner = @This();
  4 | 
  5 | pub const Error = error{
  6 |     UnexpectedToken,
  7 | };
  8 | 
  9 | pub const State = union(enum) {
 10 |     pub const TagState = union(enum) {
 11 |         next_attribute: void,
 12 |         attribute_value: void,
 13 |     };
 14 | 
 15 |     pub const Cdata = struct {};
 16 | 
 17 |     default: void,
 18 |     comment: void,
 19 |     meta: TagState,
 20 |     elem: TagState,
 21 |     cdata: Cdata,
 22 | };
 23 | 
 24 | pub const Token = struct {
 25 |     pub const Kind = enum {
 26 |         element_open,
 27 |         element_close,
 28 |         element_children_end,
 29 |         element_self_end,
 30 |         element_attribute,
 31 |         element_attribute_value,
 32 |         comment_open,
 33 |         comment_close,
 34 |         cdata_open,
 35 |         cdata_close,
 36 |         meta_attribute,
 37 |         meta_attribute_value,
 38 |         doctype,
 39 |         text_chunk,
 40 |     };
 41 | 
 42 |     kind: Kind,
 43 |     inner: []const u8,
 44 |     start_pos: usize,
 45 |     end_pos: usize,
 46 | };
 47 | 
 48 | // adapted from https://ziglang.org/documentation/master/std/#std.Io.Reader.peekDelimiterInclusive
 49 | pub fn peekDelimiterAnyInclusive(r: *std.Io.Reader, delimiters: []const u8) std.Io.Reader.DelimiterError![]u8 {
 50 |     {
 51 |         const contents = r.buffer[0..r.end];
 52 |         const seek = r.seek;
 53 |         if (std.mem.findAnyPos(u8, contents, seek, delimiters)) |end| {
 54 |             @branchHint(.likely);
 55 |             return contents[seek .. end + 1];
 56 |         }
 57 |     }
 58 |     while (true) {
 59 |         const content_len = r.end - r.seek;
 60 |         if (r.buffer.len - content_len == 0) break;
 61 |         try r.fillMore();
 62 |         const seek = r.seek;
 63 |         const contents = r.buffer[0..r.end];
 64 |         if (std.mem.findAnyPos(u8, contents, seek + content_len, delimiters)) |end| {
 65 |             return contents[seek .. end + 1];
 66 |         }
 67 |     }
 68 |     var failing_writer = std.Io.Writer.failing;
 69 |     while (r.vtable.stream(r, &failing_writer, .limited(1))) |n| {
 70 |         std.debug.assert(n == 0);
 71 |     } else |err| switch (err) {
 72 |         error.WriteFailed => return error.StreamTooLong,
 73 |         error.ReadFailed => |e| return e,
 74 |         error.EndOfStream => |e| return e,
 75 |     }
 76 | }
 77 | 
 78 | // adapted from https://ziglang.org/documentation/master/std/#std.Io.Reader.peekDelimiterExclusive
 79 | fn peekDelimiterAnyExclusive(r: *std.Io.Reader, delimiter: []const u8) std.Io.Reader.DelimiterError![]u8 {
 80 |     const result = peekDelimiterAnyInclusive(r, delimiter) catch |err| switch (err) {
 81 |         error.EndOfStream => {
 82 |             const remaining = r.buffer[r.seek..r.end];
 83 |             if (remaining.len == 0) return error.EndOfStream;
 84 |             return remaining;
 85 |         },
 86 |         else => |e| return e,
 87 |     };
 88 |     return result[0 .. result.len - 1];
 89 | }
 90 | 
 91 | // adapted from https://ziglang.org/documentation/master/std/#std.Io.Reader.takeDelimiterExclusive
 92 | fn takeDelimiterAnyExclusive(r: *std.Io.Reader, delimiter: []const u8) std.Io.Reader.DelimiterError![]u8 {
 93 |     const result = try peekDelimiterAnyExclusive(r, delimiter);
 94 |     r.toss(result.len);
 95 |     return result;
 96 | }
 97 | 
 98 | reader: *std.Io.Reader,
 99 | 
100 | global_cursor: usize = 0,
101 | state: State = .default,
102 | 
103 | fn canPeekBytes(self: *Scanner, num_bytes: usize) !bool {
104 |     self.reader.fill(num_bytes) catch |e| switch (e) {
105 |         error.EndOfStream => return false,
106 |         else => return e,
107 |     };
108 |     return true;
109 | }
110 | 
111 | pub fn next(self: *Scanner) !?Token {
112 |     return self.nextImpl() catch |e| switch (e) {
113 |         error.EndOfStream => return null,
114 |         else => return e,
115 |     };
116 | }
117 | 
118 | fn nextImpl(self: *Scanner) !?Token {
119 |     var start_pos = self.global_cursor;
120 |     switch (self.state) {
121 |         .default => {
122 |             if (try self.reader.peekByte() == '<') {
123 |                 if (std.mem.eql(u8, try self.reader.peek(1), "<")) {
124 |                     self.reader.toss(1);
125 | 
126 |                     if (std.mem.eql(u8, try self.reader.peek(1), "/")) {
127 |                         self.reader.toss(1);
128 | 
129 |                         const tag_name = try self.reader.takeDelimiterExclusive('>');
130 |                         self.state = .default;
131 | 
132 |                         self.reader.toss(1);
133 | 
134 |                         return .{
135 |                             .kind = .element_children_end,
136 |                             .inner = tag_name,
137 |                             .start_pos = start_pos,
138 |                             .end_pos = self.global_cursor,
139 |                         };
140 |                     }
141 | 
142 |                     if (try self.canPeekBytes(3) and std.mem.eql(u8, try self.reader.peek(3), "!--")) {
143 |                         self.reader.toss(3);
144 |                         self.state = .comment;
145 | 
146 |                         return .{
147 |                             .kind = .comment_open,
148 |                             .inner = &.{},
149 |                             .start_pos = start_pos,
150 |                             .end_pos = self.global_cursor,
151 |                         };
152 |                     }
153 | 
154 |                     if (try self.canPeekBytes(4) and std.mem.eql(u8, try self.reader.peek(4), "?xml")) {
155 |                         self.reader.toss(4);
156 |                         self.state = .{ .meta = .next_attribute };
157 | 
158 |                         return try self.nextImpl();
159 |                     }
160 | 
161 |                     if (try self.canPeekBytes(8) and std.mem.eql(u8, try self.reader.peek(8), "!DOCTYPE")) {
162 |                         self.reader.toss(8);
163 |                         self.state = .{ .elem = .next_attribute };
164 | 
165 |                         return try self.nextImpl();
166 |                     }
167 | 
168 |                     if (try self.canPeekBytes(8) and std.mem.eql(u8, try self.reader.peek(8), "![CDATA[")) {
169 |                         self.reader.toss(8);
170 |                         self.state = .{ .cdata = .{} };
171 | 
172 |                         return .{
173 |                             .kind = .cdata_open,
174 |                             .inner = &.{},
175 |                             .start_pos = start_pos,
176 |                             .end_pos = self.global_cursor,
177 |                         };
178 |                     }
179 | 
180 |                     const tag_name = try takeDelimiterAnyExclusive(self.reader, " \n\r/>");
181 |                     if (tag_name.len == 0) return error.UnexpectedToken;
182 |                     self.state = .{ .elem = .next_attribute };
183 | 
184 |                     return .{
185 |                         .kind = .element_open,
186 |                         .inner = tag_name,
187 |                         .start_pos = start_pos,
188 |                         .end_pos = self.global_cursor,
189 |                     };
190 |                 }
191 |             }
192 | 
193 |             if (self.reader.buffered().len == 0) {
194 |                 try self.reader.fillMore();
195 |             }
196 | 
197 |             const text_chunk = self.reader.peekDelimiterExclusive('<') catch |e| switch (e) {
198 |                 error.StreamTooLong => try self.reader.peek(self.reader.buffered().len),
199 |                 else => return e,
200 |             };
201 | 
202 |             self.reader.toss(text_chunk.len);
203 | 
204 |             return .{
205 |                 .kind = .text_chunk,
206 |                 .inner = text_chunk,
207 |                 .start_pos = start_pos,
208 |                 .end_pos = self.global_cursor,
209 |             };
210 |         },
211 |         .comment => {
212 |             if (std.mem.eql(u8, try self.reader.peek(3), "-->")) {
213 |                 self.reader.toss(3);
214 |                 self.state = .default;
215 | 
216 |                 return .{
217 |                     .kind = .comment_close,
218 |                     .inner = &.{},
219 |                     .start_pos = start_pos,
220 |                     .end_pos = self.global_cursor,
221 |                 };
222 |             }
223 | 
224 |             if (try self.reader.peekByte() == '-') {
225 |                 return .{
226 |                     .kind = .text_chunk,
227 |                     .inner = try self.reader.take(1),
228 |                     .start_pos = start_pos,
229 |                     .end_pos = self.global_cursor,
230 |                 };
231 |             }
232 | 
233 |             const text_chunk = self.reader.peekDelimiterExclusive('-') catch |e| switch (e) {
234 |                 error.StreamTooLong => try self.reader.peek(self.reader.buffered().len),
235 |                 else => return e,
236 |             };
237 | 
238 |             self.reader.toss(text_chunk.len);
239 | 
240 |             return .{
241 |                 .kind = .text_chunk,
242 |                 .inner = text_chunk,
243 |                 .start_pos = start_pos,
244 |                 .end_pos = self.global_cursor,
245 |             };
246 |         },
247 |         inline .elem, .meta => |elem_state| {
248 |             // remove whitespace
249 |             while (true) {
250 |                 const char = try self.reader.peekByte();
251 |                 switch (char) {
252 |                     ' ', '\n', '\r' => self.reader.toss(1),
253 |                     else => break,
254 |                 }
255 |             }
256 | 
257 |             start_pos = self.global_cursor;
258 |             switch (self.state) {
259 |                 .elem => {
260 |                     if (std.mem.eql(u8, try self.reader.peek(2), "/>")) {
261 |                         self.reader.toss(2);
262 |                         self.state = .default;
263 | 
264 |                         return .{
265 |                             .kind = .element_self_end,
266 |                             .inner = &.{},
267 |                             .start_pos = start_pos,
268 |                             .end_pos = self.global_cursor,
269 |                         };
270 |                     }
271 | 
272 |                     if (try self.reader.peekByte() == '>') {
273 |                         self.reader.toss(1);
274 |                         self.state = .default;
275 | 
276 |                         return .{
277 |                             .kind = .element_close,
278 |                             .inner = &.{},
279 |                             .start_pos = start_pos,
280 |                             .end_pos = self.global_cursor,
281 |                         };
282 |                     }
283 |                 },
284 |                 .meta => {
285 |                     if (std.mem.eql(u8, try self.reader.peek(2), "?>")) {
286 |                         self.reader.toss(2);
287 |                         self.state = .default;
288 | 
289 |                         return try self.nextImpl();
290 |                     }
291 |                 },
292 |                 else => unreachable,
293 |             }
294 | 
295 |             switch (elem_state) {
296 |                 .next_attribute => {
297 |                     const attr_name = try takeDelimiterAnyExclusive(self.reader, " \n\r=/>");
298 |                     if (attr_name.len == 0) return error.UnexpectedToken;
299 | 
300 |                     // remove whitespace
301 |                     while (true) {
302 |                         const char = try self.reader.peekByte();
303 |                         switch (char) {
304 |                             ' ', '\n', '\r' => self.reader.toss(1),
305 |                             else => break,
306 |                         }
307 |                     }
308 | 
309 |                     const name_end_pos = self.global_cursor;
310 | 
311 |                     const has_value = try self.reader.peekByte() == '=';
312 |                     if (has_value) {
313 |                         self.reader.toss(1);
314 |                     }
315 | 
316 |                     self.state = switch (self.state) {
317 |                         .elem => .{ .elem = if (has_value) .attribute_value else .next_attribute },
318 |                         .meta => .{ .meta = if (has_value) .attribute_value else .next_attribute },
319 |                         else => unreachable,
320 |                     };
321 | 
322 |                     return .{
323 |                         .kind = switch (self.state) {
324 |                             .elem => .element_attribute,
325 |                             .meta => .meta_attribute,
326 |                             else => unreachable,
327 |                         },
328 |                         .inner = attr_name,
329 |                         .start_pos = start_pos,
330 |                         .end_pos = name_end_pos,
331 |                     };
332 |                 },
333 |                 .attribute_value => {
334 |                     const peek = try self.reader.peekByte();
335 |                     if (peek == '"' or peek == '\'') {
336 |                         self.reader.toss(1);
337 | 
338 |                         const attr_value = try self.reader.takeDelimiterExclusive(peek);
339 |                         self.reader.toss(1);
340 | 
341 |                         self.state = switch (self.state) {
342 |                             .elem => .{ .elem = .next_attribute },
343 |                             .meta => .{ .meta = .next_attribute },
344 |                             else => unreachable,
345 |                         };
346 | 
347 |                         return .{
348 |                             .kind = switch (self.state) {
349 |                                 .elem => .element_attribute_value,
350 |                                 .meta => .meta_attribute_value,
351 |                                 else => unreachable,
352 |                             },
353 |                             .inner = attr_value,
354 |                             .start_pos = start_pos,
355 |                             .end_pos = self.global_cursor,
356 |                         };
357 |                     }
358 | 
359 |                     const attr_value = try takeDelimiterAnyExclusive(self.reader, " \n\r/>?");
360 |                     if (attr_value.len == 0) return error.UnexpectedToken;
361 | 
362 |                     return .{
363 |                         .kind = switch (self.state) {
364 |                             .elem => .element_attribute_value,
365 |                             .meta => .meta_attribute_value,
366 |                             else => unreachable,
367 |                         },
368 |                         .inner = attr_value,
369 |                         .start_pos = start_pos,
370 |                         .end_pos = self.global_cursor,
371 |                     };
372 |                 },
373 |             }
374 |         },
375 |         .cdata => {
376 |             if (std.mem.eql(u8, try self.reader.peek(3), "]]>")) {
377 |                 self.reader.toss(3);
378 |                 self.state = .default;
379 | 
380 |                 return .{
381 |                     .kind = .cdata_close,
382 |                     .inner = &.{},
383 |                     .start_pos = start_pos,
384 |                     .end_pos = self.global_cursor,
385 |                 };
386 |             }
387 | 
388 |             if (try self.reader.peekByte() == ']') {
389 |                 return .{
390 |                     .kind = .text_chunk,
391 |                     .inner = try self.reader.take(1),
392 |                     .start_pos = start_pos,
393 |                     .end_pos = self.global_cursor,
394 |                 };
395 |             }
396 | 
397 |             const text_chunk = self.reader.peekDelimiterExclusive(']') catch |e| switch (e) {
398 |                 error.StreamTooLong => try self.reader.peek(self.reader.buffered().len),
399 |                 else => return e,
400 |             };
401 | 
402 |             self.reader.toss(text_chunk.len);
403 | 
404 |             return .{
405 |                 .kind = .text_chunk,
406 |                 .inner = text_chunk,
407 |                 .start_pos = start_pos,
408 |                 .end_pos = self.global_cursor,
409 |             };
410 |         },
411 |     }
412 |     return null;
413 | }
414 | 


--------------------------------------------------------------------------------
/src/populate.zig:
--------------------------------------------------------------------------------
  1 | const std = @import("std");
  2 | const parse = @import("./parse.zig");
  3 | 
  4 | const Tree = parse.Tree;
  5 | 
  6 | pub const ContentError = error{
  7 |     MissingAttribute,
  8 |     MissingAttributeValue,
  9 |     MissingChild,
 10 |     MissingOption,
 11 |     MissingCdata,
 12 | };
 13 | 
 14 | pub const Mode = enum {
 15 |     compile_time,
 16 |     run_time,
 17 | };
 18 | 
 19 | fn PopulateShape(comptime T: type, comptime shape: anytype) type {
 20 |     // The format method, internally called by `std.fmt.comptimePrint` up to the Zig
 21 |     // compiler version 0.14.x, had a eval branch quota of two million (2_000_000).
 22 |     //    see: https://github.com/ziglang/zig/blob/6d1f0eca773e688c802e441589495b7bde2f9e3f/lib/std/fmt.zig#L100
 23 |     // Since Zig compiler version 0.15.1 `std.fmt.comptimePrint` uses the new IO API. This means
 24 |     // that `std.fmt.format` was deprecated in favor of `Writer.print`. Due to this change the eval branch quota for
 25 |     // `comptimePrint` is the default (1_000). This is way to small for the data structures usually passed via `shape`.
 26 |     // To fix this we set the eval branch quota ourself, using the quota previously set by `std.fmt.format`.
 27 |     @setEvalBranchQuota(2_000_000);
 28 | 
 29 |     const dest_type_info: std.builtin.Type = @typeInfo(T);
 30 |     const ShapeType = @TypeOf(shape);
 31 |     const shape_type_info = @typeInfo(ShapeType);
 32 | 
 33 |     const shape_print = std.fmt.comptimePrint("{}", .{shape});
 34 |     const cannot_be_applied = "Shape " ++ shape_print ++ " cannot be applied to type " ++ @typeName(T);
 35 | 
 36 |     return struct {
 37 |         /// Represents an instance of the struct to populate along with the source parsed XML tree
 38 |         /// with an arena containing all allocations.
 39 |         pub const OwnedDocument = struct {
 40 |             /// The source parsed XML tree with an arena containing all allocations.
 41 |             owned_tree: Tree.Owned,
 42 |             /// The created struct instance, populated with XML data.
 43 |             value: T,
 44 | 
 45 |             pub fn deinit(self: OwnedDocument) void {
 46 |                 self.owned_tree.deinit();
 47 |             }
 48 |         };
 49 | 
 50 |         pub fn deinit(allocator: std.mem.Allocator, val: T) void {
 51 |             switch (shape_type_info) {
 52 |                 .type => {
 53 |                     if (shape == Tree) {
 54 |                         return;
 55 |                     }
 56 |                     if (dest_type_info == .pointer and dest_type_info.pointer.size == .one) {
 57 |                         Populate(shape).deinit(allocator, val.*);
 58 |                         allocator.destroy(val);
 59 |                         return;
 60 |                     }
 61 |                     Populate(shape).deinit(allocator, val);
 62 |                 },
 63 |                 .@"struct" => |struct_info| {
 64 |                     if (struct_info.is_tuple) {
 65 |                         if (struct_info.fields.len == 2 and shape[0] == .attribute) {
 66 |                             allocator.free(val);
 67 |                         } else if (struct_info.fields.len == 2 and shape[0] == .attribute_exists) {
 68 |                             // no free
 69 |                         } else if (struct_info.fields.len == 2 and shape[0] == .maybe) {
 70 |                             const ChildType = dest_type_info.optional.child;
 71 |                             const child_shape = shape[1];
 72 |                             if (val) |non_null| {
 73 |                                 PopulateShape(ChildType, child_shape).deinit(allocator, non_null);
 74 |                             }
 75 |                         } else if (struct_info.fields.len == 3 and shape[0] == .elements) {
 76 |                             const ChildType = dest_type_info.pointer.child;
 77 |                             const child_shape = shape[2];
 78 | 
 79 |                             var i = val.len;
 80 |                             while (i > 0) {
 81 |                                 i -= 1;
 82 |                                 PopulateShape(ChildType, child_shape).deinit(allocator, val[i]);
 83 |                             }
 84 |                             allocator.free(val);
 85 |                         } else if (struct_info.fields.len == 3 and shape[0] == .element) {
 86 |                             const child_shape = shape[2];
 87 |                             PopulateShape(T, child_shape).deinit(allocator, val);
 88 |                         } else if (struct_info.fields.len == 2 and shape[0] == .cdata) {
 89 |                             allocator.free(val);
 90 |                         } else if (struct_info.fields.len > 2 and shape[0] == .one_of) {
 91 |                             const union_fields = dest_type_info.@"union".fields;
 92 |                             inline for (union_fields, 0..) |field, i| {
 93 |                                 const child_shape = shape[1 + i];
 94 |                                 if (std.mem.eql(u8, @tagName(val), field.name)) {
 95 |                                     PopulateShape(field.type, child_shape)
 96 |                                         .deinit(allocator, @field(val, field.name));
 97 |                                 }
 98 |                             }
 99 |                         } else {
100 |                             @compileError("Unknown shape: " ++ shape_print);
101 |                         }
102 |                     } else {
103 |                         const struct_fields = dest_type_info.@"struct".fields;
104 |                         const shape_fields = struct_info.fields;
105 | 
106 |                         comptime var i: usize = shape_fields.len;
107 |                         inline while (i > 0) {
108 |                             i -= 1;
109 |                             const shape_field = shape_fields[i];
110 |                             const base_field = comptime for (struct_fields) |field| {
111 |                                 if (std.mem.eql(u8, field.name, shape_field.name)) {
112 |                                     break field;
113 |                                 }
114 |                             } else @compileError("Missing field '" ++ shape_field.name ++ "' on base type " ++ @typeName(T));
115 | 
116 |                             const shape_field_val = @field(shape, shape_field.name);
117 |                             PopulateShape(base_field.type, shape_field_val)
118 |                                 .deinit(allocator, @field(val, base_field.name));
119 |                         }
120 |                     }
121 |                 },
122 |                 .enum_literal => {
123 |                     if (shape == .content or shape == .content_trimmed) {
124 |                         allocator.free(val);
125 |                     }
126 |                 },
127 |                 else => @compileError("Unknown shape type " ++ shape_print),
128 |             }
129 |         }
130 | 
131 |         fn fromTreeImpl(
132 |             comptime mode: Mode,
133 |             allocator: std.mem.Allocator,
134 |             tree: Tree,
135 |             attributes: []const Tree.Node.Elem.Attr,
136 |             val: *T,
137 |         ) (std.mem.Allocator.Error || ContentError)!void {
138 |             switch (shape_type_info) {
139 |                 .type => {
140 |                     if (shape == Tree) {
141 |                         if (T != Tree) {
142 |                             @compileError(cannot_be_applied ++ ", must be the Tree type");
143 |                         }
144 |                         val.* = tree;
145 |                         return;
146 |                     }
147 |                     if (dest_type_info == .pointer and dest_type_info.pointer.size == .one) {
148 |                         const child_type = dest_type_info.pointer.child;
149 |                         switch (mode) {
150 |                             .compile_time => {
151 |                                 if (!dest_type_info.pointer.is_const) {
152 |                                     @compileError(cannot_be_applied ++ ", must be a const pointer when populating at compile time");
153 |                                 }
154 |                                 val.* = &try Populate(shape).initFromTreeImpl(
155 |                                     mode,
156 |                                     allocator,
157 |                                     tree,
158 |                                     attributes,
159 |                                 );
160 |                             },
161 |                             .run_time => {
162 |                                 const out = try allocator.create(child_type);
163 |                                 errdefer allocator.destroy(out);
164 | 
165 |                                 out.* = try Populate(shape).initFromTreeImpl(
166 |                                     mode,
167 |                                     allocator,
168 |                                     tree,
169 |                                     attributes,
170 |                                 );
171 | 
172 |                                 val.* = out;
173 |                             },
174 |                         }
175 |                         return;
176 |                     }
177 |                     if (T != shape) {
178 |                         @compileError(cannot_be_applied);
179 |                     }
180 |                     val.* = try Populate(shape).initFromTreeImpl(
181 |                         mode,
182 |                         allocator,
183 |                         tree,
184 |                         attributes,
185 |                     );
186 |                 },
187 |                 .@"struct" => |struct_info| {
188 |                     if (struct_info.is_tuple) {
189 |                         if (struct_info.fields.len == 2 and shape[0] == .attribute) {
190 |                             if (T != []const u8 and T != []u8) {
191 |                                 @compileError(cannot_be_applied ++ ", must be a string type");
192 |                             }
193 | 
194 |                             val.* = for (attributes) |attribute| {
195 |                                 if (std.mem.eql(u8, attribute.name, shape[1])) {
196 |                                     const value = attribute.value orelse return ContentError.MissingAttributeValue;
197 |                                     break switch (mode) {
198 |                                         .compile_time => value,
199 |                                         .run_time => try allocator.dupe(u8, value),
200 |                                     };
201 |                                 }
202 |                             } else return ContentError.MissingAttribute;
203 |                         } else if (struct_info.fields.len == 2 and shape[0] == .attribute_exists) {
204 |                             if (T != bool) {
205 |                                 @compileError(cannot_be_applied ++ ", must be a boolean type");
206 |                             }
207 | 
208 |                             val.* = for (attributes) |attribute| {
209 |                                 if (std.mem.eql(u8, attribute.name, shape[1])) {
210 |                                     break true;
211 |                                 }
212 |                             } else if (T == bool) false;
213 |                         } else if (struct_info.fields.len == 2 and shape[0] == .maybe) {
214 |                             if (dest_type_info != .optional) {
215 |                                 @compileError(cannot_be_applied ++ ", must be optional");
216 |                             }
217 | 
218 |                             const ChildType = dest_type_info.optional.child;
219 |                             const child_shape = shape[1];
220 | 
221 |                             val.* = PopulateShape(ChildType, child_shape).initFromTreeImpl(
222 |                                 mode,
223 |                                 allocator,
224 |                                 tree,
225 |                                 attributes,
226 |                             ) catch |e| switch (e) {
227 |                                 error.MissingAttribute,
228 |                                 error.MissingAttributeValue,
229 |                                 error.MissingChild,
230 |                                 error.MissingOption,
231 |                                 => null,
232 |                                 else => return e,
233 |                             };
234 |                         } else if (struct_info.fields.len == 3 and shape[0] == .elements) {
235 |                             if (dest_type_info != .pointer or dest_type_info.pointer.size != .slice) {
236 |                                 @compileError(cannot_be_applied ++ ", must be a slice type");
237 |                             }
238 | 
239 |                             const ChildType = dest_type_info.pointer.child;
240 | 
241 |                             const tag_name = shape[1];
242 |                             const child_shape = shape[2];
243 | 
244 |                             switch (mode) {
245 |                                 .compile_time => {
246 |                                     if (!dest_type_info.pointer.is_const) {
247 |                                         @compileError(cannot_be_applied ++ ", must be a const slice when populating at compile time");
248 |                                     }
249 | 
250 |                                     var result: []const ChildType = &.{};
251 | 
252 |                                     for (tree.children) |child| {
253 |                                         switch (child) {
254 |                                             .elem => |elem_child| {
255 |                                                 if (std.mem.eql(u8, elem_child.tag_name, tag_name)) {
256 |                                                     result = result ++ .{try PopulateShape(ChildType, child_shape).initFromTreeImpl(
257 |                                                         mode,
258 |                                                         allocator,
259 |                                                         elem_child.tree orelse .{ .children = &.{} },
260 |                                                         elem_child.attributes,
261 |                                                     )};
262 |                                                 }
263 |                                             },
264 |                                             else => {},
265 |                                         }
266 |                                     }
267 |                                     val.* = result;
268 |                                 },
269 |                                 .run_time => {
270 |                                     var result = std.array_list.Managed(ChildType).init(allocator);
271 |                                     errdefer result.deinit();
272 |                                     errdefer {
273 |                                         for (result.items) |item| {
274 |                                             PopulateShape(ChildType, child_shape).deinit(allocator, item);
275 |                                         }
276 |                                     }
277 | 
278 |                                     for (tree.children) |child| {
279 |                                         switch (child) {
280 |                                             .elem => |elem_child| {
281 |                                                 if (std.mem.eql(u8, elem_child.tag_name, tag_name)) {
282 |                                                     try result.append(try PopulateShape(ChildType, child_shape).initFromTreeImpl(
283 |                                                         mode,
284 |                                                         allocator,
285 |                                                         elem_child.tree orelse .{ .children = &.{} },
286 |                                                         elem_child.attributes,
287 |                                                     ));
288 |                                                 }
289 |                                             },
290 |                                             else => {},
291 |                                         }
292 |                                     }
293 | 
294 |                                     val.* = try result.toOwnedSlice();
295 |                                 },
296 |                             }
297 |                         } else if (struct_info.fields.len == 3 and shape[0] == .element) {
298 |                             const tag_name = shape[1];
299 |                             const child_shape = shape[2];
300 | 
301 |                             const elem: Tree.Node.Elem = for (tree.children) |child| {
302 |                                 switch (child) {
303 |                                     .elem => |elem_child| {
304 |                                         if (std.mem.eql(u8, elem_child.tag_name, tag_name)) {
305 |                                             break elem_child;
306 |                                         }
307 |                                     },
308 |                                     else => {},
309 |                                 }
310 |                             } else return ContentError.MissingChild;
311 | 
312 |                             try PopulateShape(T, child_shape).fromTreeImpl(
313 |                                 mode,
314 |                                 allocator,
315 |                                 elem.tree orelse .{ .children = &.{} },
316 |                                 elem.attributes,
317 |                                 val,
318 |                             );
319 |                         } else if (struct_info.fields.len > 2 and shape[0] == .one_of) {
320 |                             if (dest_type_info != .@"union") {
321 |                                 @compileError(cannot_be_applied ++ ", must be a union type");
322 |                             }
323 | 
324 |                             const union_fields = dest_type_info.@"union".fields;
325 |                             const num_child_shapes = struct_info.fields.len - 1;
326 | 
327 |                             if (union_fields.len != num_child_shapes) {
328 |                                 @compileError(cannot_be_applied ++ ", mismatched number of branches");
329 |                             }
330 | 
331 |                             val.* = inline for (union_fields, 0..num_child_shapes) |field, i| {
332 |                                 const child_shape = shape[1 + i];
333 |                                 const child_shape_type_info = @typeInfo(@TypeOf(child_shape));
334 |                                 if (child_shape_type_info == .enum_literal and child_shape == .none) {
335 |                                     if (field.type != void) {
336 |                                         @compileError(cannot_be_applied ++ ", must be null");
337 |                                     }
338 |                                     break @unionInit(T, field.name, {});
339 |                                 }
340 |                                 const maybe_found: ?field.type = PopulateShape(field.type, child_shape).initFromTreeImpl(
341 |                                     mode,
342 |                                     allocator,
343 |                                     tree,
344 |                                     attributes,
345 |                                 ) catch |e| switch (e) {
346 |                                     error.MissingAttribute,
347 |                                     error.MissingAttributeValue,
348 |                                     error.MissingChild,
349 |                                     error.MissingOption,
350 |                                     => null,
351 |                                     else => return e,
352 |                                 };
353 |                                 if (maybe_found) |found| {
354 |                                     break @unionInit(T, field.name, found);
355 |                                 }
356 |                             } else return ContentError.MissingOption;
357 |                         } else {
358 |                             @compileError("Unknown shape: " ++ shape_print);
359 |                         }
360 |                     } else {
361 |                         if (dest_type_info != .@"struct") {
362 |                             @compileError(cannot_be_applied ++ ", must be a struct type");
363 |                         }
364 | 
365 |                         const struct_fields = dest_type_info.@"struct".fields;
366 |                         const shape_fields = struct_info.fields;
367 | 
368 |                         var i: usize = 0;
369 |                         errdefer {
370 |                             switch (mode) {
371 |                                 .compile_time => {},
372 |                                 .run_time => {
373 |                                     // we have to reverse all of the fields by deinitialising
374 |                                     // them. the problem is that the number of fields that were
375 |                                     // initialised is runtime-known, whereas the fields themselves
376 |                                     // need to be comptime known. so this code is weird.
377 |                                     comptime var j: usize = shape_fields.len;
378 |                                     inline while (j > 0) {
379 |                                         j -= 1;
380 |                                         if (j < i) {
381 |                                             const shape_field = shape_fields[j];
382 |                                             const base_field = comptime for (struct_fields) |field| {
383 |                                                 if (std.mem.eql(u8, field.name, shape_field.name)) {
384 |                                                     break field;
385 |                                                 }
386 |                                             } else @compileError("Missing field '" ++ shape_field.name ++ "' on base type " ++ @typeName(T));
387 | 
388 |                                             const shape_field_val = @field(shape, shape_field.name);
389 |                                             PopulateShape(base_field.type, shape_field_val)
390 |                                                 .deinit(allocator, @field(val, base_field.name));
391 |                                         }
392 |                                     }
393 |                                 },
394 |                             }
395 |                         }
396 | 
397 |                         inline for (shape_fields) |shape_field| {
398 |                             const base_field = comptime for (struct_fields) |field| {
399 |                                 if (std.mem.eql(u8, field.name, shape_field.name)) {
400 |                                     break field;
401 |                                 }
402 |                             } else @compileError(cannot_be_applied ++ ", missing field '" ++ shape_field.name);
403 | 
404 |                             const shape_field_val = @field(shape, shape_field.name);
405 |                             @field(val.*, base_field.name) = try PopulateShape(base_field.type, shape_field_val)
406 |                                 .initFromTreeImpl(mode, allocator, tree, attributes);
407 |                             i += 1;
408 |                         }
409 |                     }
410 |                 },
411 |                 .enum_literal => {
412 |                     if (shape == .content or shape == .content_trimmed) {
413 |                         if (T != []const u8 and T != []u8) {
414 |                             @compileError(cannot_be_applied ++ ", must be a string type");
415 |                         }
416 | 
417 |                         switch (mode) {
418 |                             .compile_time => {
419 |                                 val.* = switch (shape) {
420 |                                     .content => tree.concatTextComptime(),
421 |                                     .content_trimmed => tree.concatTextTrimmedComptime(),
422 |                                     else => unreachable,
423 |                                 };
424 |                             },
425 |                             .run_time => {
426 |                                 val.* = switch (shape) {
427 |                                     .content => try tree.concatTextAlloc(allocator),
428 |                                     .content_trimmed => try tree.concatTextTrimmedAlloc(allocator),
429 |                                     else => unreachable,
430 |                                 };
431 |                             },
432 |                         }
433 |                     } else if (shape == .cdata) {
434 |                         const cdata_child: Tree.Node.Cdata = for (tree.children) |child| {
435 |                             switch (child) {
436 |                                 .cdata => |cdata_child| break cdata_child,
437 |                                 else => {},
438 |                             }
439 |                         } else return ContentError.MissingCdata;
440 | 
441 |                         val.* = switch (mode) {
442 |                             .compile_time => cdata_child.contents,
443 |                             .run_time => try allocator.dupe(u8, cdata_child.contents),
444 |                         };
445 |                     }
446 |                 },
447 |                 else => @compileError("Unknown shape type " ++ shape_print),
448 |             }
449 |         }
450 | 
451 |         fn initFromTreeImpl(
452 |             comptime mode: Mode,
453 |             allocator: std.mem.Allocator,
454 |             tree: Tree,
455 |             attributes: []const Tree.Node.Elem.Attr,
456 |         ) !T {
457 |             var val: T = undefined;
458 |             switch (dest_type_info) {
459 |                 .@"struct" => |structInfo| {
460 |                     inline for (structInfo.fields) |field| {
461 |                         if (field.default_value_ptr) |default_value| {
462 |                             @field(val, field.name) = @as(*field.type, @ptrCast(@alignCast(@constCast(default_value)))).*;
463 |                         }
464 |                     }
465 |                 },
466 |                 else => {},
467 |             }
468 |             try fromTreeImpl(mode, allocator, tree, attributes, &val);
469 |             return val;
470 |         }
471 | 
472 |         /// Fill a struct instance from a parsed XML tree known at compile time.
473 |         pub fn fromTreeComptime(comptime tree: Tree, val: *T) !void {
474 |             try fromTreeImpl(.compile_time, undefined, tree, &.{}, val);
475 |         }
476 | 
477 |         /// Create the struct from a parsed XML tree known at compile time.
478 |         pub fn initFromTreeComptime(comptime tree: Tree) !T {
479 |             return comptime try initFromTreeImpl(.compile_time, undefined, tree, &.{});
480 |         }
481 | 
482 |         /// Fill a struct instance from a parsed XML tree, owning all allocations.
483 |         pub fn fromTreeOwned(allocator: std.mem.Allocator, tree: Tree, val: *T) !void {
484 |             try fromTreeImpl(.run_time, allocator, tree, &.{}, val);
485 |         }
486 | 
487 |         /// Create the struct from a parsed XML tree, owning all allocations.
488 |         pub fn initFromTreeOwned(allocator: std.mem.Allocator, tree: Tree) !T {
489 |             return try initFromTreeImpl(.run_time, allocator, tree, &.{});
490 |         }
491 | 
492 |         /// Create the struct directly, reading from an XML document, returning an arena managing all allocations.
493 |         pub fn fromReader(allocator: std.mem.Allocator, reader: anytype, val: *T) !std.heap.ArenaAllocator {
494 |             var owned_tree = try parse.fromReader(allocator, reader);
495 |             try fromTreeOwned(owned_tree.arena.allocator(), owned_tree.tree, val);
496 |             return owned_tree.arena;
497 |         }
498 | 
499 |         /// Create the struct directly, reading from an XML document, with an arena to manage all allocations.
500 |         pub fn initFromReader(allocator: std.mem.Allocator, reader: anytype) !OwnedDocument {
501 |             var owned_tree = try parse.fromReader(allocator, reader);
502 |             errdefer owned_tree.deinit();
503 |             const value = try initFromTreeOwned(owned_tree.arena.allocator(), owned_tree.tree);
504 |             return .{ .owned_tree = owned_tree, .value = value };
505 |         }
506 | 
507 |         /// Fill a struct instance directly from an XML document slice, returning an arena managing all allocations.
508 |         pub fn fromSlice(allocator: std.mem.Allocator, slice: []const u8, val: *T) !std.heap.ArenaAllocator {
509 |             var owned_tree = try parse.fromSlice(allocator, slice);
510 |             errdefer owned_tree.deinit();
511 |             try fromTreeOwned(owned_tree.arena.allocator(), owned_tree.tree, val);
512 |             return owned_tree.arena;
513 |         }
514 | 
515 |         /// Fill a struct instance directly from an XML document slice known at compile time.
516 |         pub fn fromSliceComptime(slice: []const u8, val: *T) !void {
517 |             const tree = comptime try parse.fromSliceComptime(slice);
518 |             fromTreeComptime(tree, val);
519 |         }
520 | 
521 |         /// Create the struct directly from an XML slice, with an arena to manage all allocations.
522 |         pub fn initFromSlice(allocator: std.mem.Allocator, slice: []const u8) !OwnedDocument {
523 |             var owned_tree = try parse.fromSlice(allocator, slice);
524 |             errdefer owned_tree.deinit();
525 |             const value = try initFromTreeOwned(owned_tree.arena.allocator(), owned_tree.tree);
526 |             return .{ .owned_tree = owned_tree, .value = value };
527 |         }
528 | 
529 |         /// Create the struct directly from an XML document slice known at compile time.
530 |         pub fn initFromSliceComptime(comptime slice: []const u8) T {
531 |             const tree = comptime parse.fromSliceComptime(slice);
532 |             return comptime initFromTreeComptime(tree);
533 |         }
534 |     };
535 | }
536 | 
537 | pub fn ShapeTypeFromType(comptime T: type) type {
538 |     if (T == Tree) {
539 |         return type;
540 |     }
541 | 
542 |     if (@hasDecl(T, "xml_shape")) {
543 |         return @TypeOf(T.xml_shape);
544 |     }
545 | 
546 |     @compileError("Type " ++ @typeName(T) ++ " needs an 'xml_shape' declaration to deserialise from XML");
547 | }
548 | 
549 | pub fn shapeFromType(comptime T: type) ShapeTypeFromType(T) {
550 |     if (T == Tree) {
551 |         return Tree;
552 |     }
553 | 
554 |     if (@hasDecl(T, "xml_shape")) {
555 |         return T.xml_shape;
556 |     }
557 | }
558 | 
559 | /// Methods for creating and filling structs from data in an XML document.
560 | pub fn Populate(comptime T: type) type {
561 |     return PopulateShape(T, shapeFromType(T));
562 | }
563 | 
564 | const Person = struct {
565 |     pub const xml_shape = .{
566 |         .name = .content_trimmed,
567 |         .age = .{ .attribute, "age" },
568 |         .jobs = .{ .elements, "job", .{
569 |             .start_date = .{ .attribute, "start_date" },
570 |             .end_date = .{ .attribute, "end_date" },
571 |             .title = .content_trimmed,
572 |             .fired = .attribute_exists,
573 |         } },
574 |         .location = .{
575 |             .one_of,
576 |             .{ .element, "house", .content },
577 |             .{ .element, "work", .content },
578 |             .none,
579 |         },
580 |         .apprentice = .{ .maybe, .{ .element, "apprentice", Person } },
581 |         .children = .{ .elements, "child", Person },
582 |         .custom_data = .{ .maybe, .{ .element, "custom_data", Tree } },
583 |     };
584 | 
585 |     name: []const u8,
586 |     age: []const u8,
587 |     jobs: []const struct {
588 |         start_date: []const u8,
589 |         end_date: []const u8,
590 |         title: []const u8,
591 |         fired: bool,
592 |     },
593 |     location: union(enum) {
594 |         house: []const u8,
595 |         work: []const u8,
596 |         none: void,
597 |     },
598 |     apprentice: ?*const Person,
599 |     children: []const Person,
600 |     custom_data: ?Tree,
601 | };
602 | 
603 | const Document = struct {
604 |     pub const xml_shape = .{
605 |         .people = .{ .elements, "person", Person },
606 |     };
607 | 
608 |     people: []const Person,
609 | };
610 | 
611 | const test_buf =
612 |     \\<!-- not biblically accurate... -->
613 |     \\<person age="42">
614 |     \\    Judas
615 |     \\    <job start_date="2019" end_date="2022">software engineeer</job>
616 |     \\    <job start_date="2022" end_date="2023">dishwasher</job>
617 |     \\    <job start_date="2023" end_date="2024">door-to-door salesman</job>
618 |     \\    <house>Nazereth</house>
619 |     \\    <custom_data>
620 |     \\        <temperature unit="celcius">36</temperature>
621 |     \\        <favourite_color>blue</favourite_color>
622 |     \\    </custom_data>
623 |     \\</person>
624 |     \\<person age="40">
625 |     \\    Paul
626 |     \\    <job start_date="40" end_date="-">apostle</job>
627 |     \\    <work>Tarsus</work>
628 |     \\    <child age="20">
629 |     \\        John
630 |     \\        <apprentice age="18">
631 |     \\            Jude
632 |     \\        </apprentice>
633 |     \\        <child age="2">
634 |     \\            Jamie
635 |     \\            <work>baby places</work>
636 |     \\        </child>
637 |     \\    </child>
638 |     \\</person>
639 | ;
640 | 
641 | pub fn expectTestBufDocumentValid(document: Document) !void {
642 |     try std.testing.expectEqual(document.people.len, 2);
643 |     try std.testing.expectEqualSlices(u8, document.people[0].name, "Judas");
644 |     try std.testing.expectEqualSlices(u8, document.people[0].age, "42");
645 |     try std.testing.expectEqual(document.people[0].jobs.len, 3);
646 |     try std.testing.expect(document.people[0].location == .house);
647 |     try std.testing.expectEqualSlices(u8, document.people[0].location.house, "Nazereth");
648 |     try std.testing.expectEqualSlices(u8, document.people[1].name, "Paul");
649 |     try std.testing.expectEqualSlices(u8, document.people[1].age, "40");
650 |     try std.testing.expectEqual(document.people[1].jobs.len, 1);
651 |     try std.testing.expect(document.people[1].location == .work);
652 |     try std.testing.expectEqualSlices(u8, document.people[1].location.work, "Tarsus");
653 | 
654 |     try std.testing.expect(document.people[0].custom_data != null);
655 |     try std.testing.expectEqual(document.people[0].custom_data.?.children.len, 5);
656 |     try std.testing.expect(document.people[0].custom_data.?.children[1] == .elem);
657 |     try std.testing.expectEqual(document.people[0].custom_data.?.children[1].elem.attributes.len, 1);
658 |     try std.testing.expectEqualSlices(u8, document.people[0].custom_data.?.children[1].elem.attributes[0].name, "unit");
659 |     try std.testing.expect(document.people[0].custom_data.?.children[1].elem.attributes[0].value != null);
660 |     try std.testing.expectEqualSlices(u8, document.people[0].custom_data.?.children[1].elem.attributes[0].value.?, "celcius");
661 | }
662 | 
663 | test Populate {
664 |     var owned_tree = try parse.fromSlice(std.testing.allocator, test_buf);
665 |     defer owned_tree.deinit();
666 | 
667 |     const document: Document = try Populate(Document).initFromTreeOwned(std.testing.allocator, owned_tree.tree);
668 |     defer Populate(Document).deinit(std.testing.allocator, document);
669 | 
670 |     try expectTestBufDocumentValid(document);
671 | }
672 | 
673 | test "Populate: comptime" {
674 |     @setEvalBranchQuota(8192);
675 |     const tree = try parse.fromSliceComptime(test_buf);
676 |     const document: Document = try comptime Populate(Document).initFromTreeComptime(tree);
677 | 
678 |     try expectTestBufDocumentValid(document);
679 | }
680 | 
681 | const DogDocument = struct {
682 |     pub const Dog = struct {
683 |         pub const xml_shape = .{
684 |             .name = .{ .attribute, "name" },
685 |             .ears = .{ .attribute, "ears" },
686 |             .teeth = .{ .attribute, "teeth" },
687 |             .temperament = .{ .element, "temperament", .content_trimmed },
688 |             .colour = .{ .elements, "colour", .content_trimmed },
689 |         };
690 | 
691 |         name: []const u8,
692 |         ears: []const u8,
693 |         teeth: []const u8,
694 |         temperament: []const u8,
695 |         colour: []const []const u8,
696 |     };
697 | 
698 |     pub const xml_shape = .{
699 |         .dogs = .{ .elements, "dog", Dog },
700 |     };
701 | 
702 |     dogs: []const Dog,
703 | };
704 | 
705 | const test_missing_attribute =
706 |     \\<dog name="Barney" ears="floppy">
707 |     \\    <temperament>stoic</temperament>
708 |     \\    <colour>brown</colour>
709 |     \\    <colour>white</colour>
710 |     \\</dog>
711 | ;
712 | 
713 | test "Populate: error: missing attribute" {
714 |     try std.testing.expectError(ContentError.MissingAttribute, Populate(DogDocument).initFromSlice(std.testing.allocator, test_missing_attribute));
715 | }
716 | 
717 | const test_missing_attribute_value =
718 |     \\<dog name="Barney" ears="floppy" teeth>
719 |     \\    <temperament>stoic</temperament>
720 |     \\    <colour>brown</colour>
721 |     \\    <colour>white</colour>
722 |     \\</dog>
723 | ;
724 | 
725 | test "Populate: error: missing attribute value" {
726 |     try std.testing.expectError(ContentError.MissingAttributeValue, Populate(DogDocument).initFromSlice(std.testing.allocator, test_missing_attribute_value));
727 | }
728 | 
729 | const test_missing_child =
730 |     \\<dog name="Barney" ears="floppy" teeth="none">
731 |     \\    <colour>brown</colour>
732 |     \\    <colour>white</colour>
733 |     \\</dog>
734 | ;
735 | 
736 | test "Populate: error: missing child" {
737 |     try std.testing.expectError(ContentError.MissingChild, Populate(DogDocument).initFromSlice(std.testing.allocator, test_missing_child));
738 | }
739 | 
740 | const OptionDocument = union(enum) {
741 |     pub const xml_shape = .{ .one_of, Shampoo, Microwave };
742 | 
743 |     pub const Shampoo = struct {
744 |         pub const xml_shape = .{
745 |             .scent = .{ .element, "scent", .content_trimmed },
746 |         };
747 |         scent: []const u8,
748 |     };
749 | 
750 |     pub const Microwave = struct {
751 |         pub const xml_shape = .{
752 |             .wattage = .{ .element, "wattage", .content_trimmed },
753 |         };
754 | 
755 |         wattage: []const u8,
756 |     };
757 | 
758 |     shampoo: Shampoo,
759 |     microwave: Microwave,
760 | };
761 | 
762 | const test_missing_option =
763 |     \\<dog name="barney"></dog>
764 | ;
765 | 
766 | test "Populate: missing option" {
767 |     try std.testing.expectError(ContentError.MissingOption, Populate(OptionDocument).initFromSlice(std.testing.allocator, test_missing_option));
768 | }
769 | 
770 | const test_cdata_payload =
771 |     \\<item>
772 |     \\  <title>Title #1</title>
773 |     \\  <data><![CDATA[<a>foobar<br/>]]></data>
774 |     \\</item>
775 | ;
776 | 
777 | const CdataDocument = struct {
778 |     pub const Item = struct {
779 |         pub const xml_shape = .{
780 |             .text = .{ .element, "data", .cdata },
781 |         };
782 | 
783 |         text: []const u8,
784 |     };
785 | 
786 |     pub const xml_shape = .{
787 |         .item = .{ .element, "item", Item },
788 |     };
789 | 
790 |     item: Item,
791 | };
792 | 
793 | test "Populate: with CDATA" {
794 | 
795 |     const document = try Populate(CdataDocument).initFromSlice(std.testing.allocator, test_cdata_payload);
796 |     defer document.deinit();
797 | 
798 |     try std.testing.expectEqualStrings("<a>foobar<br/>", document.value.item.text);
799 | }
800 | 
801 | test "Populate: comptime with CDATA" {
802 |     @setEvalBranchQuota(8192);
803 |     const tree = try parse.fromSliceComptime(test_cdata_payload);
804 |     const document: CdataDocument = try comptime Populate(CdataDocument).initFromTreeComptime(tree);
805 | 
806 |     try std.testing.expectEqualStrings("<a>foobar<br/>", document.item.text);
807 | }


--------------------------------------------------------------------------------
/src/parse.zig:
--------------------------------------------------------------------------------
   1 | const std = @import("std");
   2 | const Scanner = @import("./Scanner.zig");
   3 | 
   4 | const Error = error{XmlDefect};
   5 | 
   6 | pub const Diagnostics = struct {
   7 |     pub const Range = struct {
   8 |         start: usize,
   9 |         end: usize,
  10 |     };
  11 | 
  12 |     pub const Defect = struct {
  13 |         pub const Kind = enum {
  14 |             missing_tag_name,
  15 |             tag_never_opened,
  16 |             tag_never_closed,
  17 |         };
  18 | 
  19 |         kind: Kind,
  20 |         range: Range,
  21 |     };
  22 | 
  23 |     defects: std.array_list.Managed(Defect),
  24 | 
  25 |     pub fn init(allocator: std.mem.Allocator) Diagnostics {
  26 |         return .{
  27 |             .defects = std.array_list.Managed(Defect).init(allocator),
  28 |         };
  29 |     }
  30 | 
  31 |     pub fn deinit(self: Diagnostics) void {
  32 |         self.defects.deinit();
  33 |     }
  34 | 
  35 |     fn buildRange(tokens: []const Scanner.Token) Range {
  36 |         std.debug.assert(tokens.len > 0);
  37 | 
  38 |         var min: usize = std.math.maxInt(usize);
  39 |         var max: usize = 0;
  40 |         for (tokens) |token| {
  41 |             if (token.start_pos < min) min = token.start_pos;
  42 |             if (token.end_pos > max) max = token.end_pos;
  43 |         }
  44 | 
  45 |         std.debug.assert(max != std.math.maxInt(usize));
  46 |         std.debug.assert(max >= min);
  47 | 
  48 |         return .{ .start = min, .end = max };
  49 |     }
  50 | 
  51 |     pub fn reportDefect(self: *Diagnostics, defectKind: Defect.Kind, tokens: []const Scanner.Token) !void {
  52 |         try self.defects.append(.{
  53 |             .kind = defectKind,
  54 |             .range = buildRange(tokens),
  55 |         });
  56 |     }
  57 | 
  58 |     pub fn hasDefect(self: Diagnostics) bool {
  59 |         return self.defects.items.len > 0;
  60 |     }
  61 | };
  62 | 
  63 | /// Represents a set of XML element, text or comment nodes.
  64 | pub const Tree = struct {
  65 |     /// A tree along with the arena allocator that all allocations were done through, so that
  66 |     /// the entire tree can be easily destroyed.
  67 |     pub const Owned = struct {
  68 |         /// The arena used for all allocations in the parsed XML document tree.
  69 |         arena: std.heap.ArenaAllocator,
  70 |         /// The parsed XML document as a tree structure.
  71 |         tree: Tree,
  72 | 
  73 |         /// De-initialise the internal arena, freeing all allocations and invalidating the parsed
  74 |         /// XML document tree.
  75 |         pub fn deinit(self: Owned) void {
  76 |             self.arena.deinit();
  77 |         }
  78 |     };
  79 | 
  80 |     /// Represents an element, text, or comment node in an XML document.
  81 |     pub const Node = union(enum) {
  82 |         /// Represents an element with a tag name in an XML document.
  83 |         pub const Elem = struct {
  84 |             /// Represents an attribute on an element, both those without values, e.g. `<button disabled>`,
  85 |             /// and those with values.
  86 |             pub const Attr = struct {
  87 |                 name: []const u8,
  88 |                 /// This is set to `null` if the attribute has no value.
  89 |                 value: ?[]const u8,
  90 |             };
  91 | 
  92 |             tag_name: []const u8,
  93 |             attributes: []const Attr,
  94 |             /// The sub-tree of the elements containing child elements and text nodes.
  95 |             tree: ?Tree,
  96 | 
  97 |             /// De-initialise the entire element, including its attributes, child elements
  98 |             /// and text nodes.
  99 |             pub fn freeRecursive(self: Elem, allocator: std.mem.Allocator) void {
 100 |                 if (self.tree) |tree| tree.freeRecursive(allocator);
 101 |                 var i = self.attributes.len;
 102 |                 while (i > 0) {
 103 |                     i -= 1;
 104 |                     if (self.attributes[i].value) |value| {
 105 |                         allocator.free(value);
 106 |                     }
 107 |                     allocator.free(self.attributes[i].name);
 108 |                 }
 109 |                 allocator.free(self.attributes);
 110 |                 allocator.free(self.tag_name);
 111 |             }
 112 | 
 113 |             /// Get an attribute by its name.
 114 |             pub fn attributeByName(self: Elem, needle: []const u8) ?Attr {
 115 |                 return for (self.attributes) |attribute| {
 116 |                     if (std.mem.eql(u8, attribute.name, needle)) {
 117 |                         break attribute;
 118 |                     }
 119 |                 } else null;
 120 |             }
 121 | 
 122 |             /// Alias for `attributeByName`.
 123 |             pub fn attr(self: Elem, needle: []const u8) ?Attr {
 124 |                 return try self.attributeByName(needle);
 125 |             }
 126 | 
 127 |             /// Get the value of an attribute given its name.
 128 |             ///
 129 |             /// Note that if the attribute has no value, e.g., `<button disabled>` this will
 130 |             /// still return null. Use `attributeByName` or `attr` in those cases.
 131 |             pub fn attributeValueByName(self: Elem, needle: []const u8) ?[]const u8 {
 132 |                 return (self.attributeByName(needle) orelse return null).value;
 133 |             }
 134 | 
 135 |             /// Alias for `attributeValueByName`
 136 |             pub fn attrValue(self: Elem, needle: []const u8) ?[]const u8 {
 137 |                 return self.attributeValueByName(needle);
 138 |             }
 139 |         };
 140 | 
 141 |         /// Represents a piece of text in an XML document. Note that contiguous text sections
 142 |         /// are combined into one.
 143 |         pub const Text = struct {
 144 |             /// The inner contents of the text verbatim. This includes all surrounding whitespace. Note that
 145 |             /// in most XML use-cases, for example in HTML, whitespace is essentially collapsed into
 146 |             /// one space. Dishwasher does not do this for you.
 147 |             ///
 148 |             /// Use `trimmed` to get just the text.
 149 |             contents: []const u8,
 150 | 
 151 |             pub fn freeRecursive(self: Text, allocator: std.mem.Allocator) void {
 152 |                 allocator.free(self.contents);
 153 |             }
 154 | 
 155 |             /// Return the text without any ASCII whitespace at the beginning or end.
 156 |             pub fn trimmed(self: Text) []const u8 {
 157 |                 return std.mem.trim(u8, self.contents, &std.ascii.whitespace);
 158 |             }
 159 |         };
 160 | 
 161 |         /// Represents a full comment in an XML document.
 162 |         pub const Comment = struct {
 163 |             /// The inner contents of the comment verbatim. This includes all surrounding whitespace.
 164 |             contents: []const u8,
 165 | 
 166 |             pub fn freeRecursive(self: Comment, allocator: std.mem.Allocator) void {
 167 |                 allocator.free(self.contents);
 168 |             }
 169 |         };
 170 | 
 171 |         /// Represents CDATA in an XML document.
 172 |         pub const Cdata = struct {
 173 |             /// The inner contents of the CDATA block verbatim. This includes all surrounding whitespace.
 174 |             contents: []const u8,
 175 | 
 176 |             pub fn freeRecursive(self: Cdata, allocator: std.mem.Allocator) void {
 177 |                 allocator.free(self.contents);
 178 |             }
 179 |         };
 180 | 
 181 |         elem: Elem,
 182 |         text: Text,
 183 |         comment: Comment,
 184 |         cdata: Cdata,
 185 | 
 186 |         pub fn freeRecursive(self: Node, allocator: std.mem.Allocator) void {
 187 |             switch (self) {
 188 |                 inline else => |node| node.freeRecursive(allocator),
 189 |             }
 190 |         }
 191 |     };
 192 | 
 193 |     pub const empty: Tree = .{ .children = &.{} };
 194 | 
 195 |     children: []const Node,
 196 | 
 197 |     pub fn freeRecursive(self: Tree, allocator: std.mem.Allocator) void {
 198 |         var i = self.children.len;
 199 |         while (i > 0) {
 200 |             i -= 1;
 201 |             self.children[i].freeRecursive(allocator);
 202 |         }
 203 |         allocator.free(self.children);
 204 |     }
 205 | 
 206 |     /// Find an element child node by its tag name, returns `null` if no elements with that
 207 |     /// tag can not be found.
 208 |     pub fn elementByTagName(self: Tree, needle: []const u8) ?Node.Elem {
 209 |         return for (self.children) |child| {
 210 |             switch (child) {
 211 |                 .elem => |elem_child| {
 212 |                     if (std.mem.eql(u8, elem_child.tag_name, needle)) {
 213 |                         break elem_child;
 214 |                     }
 215 |                 },
 216 |                 else => {},
 217 |             }
 218 |         } else null;
 219 |     }
 220 | 
 221 |     /// Alias for `elementByTagName`.
 222 |     pub fn elem(self: Tree, needle: []const u8) ?Node.Elem {
 223 |         return self.elementByTagName(needle);
 224 |     }
 225 | 
 226 |     /// Collate all child elements with a given tag name, allocating a slice to contain them
 227 |     /// all. To free the returned slice, call `allocator.free(elements)`, where `elements`
 228 |     /// is the returned slice.
 229 |     pub fn elementsByTagNameAlloc(self: Tree, allocator: std.mem.Allocator, needle: []const u8) ![]Node.Elem {
 230 |         var out = std.array_list.Managed(Node.Elem).init(allocator);
 231 |         errdefer out.deinit();
 232 | 
 233 |         for (self.children) |child| {
 234 |             switch (child) {
 235 |                 .elem => |elem_child| {
 236 |                     if (std.mem.eql(u8, elem_child.tag_name, needle)) {
 237 |                         try out.append(elem_child);
 238 |                     }
 239 |                 },
 240 |                 else => {},
 241 |             }
 242 |         }
 243 | 
 244 |         return try out.toOwnedSlice();
 245 |     }
 246 | 
 247 |     /// Alias for `elementsByTagNameAlloc`.
 248 |     pub fn elemsAlloc(self: Tree, allocator: std.mem.Allocator, needle: []const u8) ![]Node.Elem {
 249 |         return try self.elementsByTagNameAlloc(allocator, needle);
 250 |     }
 251 | 
 252 |     /// Get an element by the value of one of its attributes. Returns `null` if no elements
 253 |     /// with the attribute value can be found.
 254 |     pub fn elementByAttributeValue(self: Tree, needle_name: []const u8, needle_value: []const u8) ?Node.Elem {
 255 |         return for (self.children) |child| {
 256 |             switch (child) {
 257 |                 .elem => |elem_child| {
 258 |                     const attribute = elem_child.attributeByName(needle_name) orelse continue;
 259 |                     if (std.mem.eql(u8, attribute.value orelse continue, needle_value)) {
 260 |                         break elem_child;
 261 |                     }
 262 |                 },
 263 |                 else => {},
 264 |             }
 265 |         } else null;
 266 |     }
 267 | 
 268 |     /// Alias for `elementByAttributeValue`
 269 |     pub fn elemByAttr(self: Tree, needle_name: []const u8, needle_value: []const u8) ?Node.Elem {
 270 |         return self.elementByAttributeValue(needle_name, needle_value);
 271 |     }
 272 | 
 273 |     /// Collate the inner text (not including the elements or comments) of the tree. Note that the
 274 |     /// result will be entirely unformatted, with whitespace uncollapsed.
 275 |     ///
 276 |     /// Free with allocator.free(result);
 277 |     pub fn concatTextAlloc(self: Tree, allocator: std.mem.Allocator) ![]const u8 {
 278 |         var content_length: usize = 0;
 279 |         for (self.children) |child| {
 280 |             switch (child) {
 281 |                 .text => |text_child| content_length += text_child.contents.len,
 282 |                 else => {},
 283 |             }
 284 |         }
 285 |         const combined = try allocator.alloc(u8, content_length);
 286 |         errdefer allocator.free(combined);
 287 | 
 288 |         var cursor: usize = 0;
 289 |         for (self.children) |child| {
 290 |             switch (child) {
 291 |                 .text => |text_child| {
 292 |                     @memcpy(combined[cursor .. cursor + text_child.contents.len], text_child.contents);
 293 |                     cursor += text_child.contents.len;
 294 |                 },
 295 |                 else => {},
 296 |             }
 297 |         }
 298 | 
 299 |         return combined;
 300 |     }
 301 | 
 302 |     /// Collate the inner text (not including the elements or comments) of the tree. Note that the
 303 |     /// result will be entirely unformatted, with whitespace trimmed from the start and beginning, but
 304 |     /// uncollapsed inside.
 305 |     ///
 306 |     /// Free with allocator.free(result);
 307 |     pub fn concatTextTrimmedAlloc(self: Tree, allocator: std.mem.Allocator) ![]const u8 {
 308 |         const combined = try self.concatTextAlloc(allocator);
 309 |         defer allocator.free(combined);
 310 | 
 311 |         const trimmed = std.mem.trim(u8, combined, &std.ascii.whitespace);
 312 |         return try allocator.dupe(u8, trimmed);
 313 |     }
 314 | 
 315 |     /// Same as `concatTextAlloc` but can be executed on a tree processed at
 316 |     /// compile time.
 317 |     pub fn concatTextComptime(self: Tree) []const u8 {
 318 |         var out: []const u8 = &.{};
 319 |         for (self.children) |child| {
 320 |             switch (child) {
 321 |                 .text => |text_child| {
 322 |                     out = out ++ text_child.contents;
 323 |                 },
 324 |                 else => {},
 325 |             }
 326 |         }
 327 |         return out;
 328 |     }
 329 | 
 330 |     /// Same as `concatTextTrimmedAlloc` but can be executed on a tree processed at
 331 |     /// compile time.
 332 |     pub fn concatTextTrimmedComptime(self: Tree) []const u8 {
 333 |         const combined = self.concatTextComptime();
 334 |         return std.mem.trim(u8, combined, &std.ascii.whitespace);
 335 |     }
 336 | };
 337 | 
 338 | pub fn StateMachine(comptime Builder: type) type {
 339 |     return struct {
 340 |         pub const State = union(enum) {
 341 |             const ElemTag = struct {
 342 |                 open_token: Scanner.Token,
 343 |                 tag_name: []const u8,
 344 |             };
 345 | 
 346 |             default: void,
 347 |             elem_tag: ElemTag,
 348 |         };
 349 | 
 350 |         const StateMachineT = @This();
 351 | 
 352 |         builder: *Builder,
 353 |         state: State = .default,
 354 | 
 355 |         pub fn feedToken(self: *StateMachineT, token: Scanner.Token) !void {
 356 |             switch (self.state) {
 357 |                 .default => switch (token.kind) {
 358 |                     .element_open => {
 359 |                         if (token.inner.len == 0) {
 360 |                             try self.builder.reportDefectOrExit(.missing_tag_name, &.{token});
 361 |                         }
 362 | 
 363 |                         const copied_token: Scanner.Token = try self.builder.copyToken(token);
 364 |                         try self.builder.buildAttributes();
 365 |                         self.state = .{ .elem_tag = .{
 366 |                             .open_token = copied_token,
 367 |                             .tag_name = copied_token.inner,
 368 |                         } };
 369 |                     },
 370 |                     .element_children_end => {
 371 |                         const stack_size: usize = self.builder.getStackSize();
 372 | 
 373 |                         if (stack_size == 1) {
 374 |                             try self.builder.reportDefectOrExit(.tag_never_opened, &.{token});
 375 |                             return;
 376 |                         }
 377 | 
 378 |                         const open_token: Scanner.Token = try self.builder.getOpenToken() orelse unreachable;
 379 |                         const children = try self.builder.getOwnedChildren();
 380 | 
 381 |                         try self.builder.popStack();
 382 | 
 383 |                         if (!std.mem.eql(u8, open_token.inner, token.inner)) {
 384 |                             try self.builder.reportDefectOrExit(.tag_never_opened, &.{token});
 385 |                         }
 386 | 
 387 |                         try self.builder.setElementTree(.{ .children = children });
 388 |                     },
 389 |                     .comment_open => {
 390 |                         try self.builder.addComment();
 391 |                     },
 392 |                     .comment_close => {
 393 |                         try self.builder.closeComment();
 394 |                     },
 395 |                     .cdata_open => {
 396 |                         try self.builder.addCdata();
 397 |                     },
 398 |                     .cdata_close => {
 399 |                         try self.builder.closeCdata();
 400 |                     },
 401 |                     .meta_attribute => {},
 402 |                     .meta_attribute_value => {},
 403 |                     .doctype => {},
 404 |                     .text_chunk => {
 405 |                         try self.builder.appendTextChunk(token.inner);
 406 |                     },
 407 |                     else => unreachable,
 408 |                 },
 409 |                 .elem_tag => |*tag_details| {
 410 |                     switch (token.kind) {
 411 |                         .element_close, .element_self_end => {
 412 |                             const attributes = try self.builder.getAttributesOwned();
 413 | 
 414 |                             try self.builder.addNode(.{ .elem = .{
 415 |                                 .tag_name = tag_details.tag_name,
 416 |                                 .attributes = attributes,
 417 |                                 .tree = null,
 418 |                             } });
 419 |                             if (token.kind == .element_close) {
 420 |                                 try self.builder.pushStack(tag_details.open_token);
 421 |                             }
 422 |                             self.state = .default;
 423 |                         },
 424 |                         .element_attribute => {
 425 |                             try self.builder.appendAttribute(token.inner);
 426 |                         },
 427 |                         .element_attribute_value => {
 428 |                             try self.builder.setLastAttributeValue(token.inner);
 429 |                         },
 430 |                         else => unreachable,
 431 |                     }
 432 |                 },
 433 |             }
 434 |         }
 435 | 
 436 |         pub fn finalise(self: *StateMachineT) !Tree {
 437 |             while (self.builder.getStackSize() > 1) {
 438 |                 const open_token = try self.builder.getOpenToken() orelse unreachable;
 439 |                 try self.builder.reportDefectOrExit(.tag_never_closed, &.{open_token});
 440 |                 try self.builder.popStack();
 441 |             }
 442 | 
 443 |             const root_children = try self.builder.getOwnedChildren();
 444 |             try self.builder.popStack();
 445 | 
 446 |             return .{ .children = root_children };
 447 |         }
 448 |     };
 449 | }
 450 | 
 451 | pub fn stateMachine(builder: anytype) StateMachine(@typeInfo(@TypeOf(builder)).pointer.child) {
 452 |     return .{ .builder = builder };
 453 | }
 454 | 
 455 | pub const RuntimeBuilder = struct {
 456 |     const TempTree = struct {
 457 |         maybe_open_token: ?Scanner.Token,
 458 |         children: std.array_list.Managed(Tree.Node),
 459 |     };
 460 | 
 461 |     temp_allocator: std.mem.Allocator,
 462 |     data_allocator: std.mem.Allocator,
 463 |     maybe_diagnostics: ?*Diagnostics,
 464 | 
 465 |     stack: std.array_list.Managed(TempTree),
 466 |     attributes: ?std.array_list.Managed(Tree.Node.Elem.Attr),
 467 | 
 468 |     pub fn init(
 469 |         temp_allocator: std.mem.Allocator,
 470 |         data_allocator: std.mem.Allocator,
 471 |         maybe_diagnostics: ?*Diagnostics,
 472 |     ) !RuntimeBuilder {
 473 |         const root: TempTree = .{
 474 |             .maybe_open_token = null,
 475 |             .children = std.array_list.Managed(Tree.Node).init(data_allocator),
 476 |         };
 477 |         var stack = try std.array_list.Managed(TempTree).initCapacity(temp_allocator, 8);
 478 |         try stack.append(root);
 479 |         return .{
 480 |             .temp_allocator = temp_allocator,
 481 |             .data_allocator = data_allocator,
 482 |             .maybe_diagnostics = maybe_diagnostics,
 483 |             .stack = stack,
 484 |             .attributes = null,
 485 |         };
 486 |     }
 487 | 
 488 |     pub fn deinit(self: *RuntimeBuilder) void {
 489 |         if (self.attributes) |*attr| {
 490 |             attr.deinit();
 491 |             self.attributes = null;
 492 |         }
 493 |         var i = self.stack.items.len;
 494 |         while (i > 0) {
 495 |             i -= 1;
 496 |             const temp_tree = &self.stack.items[i];
 497 |             var j = temp_tree.children.items.len;
 498 |             while (j > 0) {
 499 |                 j -= 1;
 500 |                 var child_node = &temp_tree.children.items[j];
 501 |                 child_node.freeRecursive(self.data_allocator);
 502 |             }
 503 |             if (temp_tree.maybe_open_token) |open_token| {
 504 |                 self.data_allocator.free(open_token.inner);
 505 |             }
 506 |         }
 507 |         self.stack.deinit();
 508 |     }
 509 | 
 510 |     fn reportDefectOrExit(self: *RuntimeBuilder, defectKind: Diagnostics.Defect.Kind, tokens: []const Scanner.Token) !void {
 511 |         const diagnostics = self.maybe_diagnostics orelse return Error.XmlDefect;
 512 |         try diagnostics.reportDefect(defectKind, tokens);
 513 |     }
 514 | 
 515 |     pub fn copyToken(self: *RuntimeBuilder, token: Scanner.Token) !Scanner.Token {
 516 |         var copied = token;
 517 |         copied.inner = try self.data_allocator.dupe(u8, token.inner);
 518 |         return copied;
 519 |     }
 520 | 
 521 |     pub fn getOpenToken(self: *RuntimeBuilder) !?Scanner.Token {
 522 |         std.debug.assert(self.stack.items.len > 0);
 523 |         return self.stack.getLast().maybe_open_token;
 524 |     }
 525 | 
 526 |     pub fn getOwnedChildren(self: *RuntimeBuilder) ![]const Tree.Node {
 527 |         std.debug.assert(self.stack.items.len > 0);
 528 |         return try self.stack.items[self.stack.items.len - 1].children.toOwnedSlice();
 529 |     }
 530 | 
 531 |     pub fn getStackSize(self: *RuntimeBuilder) usize {
 532 |         return self.stack.items.len;
 533 |     }
 534 | 
 535 |     pub fn pushStack(self: *RuntimeBuilder, open_token: Scanner.Token) !void {
 536 |         try self.stack.append(.{
 537 |             .maybe_open_token = open_token,
 538 |             .children = std.array_list.Managed(Tree.Node).init(self.data_allocator),
 539 |         });
 540 |     }
 541 | 
 542 |     pub fn popStack(self: *RuntimeBuilder) !void {
 543 |         std.debug.assert(self.stack.items.len > 0);
 544 |         _ = self.stack.pop();
 545 |     }
 546 | 
 547 |     pub fn addNode(self: *RuntimeBuilder, node: Tree.Node) !void {
 548 |         std.debug.assert(self.stack.items.len > 0);
 549 |         const last = &self.stack.items[self.stack.items.len - 1];
 550 |         try last.children.append(node);
 551 |     }
 552 | 
 553 |     pub fn setElementTree(self: *RuntimeBuilder, tree: Tree) !void {
 554 |         std.debug.assert(self.stack.items.len > 0);
 555 |         const last = &self.stack.items[self.stack.items.len - 1];
 556 |         const last_child = &last.children.items[last.children.items.len - 1];
 557 |         std.debug.assert(last_child.* == .elem);
 558 |         std.debug.assert(last_child.elem.tree == null);
 559 |         last_child.elem.tree = tree;
 560 |     }
 561 | 
 562 |     pub fn addComment(self: *RuntimeBuilder) !void {
 563 |         std.debug.assert(self.stack.items.len > 0);
 564 |         const last = &self.stack.items[self.stack.items.len - 1];
 565 |         try last.children.append(.{ .comment = .{
 566 |             .contents = &.{},
 567 |         } });
 568 |     }
 569 | 
 570 |     pub fn closeComment(self: *RuntimeBuilder) !void {
 571 |         std.debug.assert(self.stack.items.len > 0);
 572 |         const last = &self.stack.items[self.stack.items.len - 1];
 573 |         std.debug.assert(last.children.items.len > 0);
 574 |         std.debug.assert(last.children.items[last.children.items.len - 1] == .comment);
 575 |         try last.children.append(.{ .text = .{
 576 |             .contents = &.{},
 577 |         } });
 578 |     }
 579 | 
 580 |     pub fn addCdata(self: *RuntimeBuilder) !void {
 581 |         std.debug.assert(self.stack.items.len > 0);
 582 |         const last = &self.stack.items[self.stack.items.len - 1];
 583 |         try last.children.append(.{
 584 |             .cdata = .{ .contents = &.{} },
 585 |         });
 586 |     }
 587 | 
 588 |     pub fn closeCdata(self: *RuntimeBuilder) !void {
 589 |         std.debug.assert(self.stack.items.len > 0);
 590 |         const last = &self.stack.items[self.stack.items.len - 1];
 591 |         std.debug.assert(last.children.items.len > 0);
 592 |         std.debug.assert(last.children.items[last.children.items.len - 1] == .cdata);
 593 |         try last.children.append(.{ .text = .{
 594 |             .contents = &.{},
 595 |         } });
 596 |     }
 597 | 
 598 |     pub fn appendTextChunk(self: *RuntimeBuilder, text_content: []const u8) !void {
 599 |         std.debug.assert(self.stack.items.len > 0);
 600 |         const last = &self.stack.items[self.stack.items.len - 1];
 601 |         if (last.children.items.len > 0) {
 602 |             const last_node = &last.children.items[last.children.items.len - 1];
 603 |             switch (last_node.*) {
 604 |                 inline .text, .comment, .cdata => |*text_node| {
 605 |                     const concat = try self.data_allocator.alloc(u8, text_node.contents.len + text_content.len);
 606 |                     @memcpy(concat[0..text_node.contents.len], text_node.contents);
 607 |                     @memcpy(concat[text_node.contents.len..], text_content);
 608 |                     self.data_allocator.free(text_node.contents);
 609 |                     text_node.contents = concat;
 610 |                     return;
 611 |                 },
 612 |                 else => {},
 613 |             }
 614 |         }
 615 |         try last.children.append(.{ .text = .{
 616 |             .contents = try self.data_allocator.dupe(u8, text_content),
 617 |         } });
 618 |     }
 619 | 
 620 |     pub fn buildAttributes(self: *RuntimeBuilder) !void {
 621 |         std.debug.assert(self.attributes == null);
 622 |         self.attributes = std.array_list.Managed(Tree.Node.Elem.Attr).init(self.data_allocator);
 623 |     }
 624 | 
 625 |     pub fn getAttributesOwned(self: *RuntimeBuilder) ![]const Tree.Node.Elem.Attr {
 626 |         std.debug.assert(self.attributes != null);
 627 |         const owned = try self.attributes.?.toOwnedSlice();
 628 |         self.attributes = null;
 629 |         return owned;
 630 |     }
 631 | 
 632 |     pub fn appendAttribute(self: *RuntimeBuilder, attr_name: []const u8) !void {
 633 |         std.debug.assert(self.attributes != null);
 634 |         try self.attributes.?.append(.{
 635 |             .name = try self.data_allocator.dupe(u8, attr_name),
 636 |             .value = null,
 637 |         });
 638 |     }
 639 | 
 640 |     pub fn setLastAttributeValue(self: *RuntimeBuilder, attr_value: []const u8) !void {
 641 |         std.debug.assert(self.attributes != null);
 642 |         std.debug.assert(self.attributes.?.items.len > 0);
 643 | 
 644 |         self.attributes.?.items[self.attributes.?.items.len - 1].value =
 645 |             try self.data_allocator.dupe(u8, attr_value);
 646 |     }
 647 | };
 648 | 
 649 | pub const ComptimeBuilder = struct {
 650 |     const TempTree = struct {
 651 |         maybe_open_token: ?Scanner.Token,
 652 |         children: []const Tree.Node,
 653 |     };
 654 | 
 655 |     stack: []const TempTree = &.{.{
 656 |         .maybe_open_token = null,
 657 |         .children = &.{},
 658 |     }},
 659 |     attributes: ?[]const Tree.Node.Elem.Attr = null,
 660 | 
 661 |     pub fn deinit(self: ComptimeBuilder) void {
 662 |         self.stack.deinit();
 663 |     }
 664 | 
 665 |     fn reportDefectOrExit(self: ComptimeBuilder, defectKind: Diagnostics.Defect.Kind, tokens: []const Scanner.Token) !void {
 666 |         _ = self;
 667 |         _ = defectKind;
 668 |         _ = tokens;
 669 |         return Error.XmlDefect;
 670 |     }
 671 | 
 672 |     pub fn copyToken(_: *ComptimeBuilder, token: Scanner.Token) !Scanner.Token {
 673 |         return token;
 674 |     }
 675 | 
 676 |     pub fn buildAttributes(self: *ComptimeBuilder) !void {
 677 |         std.debug.assert(self.attributes == null);
 678 |         self.attributes = &.{};
 679 |     }
 680 | 
 681 |     pub fn getOpenToken(self: *ComptimeBuilder) !?Scanner.Token {
 682 |         std.debug.assert(self.stack.len > 0);
 683 |         return self.stack[self.stack.len - 1].maybe_open_token;
 684 |     }
 685 | 
 686 |     pub fn getOwnedChildren(self: *ComptimeBuilder) ![]const Tree.Node {
 687 |         std.debug.assert(self.stack.len > 0);
 688 |         return self.stack[self.stack.len - 1].children;
 689 |     }
 690 | 
 691 |     pub fn getStackSize(self: *ComptimeBuilder) usize {
 692 |         return self.stack.len;
 693 |     }
 694 | 
 695 |     pub fn pushStack(self: *ComptimeBuilder, open_token: Scanner.Token) !void {
 696 |         self.stack = self.stack ++ .{ComptimeBuilder.TempTree{
 697 |             .maybe_open_token = open_token,
 698 |             .children = &.{},
 699 |         }};
 700 |     }
 701 | 
 702 |     pub fn popStack(self: *ComptimeBuilder) !void {
 703 |         std.debug.assert(self.stack.len > 0);
 704 |         self.stack = self.stack[0 .. self.stack.len - 1];
 705 |     }
 706 | 
 707 |     pub fn addNode(self: *ComptimeBuilder, node: Tree.Node) !void {
 708 |         std.debug.assert(self.stack.len > 0);
 709 |         const last = self.stack[self.stack.len - 1];
 710 |         const temp_children: []const Tree.Node = if (last.children.len == 0) &.{} else last.children;
 711 |         self.stack = self.stack[0 .. self.stack.len - 1] ++ .{
 712 |             ComptimeBuilder.TempTree{
 713 |                 .maybe_open_token = last.maybe_open_token,
 714 |                 .children = temp_children ++ .{node},
 715 |             },
 716 |         };
 717 |     }
 718 | 
 719 |     pub fn setElementTree(self: *ComptimeBuilder, tree: Tree) !void {
 720 |         std.debug.assert(self.stack.len > 0);
 721 |         const last = self.stack[self.stack.len - 1];
 722 |         const last_child = last.children[last.children.len - 1];
 723 |         std.debug.assert(last_child == .elem);
 724 |         std.debug.assert(last_child.elem.tree == null);
 725 |         self.stack = self.stack[0 .. self.stack.len - 1] ++ .{ComptimeBuilder.TempTree{
 726 |             .maybe_open_token = last.maybe_open_token,
 727 |             .children = last.children[0 .. last.children.len - 1] ++ .{
 728 |                 Tree.Node{ .elem = .{
 729 |                     .tag_name = last_child.elem.tag_name,
 730 |                     .attributes = last_child.elem.attributes,
 731 |                     .tree = tree,
 732 |                 } },
 733 |             },
 734 |         }};
 735 |     }
 736 | 
 737 |     pub fn addComment(self: *ComptimeBuilder) !void {
 738 |         std.debug.assert(self.stack.len > 0);
 739 |         const last = self.stack[self.stack.len - 1];
 740 |         const temp_children: []const Tree.Node = if (last.children.len == 0) &.{} else last.children;
 741 |         self.stack = self.stack[0 .. self.stack.len - 1] ++ .{ComptimeBuilder.TempTree{
 742 |             .maybe_open_token = last.maybe_open_token,
 743 |             .children = temp_children ++ .{Tree.Node{
 744 |                 .comment = .{ .contents = &.{} },
 745 |             }},
 746 |         }};
 747 |     }
 748 | 
 749 |     pub fn closeComment(self: *ComptimeBuilder) !void {
 750 |         std.debug.assert(self.stack.len > 0);
 751 |         const last = self.stack[self.stack.len - 1];
 752 |         std.debug.assert(last.children.len > 0);
 753 |         const temp_children: []const Tree.Node = if (last.children.len == 0) &.{} else last.children;
 754 |         std.debug.assert(last.children[last.children.len - 1] == .comment);
 755 |         self.stack = self.stack[0 .. self.stack.len - 1] ++ .{ComptimeBuilder.TempTree{
 756 |             .maybe_open_token = last.maybe_open_token,
 757 |             .children = temp_children ++ .{Tree.Node{
 758 |                 .text = .{ .contents = &.{} },
 759 |             }},
 760 |         }};
 761 |     }
 762 |     
 763 |     pub fn addCdata(self: *ComptimeBuilder) !void {
 764 |         std.debug.assert(self.stack.len > 0);
 765 |         const last = self.stack[self.stack.len - 1];
 766 |         const temp_children: []const Tree.Node = if (last.children.len == 0) &.{} else last.children;
 767 |         self.stack = self.stack[0 .. self.stack.len - 1] ++ .{ComptimeBuilder.TempTree{
 768 |             .maybe_open_token = last.maybe_open_token,
 769 |             .children = temp_children ++ .{Tree.Node{
 770 |                 .cdata = .{ .contents = &.{} },
 771 |             }},
 772 |         }};
 773 |     }
 774 | 
 775 |     pub fn closeCdata(self: *ComptimeBuilder) !void {
 776 |         std.debug.assert(self.stack.len > 0);
 777 |         const last = self.stack[self.stack.len - 1];
 778 |         std.debug.assert(last.children.len > 0);
 779 |         const temp_children: []const Tree.Node = if (last.children.len == 0) &.{} else last.children;
 780 |         std.debug.assert(last.children[last.children.len - 1] == .cdata);
 781 |         self.stack = self.stack[0 .. self.stack.len - 1] ++ .{ComptimeBuilder.TempTree{
 782 |             .maybe_open_token = last.maybe_open_token,
 783 |             .children = temp_children ++ .{Tree.Node{
 784 |                 .text = .{ .contents = &.{} },
 785 |             }},
 786 |         }};
 787 |     }
 788 | 
 789 |     pub fn appendTextChunk(self: *ComptimeBuilder, text_content: []const u8) !void {
 790 |         std.debug.assert(self.stack.len > 0);
 791 |         const last = self.stack[self.stack.len - 1];
 792 |         if (last.children.len > 0) {
 793 |             const last_node = last.children[last.children.len - 1];
 794 |             switch (last_node) {
 795 |                 inline .text, .comment, .cdata => |text_node, tag| {
 796 |                     const previous_contents: []const u8 = if (text_node.contents.len > 0) text_node.contents else &.{};
 797 |                     const contents = previous_contents ++ text_content;
 798 |                     self.stack = self.stack[0 .. self.stack.len - 1] ++ .{ComptimeBuilder.TempTree{
 799 |                         .maybe_open_token = last.maybe_open_token,
 800 |                         .children = last.children[0 .. last.children.len - 1] ++ .{
 801 |                             switch (tag) {
 802 |                                 .text => Tree.Node{ .text = .{ .contents = contents } },
 803 |                                 .comment => Tree.Node{ .comment = .{ .contents = contents } },
 804 |                                 .cdata => Tree.Node{ .cdata = .{ .contents = contents } },
 805 |                                 else => unreachable,
 806 |                             },
 807 |                         },
 808 |                     }};
 809 |                     return;
 810 |                 },
 811 |                 else => {},
 812 |             }
 813 |         }
 814 | 
 815 |         const temp_children: []const Tree.Node = if (last.children.len > 0) last.children else &.{};
 816 |         self.stack = self.stack[0 .. self.stack.len - 1] ++ .{ComptimeBuilder.TempTree{
 817 |             .maybe_open_token = last.maybe_open_token,
 818 |             .children = temp_children ++ .{Tree.Node{
 819 |                 .text = .{ .contents = text_content },
 820 |             }},
 821 |         }};
 822 |     }
 823 | 
 824 |     pub fn getAttributesOwned(self: *ComptimeBuilder) ![]const Tree.Node.Elem.Attr {
 825 |         std.debug.assert(self.attributes != null);
 826 |         defer self.attributes = null;
 827 |         return self.attributes.?;
 828 |     }
 829 | 
 830 |     pub fn appendAttribute(self: *ComptimeBuilder, attr_name: []const u8) !void {
 831 |         std.debug.assert(self.attributes != null);
 832 |         self.attributes = self.attributes.? ++ .{Tree.Node.Elem.Attr{
 833 |             .name = attr_name,
 834 |             .value = null,
 835 |         }};
 836 |     }
 837 | 
 838 |     pub fn setLastAttributeValue(self: *ComptimeBuilder, attr_value: []const u8) !void {
 839 |         std.debug.assert(self.attributes != null);
 840 |         std.debug.assert(self.attributes.?.len > 0);
 841 | 
 842 |         const last_attr = self.attributes.?[self.attributes.?.len - 1];
 843 |         self.attributes = self.attributes.?[0 .. self.attributes.?.len - 1] ++ .{Tree.Node.Elem.Attr{
 844 |             .name = last_attr.name,
 845 |             .value = attr_value,
 846 |         }};
 847 |     }
 848 | };
 849 | 
 850 | fn fromScannerImpl(
 851 |     temp_allocator: std.mem.Allocator,
 852 |     data_allocator: std.mem.Allocator,
 853 |     scanner_or_reader: *Scanner,
 854 |     maybe_diagnostics: ?*Diagnostics,
 855 | ) !Tree {
 856 |     var builder = try RuntimeBuilder.init(temp_allocator, data_allocator, maybe_diagnostics);
 857 |     defer builder.deinit();
 858 | 
 859 |     var state = stateMachine(&builder);
 860 |     while (try scanner_or_reader.next()) |token| {
 861 |         try state.feedToken(token);
 862 |     }
 863 | 
 864 |     return try state.finalise();
 865 | }
 866 | 
 867 | fn fromSliceImpl(
 868 |     temp_allocator: std.mem.Allocator,
 869 |     data_allocator: std.mem.Allocator,
 870 |     slice: []const u8,
 871 |     maybe_diagnostics: ?*Diagnostics,
 872 | ) !Tree {
 873 |     var reader: std.Io.Reader = .fixed(slice);
 874 |     var xml_scanner: Scanner = .{ .reader = &reader };
 875 |     return fromScannerImpl(temp_allocator, data_allocator, &xml_scanner, maybe_diagnostics);
 876 | }
 877 | 
 878 | fn fromSliceArenaImpl(
 879 |     allocator: std.mem.Allocator,
 880 |     slice: []const u8,
 881 |     maybe_diagnostics: ?*Diagnostics,
 882 | ) !Tree.Owned {
 883 |     var arena = std.heap.ArenaAllocator.init(allocator);
 884 |     errdefer arena.deinit();
 885 | 
 886 |     const tree = try fromSliceImpl(allocator, arena.allocator(), slice, maybe_diagnostics);
 887 | 
 888 |     return .{
 889 |         .arena = arena,
 890 |         .tree = tree,
 891 |     };
 892 | }
 893 | 
 894 | /// Parse an entire XML tree from a slice, owning all allocations and tracking parse errors.
 895 | pub fn fromSliceDiagnosticsOwned(
 896 |     allocator: std.mem.Allocator,
 897 |     slice: []const u8,
 898 |     diagnostics: *Diagnostics,
 899 | ) !Tree.Owned {
 900 |     return try fromSliceImpl(allocator, allocator, slice, diagnostics);
 901 | }
 902 | 
 903 | /// Parse an entire XML tree from a slice, with all allocations done through an arena and tracking parse errors.
 904 | pub fn fromSliceDiagnostics(
 905 |     allocator: std.mem.Allocator,
 906 |     slice: []const u8,
 907 |     diagnostics: *Diagnostics,
 908 | ) !Tree.Owned {
 909 |     return try fromSliceArenaImpl(allocator, slice, diagnostics);
 910 | }
 911 | 
 912 | /// Parse an entire XML tree from a slice, owning all allocations.
 913 | pub fn fromSliceOwned(allocator: std.mem.Allocator, slice: []const u8) !Tree {
 914 |     return try fromSliceImpl(allocator, allocator, slice, null);
 915 | }
 916 | 
 917 | /// Parse an entire XML tree from a slice, with all allocations done through an arena.
 918 | pub fn fromSlice(allocator: std.mem.Allocator, slice: []const u8) !Tree.Owned {
 919 |     var arena = std.heap.ArenaAllocator.init(allocator);
 920 |     errdefer arena.deinit();
 921 | 
 922 |     return fromSliceArenaImpl(allocator, slice, null);
 923 | }
 924 | 
 925 | fn fromReaderImpl(
 926 |     temp_allocator: std.mem.Allocator,
 927 |     data_allocator: std.mem.Allocator,
 928 |     reader: *std.Io.Reader,
 929 |     maybe_diagnostics: ?*Diagnostics,
 930 | ) !Tree {
 931 |     var xml_scanner: Scanner = .{ .reader = reader };
 932 |     return fromScannerImpl(temp_allocator, data_allocator, &xml_scanner, maybe_diagnostics);
 933 | }
 934 | 
 935 | fn fromReaderArenaImpl(
 936 |     allocator: std.mem.Allocator,
 937 |     reader: *std.Io.Reader,
 938 |     maybe_diagnostics: ?*Diagnostics,
 939 | ) !Tree.Owned {
 940 |     var arena = std.heap.ArenaAllocator.init(allocator);
 941 |     errdefer arena.deinit();
 942 | 
 943 |     const tree = try fromReaderImpl(allocator, arena.allocator(), reader, maybe_diagnostics);
 944 | 
 945 |     return .{
 946 |         .arena = arena,
 947 |         .tree = tree,
 948 |     };
 949 | }
 950 | 
 951 | /// Parse an entire XML tree from a reader, owning all allocations and tracking parse errors.
 952 | pub fn fromReaderDiagnosticsOwned(
 953 |     allocator: std.mem.Allocator,
 954 |     reader: *std.Io.Reader,
 955 |     diagnostics: *Diagnostics,
 956 | ) !Tree.Owned {
 957 |     return try fromReaderImpl(allocator, allocator, reader, diagnostics);
 958 | }
 959 | 
 960 | /// Parse an entire XML tree from a reader, with all allocations done through an arena and tracking parse errors.
 961 | pub fn fromReaderDiagnostics(
 962 |     allocator: std.mem.Allocator,
 963 |     reader: *std.Io.Reader,
 964 |     diagnostics: *Diagnostics,
 965 | ) !Tree.Owned {
 966 |     return try fromReaderArenaImpl(allocator, reader, diagnostics);
 967 | }
 968 | 
 969 | /// Parse an entire XML tree from a reader, owning all allocations.
 970 | pub fn fromReaderOwned(allocator: std.mem.Allocator, reader: *std.Io.Reader) !Tree {
 971 |     return try fromReaderImpl(allocator, allocator, reader, null);
 972 | }
 973 | 
 974 | /// Parse an entire XML tree from a reader, with all allocations done through an arena.
 975 | pub fn fromReader(allocator: std.mem.Allocator, reader: *std.Io.Reader) !Tree.Owned {
 976 |     var arena = std.heap.ArenaAllocator.init(allocator);
 977 |     errdefer arena.deinit();
 978 | 
 979 |     return fromReaderArenaImpl(allocator, reader, null);
 980 | }
 981 | 
 982 | /// Parse an entire XML tree from a slice known at compile time.
 983 | pub inline fn fromSliceComptime(comptime slice: []const u8) !Tree {
 984 |     return comptime blk: {
 985 |         @setEvalBranchQuota(slice.len * 8); // should be a good upper-limit
 986 | 
 987 |         var reader: std.Io.Reader = .fixed(slice);
 988 | 
 989 |         var scanner: Scanner = .{ .reader = &reader };
 990 |         var builder = ComptimeBuilder{};
 991 |         var state = stateMachine(&builder);
 992 | 
 993 |         while (try scanner.next()) |token| {
 994 |             try state.feedToken(token);
 995 |         }
 996 | 
 997 |         break :blk try state.finalise();
 998 |     };
 999 | }
1000 | 
1001 | const test_buf = "<div betrayed-by=\"judas\">jesus <p>christ</p> lord <amen/></div>";
1002 | fn expectTestTreeValid(tree: Tree) !void {
1003 |     try std.testing.expectEqual(tree.children.len, 1);
1004 |     try std.testing.expect(tree.children[0] == .elem);
1005 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.tag_name, "div");
1006 |     try std.testing.expectEqual(tree.children[0].elem.attributes.len, 1);
1007 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.attributes[0].name, "betrayed-by");
1008 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.attributes[0].value.?, "judas");
1009 |     try std.testing.expect(tree.children[0].elem.tree != null);
1010 |     try std.testing.expectEqual(tree.children[0].elem.tree.?.children.len, 4);
1011 | 
1012 |     try std.testing.expect(tree.children[0].elem.tree.?.children[0] == .text);
1013 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.tree.?.children[0].text.contents, "jesus ");
1014 | 
1015 |     try std.testing.expect(tree.children[0].elem.tree.?.children[1] == .elem);
1016 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.tree.?.children[1].elem.tag_name, "p");
1017 |     try std.testing.expect(tree.children[0].elem.tree.?.children[0] == .text);
1018 |     try std.testing.expectEqual(tree.children[0].elem.tree.?.children[1].elem.attributes.len, 0);
1019 |     try std.testing.expect(tree.children[0].elem.tree.?.children[1].elem.tree != null);
1020 |     try std.testing.expectEqual(tree.children[0].elem.tree.?.children[1].elem.tree.?.children.len, 1);
1021 |     try std.testing.expect(tree.children[0].elem.tree.?.children[1].elem.tree.?.children[0] == .text);
1022 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.tree.?.children[1].elem.tree.?.children[0].text.contents, "christ");
1023 | 
1024 |     try std.testing.expect(tree.children[0].elem.tree.?.children[2] == .text);
1025 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.tree.?.children[2].text.contents, " lord ");
1026 | 
1027 |     try std.testing.expect(tree.children[0].elem.tree.?.children[3] == .elem);
1028 |     try std.testing.expectEqualSlices(u8, tree.children[0].elem.tree.?.children[3].elem.tag_name, "amen");
1029 |     try std.testing.expectEqual(tree.children[0].elem.tree.?.children[3].elem.attributes.len, 0);
1030 |     try std.testing.expect(tree.children[0].elem.tree.?.children[3].elem.tree == null);
1031 | }
1032 | 
1033 | test fromReader {
1034 |     var fixed_reader: std.Io.Reader = .fixed(test_buf);
1035 | 
1036 |     const parsed = try fromReader(std.testing.allocator, &fixed_reader);
1037 |     defer parsed.deinit();
1038 | 
1039 |     try expectTestTreeValid(parsed.tree);
1040 | }
1041 | 
1042 | test fromReaderOwned {
1043 |     var fixed_reader: std.Io.Reader = .fixed(test_buf);
1044 | 
1045 |     const tree = try fromReaderOwned(std.testing.allocator, &fixed_reader);
1046 |     defer tree.freeRecursive(std.testing.allocator);
1047 | 
1048 |     try expectTestTreeValid(tree);
1049 | }
1050 | 
1051 | test fromReaderDiagnostics {
1052 |     const buf = "<div><p></p>";
1053 |     var fixed_reader: std.Io.Reader = .fixed(buf);
1054 | 
1055 |     var diagnostics = Diagnostics.init(std.testing.allocator);
1056 |     defer diagnostics.deinit();
1057 | 
1058 |     const parsed = try fromReaderDiagnostics(std.testing.allocator, &fixed_reader, &diagnostics);
1059 |     defer parsed.deinit();
1060 | 
1061 |     try std.testing.expectEqual(diagnostics.defects.items.len, 1);
1062 | }
1063 | 
1064 | test fromSliceComptime {
1065 |     @setEvalBranchQuota(8192);
1066 |     const tree = try fromSliceComptime(test_buf);
1067 |     try expectTestTreeValid(tree);
1068 | }
1069 | 
1070 | test Tree {
1071 |     const tree: Tree = .{
1072 |         .children = &.{
1073 |             .{ .elem = .{
1074 |                 .tag_name = "person",
1075 |                 .attributes = &.{
1076 |                     .{ .name = "name", .value = "Jonas" },
1077 |                     .{ .name = "age", .value = "18" },
1078 |                 },
1079 |                 .tree = null,
1080 |             } },
1081 |             .{ .text = .{ .contents = "\n    this is a gap!!!    \n    \n    \n    " } },
1082 |             .{ .elem = .{
1083 |                 .tag_name = "goat",
1084 |                 .attributes = &.{},
1085 |                 .tree = null,
1086 |             } },
1087 |             .{ .elem = .{
1088 |                 .tag_name = "person",
1089 |                 .attributes = &.{
1090 |                     .{ .name = "name", .value = "Kyle" },
1091 |                     .{ .name = "age", .value = "24" },
1092 |                 },
1093 |                 .tree = null,
1094 |             } },
1095 |         },
1096 |     };
1097 | 
1098 |     const jonas = tree.elementByTagName("person");
1099 |     const jonas_alias = tree.elem("person");
1100 |     const kyle = tree.elementByAttributeValue("name", "Kyle");
1101 |     const kyle_alias = tree.elemByAttr("name", "Kyle");
1102 | 
1103 |     try std.testing.expect(jonas != null);
1104 |     try std.testing.expect(jonas_alias != null);
1105 |     try std.testing.expect(kyle != null);
1106 |     try std.testing.expect(kyle_alias != null);
1107 |     try std.testing.expectEqualSlices(u8, "person", jonas.?.tag_name);
1108 |     try std.testing.expectEqualSlices(u8, "person", jonas_alias.?.tag_name);
1109 |     try std.testing.expectEqualSlices(u8, "person", kyle.?.tag_name);
1110 |     try std.testing.expectEqualSlices(u8, "person", kyle_alias.?.tag_name);
1111 |     try std.testing.expectEqualSlices(u8, "Jonas", jonas.?.attributes[0].value.?);
1112 |     try std.testing.expectEqualSlices(u8, "Jonas", jonas_alias.?.attributes[0].value.?);
1113 |     try std.testing.expectEqualSlices(u8, "Kyle", kyle.?.attributes[0].value.?);
1114 |     try std.testing.expectEqualSlices(u8, "Kyle", kyle_alias.?.attributes[0].value.?);
1115 | 
1116 |     const jonas_name = tree.children[0].elem.attributeValueByName("name");
1117 |     const jonas_name_alias = tree.children[0].elem.attrValue("name");
1118 |     try std.testing.expect(jonas_name != null);
1119 |     try std.testing.expect(jonas_name_alias != null);
1120 |     try std.testing.expectEqualSlices(u8, "Jonas", jonas_name.?);
1121 |     try std.testing.expectEqualSlices(u8, "Jonas", jonas_name_alias.?);
1122 | 
1123 |     const all_people = try tree.elementsByTagNameAlloc(std.testing.allocator, "person");
1124 |     defer std.testing.allocator.free(all_people);
1125 | 
1126 |     try std.testing.expectEqual(2, all_people.len);
1127 |     try std.testing.expectEqualDeep(jonas.?, all_people[0]);
1128 |     try std.testing.expectEqualDeep(kyle.?, all_people[1]);
1129 | 
1130 |     const text = try tree.concatTextAlloc(std.testing.allocator);
1131 |     defer std.testing.allocator.free(text);
1132 |     const text2 = try tree.concatTextTrimmedAlloc(std.testing.allocator);
1133 |     defer std.testing.allocator.free(text2);
1134 | 
1135 |     try std.testing.expectEqualSlices(u8, "\n    this is a gap!!!    \n    \n    \n    ", text);
1136 |     try std.testing.expectEqualSlices(u8, "this is a gap!!!", text2);
1137 | }
1138 | 
1139 | test "parsing CDATA" {
1140 |     const payload =
1141 |         \\<item>
1142 |         \\  <title>Title #1</title>
1143 |         \\  <data><![CDATA[<a>foobar]]<br/>]]></data>
1144 |         \\</item>
1145 |     ;
1146 | 
1147 |     const result = try fromSlice(std.testing.allocator, payload);
1148 |     defer result.deinit();
1149 | 
1150 |     const item_tag = result.tree.elementByTagName("item").?;
1151 |     const data_tag = item_tag.tree.?.elementByTagName("data").?;
1152 |     try std.testing.expectEqualStrings("<a>foobar]]<br/>", data_tag.tree.?.children[0].cdata.contents);
1153 | }
1154 | 


--------------------------------------------------------------------------------