Add parser mode guidance doc

Author: ItsMeSamey

README.md

@@ -108,6 +108,18 @@ if (node == null) {
 }
 ```
 
+### Instrumentation hooks
+
+```zig
+var hooks = Hooks{};
+try html.parseWithHooks(&doc, &input, .{}, &hooks);
+_ = try html.queryOneRuntimeWithHooks(&doc, "a.primary", &hooks);
+```
+
+Reference examples:
+- `examples/debug_query_report.zig`
+- `examples/instrumentation_hooks.zig`
+
 ## Parse Option Recipes
 
 Two bundles are used by the benchmark harness and conformance runner:

bench/README.md

@@ -8,6 +8,7 @@ This directory benchmarks `htmlparser` against other high-performance HTML parse
 
 It also benchmarks `htmlparser` query parsing throughput (runtime selector compile path).
 Query sections remain `htmlparser`-only; external parser comparisons are parse throughput only.
+`query-parse` is mode-independent and is measured once (`ours`) to avoid duplicate compatibility rows.
 
 `htmlparser` parse results are reported in two internal benchmark modes:
 

docs/getting-started.md

@@ -49,6 +49,26 @@ _ = node;
 
 Source of truth: `examples/runtime_selector.zig` and `examples/compiled_selector.zig`.
 
+## Debug Diagnostics and Hooks
+
+Selector mismatch diagnostics:
+
+```zig
+var report: html.QueryDebugReport = .{};
+const node = try doc.queryOneRuntimeDebug("a[href^=https]", &report);
+_ = node;
+```
+
+Instrumentation wrappers:
+
+```zig
+var hooks = Hooks{};
+try html.parseWithHooks(&doc, &input, .{}, &hooks);
+_ = try html.queryOneRuntimeWithHooks(&doc, "a.primary", &hooks);
+```
+
+Source of truth: `examples/debug_query_report.zig` and `examples/instrumentation_hooks.zig`.
+
 ## Parse Options
 
 ```zig

examples/debug_query_report.zig

@@ -0,0 +1,23 @@
+const std = @import("std");
+const html = @import("htmlparser");
+const default_options: html.ParseOptions = .{};
+const Document = default_options.GetDocument();
+
+fn run() !void {
+    var doc = Document.init(std.testing.allocator);
+    defer doc.deinit();
+
+    var input = "<div><a id='one' class='nav'></a><a id='two'></a></div>".*;
+    try doc.parse(&input, .{});
+
+    var report: html.QueryDebugReport = .{};
+    const node = try doc.queryOneRuntimeDebug("a[href^=https]", &report);
+    try std.testing.expect(node == null);
+    try std.testing.expect(report.visited_elements > 0);
+    try std.testing.expect(report.near_miss_len > 0);
+    try std.testing.expect(report.near_misses[0].reason.kind != .none);
+}
+
+test "query debug report for selector mismatch" {
+    try run();
+}

examples/instrumentation_hooks.zig

@@ -0,0 +1,46 @@
+const std = @import("std");
+const html = @import("htmlparser");
+const default_options: html.ParseOptions = .{};
+const Document = default_options.GetDocument();
+
+const Hooks = struct {
+    parse_start_calls: usize = 0,
+    parse_end_calls: usize = 0,
+    query_start_calls: usize = 0,
+    query_end_calls: usize = 0,
+
+    pub fn onParseStart(self: *@This(), _: usize) void {
+        self.parse_start_calls += 1;
+    }
+
+    pub fn onParseEnd(self: *@This(), _: html.ParseInstrumentationStats) void {
+        self.parse_end_calls += 1;
+    }
+
+    pub fn onQueryStart(self: *@This(), _: html.QueryInstrumentationKind, _: usize) void {
+        self.query_start_calls += 1;
+    }
+
+    pub fn onQueryEnd(self: *@This(), _: html.QueryInstrumentationStats) void {
+        self.query_end_calls += 1;
+    }
+};
+
+fn run() !void {
+    var doc = Document.init(std.testing.allocator);
+    defer doc.deinit();
+
+    var hooks: Hooks = .{};
+    var input = "<div><span id='x'></span></div>".*;
+    try html.parseWithHooks(&doc, &input, .{}, &hooks);
+    try std.testing.expectEqual(@as(usize, 1), hooks.parse_start_calls);
+    try std.testing.expectEqual(@as(usize, 1), hooks.parse_end_calls);
+
+    _ = try html.queryOneRuntimeWithHooks(&doc, "span#x", &hooks);
+    try std.testing.expectEqual(@as(usize, 1), hooks.query_start_calls);
+    try std.testing.expectEqual(@as(usize, 1), hooks.query_end_calls);
+}
+
+test "instrumentation hook wrappers" {
+    try run();
+}

src/bench/bench.zig

@@ -14,20 +14,7 @@ fn parseMode(arg: []const u8) !BenchMode {
     return error.InvalidBenchMode;
 }
 
-fn parseDocForParseBench(noalias doc: *Document, input: []u8, mode: BenchMode) !void {
-    switch (mode) {
-        .strictest => try doc.parse(input, .{
-            .eager_child_views = true,
-            .drop_whitespace_text_nodes = false,
-        }),
-        .fastest => try doc.parse(input, .{
-            .eager_child_views = false,
-            .drop_whitespace_text_nodes = true,
-        }),
-    }
-}
-
-fn parseDocForQueryBench(noalias doc: *Document, input: []u8, mode: BenchMode) !void {
+fn parseDocForBench(noalias doc: *Document, input: []u8, mode: BenchMode) !void {
     switch (mode) {
         .strictest => try doc.parse(input, .{
             .eager_child_views = true,
@@ -92,9 +79,9 @@ pub fn runParseFile(path: []const u8, iterations: usize, mode: BenchMode) !u64 {
             defer doc.deinit();
             if (working_opt) |working| {
                 @memcpy(working, input);
-                try parseDocForParseBench(&doc, working, mode);
+                try parseDocForBench(&doc, working, mode);
             } else {
-                try parseDocForParseBench(&doc, input, mode);
+                try parseDocForBench(&doc, input, mode);
             }
         }
         _ = parse_arena.reset(.retain_capacity);
@@ -136,7 +123,7 @@ pub fn runQueryMatch(path: []const u8, selector: []const u8, iterations: usize,
 
     var doc = Document.init(alloc);
     defer doc.deinit();
-    try parseDocForQueryBench(&doc, working, mode);
+    try parseDocForBench(&doc, working, mode);
 
     const start = std.time.nanoTimestamp();
     var i: usize = 0;
@@ -166,7 +153,7 @@ pub fn runQueryCompiled(path: []const u8, selector: []const u8, iterations: usiz
 
     var doc = Document.init(alloc);
     defer doc.deinit();
-    try parseDocForQueryBench(&doc, working, mode);
+    try parseDocForBench(&doc, working, mode);
 
     const start = std.time.nanoTimestamp();
     var i: usize = 0;
@@ -198,14 +185,6 @@ pub fn main() !void {
         return;
     }
 
-    if (args.len == 5 and std.mem.eql(u8, args[1], "query-parse")) {
-        _ = try parseMode(args[2]);
-        const iterations = try std.fmt.parseInt(usize, args[4], 10);
-        const total_ns = try runQueryParse(args[3], iterations);
-        std.debug.print("{d}\n", .{total_ns});
-        return;
-    }
-
     if (args.len == 5 and std.mem.eql(u8, args[1], "query-match")) {
         const iterations = try std.fmt.parseInt(usize, args[4], 10);
         const total_ns = try runQueryMatch(args[2], args[3], iterations, .fastest);
@@ -246,8 +225,8 @@ pub fn main() !void {
 
     if (args.len != 3) {
         std.debug.print(
-            "usage:\n  {s} <html-file> <iterations>\n  {s} parse <strictest|fastest> <html-file> <iterations>\n  {s} query-parse <selector> <iterations>\n  {s} query-parse <strictest|fastest> <selector> <iterations>\n  {s} query-match <html-file> <selector> <iterations>\n  {s} query-match <strictest|fastest> <html-file> <selector> <iterations>\n  {s} query-compiled <html-file> <selector> <iterations>\n  {s} query-compiled <strictest|fastest> <html-file> <selector> <iterations>\n",
-            .{ args[0], args[0], args[0], args[0], args[0], args[0], args[0], args[0] },
+            "usage:\n  {s} <html-file> <iterations>\n  {s} parse <strictest|fastest> <html-file> <iterations>\n  {s} query-parse <selector> <iterations>\n  {s} query-match <html-file> <selector> <iterations>\n  {s} query-match <strictest|fastest> <html-file> <selector> <iterations>\n  {s} query-compiled <html-file> <selector> <iterations>\n  {s} query-compiled <strictest|fastest> <html-file> <selector> <iterations>\n",
+            .{ args[0], args[0], args[0], args[0], args[0], args[0], args[0] },
         );
         std.process.exit(2);
     }

src/examples_tests.zig

@@ -122,3 +122,53 @@ test "example parity: strictest and fastest selectors agree" {
     try std.testing.expectEqual(@as(usize, 2), strictest_count);
     try std.testing.expectEqual(strictest_count, fastest_count);
 }
+
+test "example parity: debug query report" {
+    var doc = Document.init(std.testing.allocator);
+    defer doc.deinit();
+
+    var input = "<div><a id='one' class='nav'></a><a id='two'></a></div>".*;
+    try doc.parse(&input, .{});
+
+    var report: html.QueryDebugReport = .{};
+    const node = try doc.queryOneRuntimeDebug("a[href^=https]", &report);
+    try std.testing.expect(node == null);
+    try std.testing.expect(report.visited_elements > 0);
+    try std.testing.expect(report.near_miss_len > 0);
+    try std.testing.expect(report.near_misses[0].reason.kind != .none);
+}
+
+test "example parity: instrumentation hooks" {
+    const Hooks = struct {
+        parse_start_calls: usize = 0,
+        parse_end_calls: usize = 0,
+        query_start_calls: usize = 0,
+        query_end_calls: usize = 0,
+
+        pub fn onParseStart(self: *@This(), _: usize) void {
+            self.parse_start_calls += 1;
+        }
+        pub fn onParseEnd(self: *@This(), _: html.ParseInstrumentationStats) void {
+            self.parse_end_calls += 1;
+        }
+        pub fn onQueryStart(self: *@This(), _: html.QueryInstrumentationKind, _: usize) void {
+            self.query_start_calls += 1;
+        }
+        pub fn onQueryEnd(self: *@This(), _: html.QueryInstrumentationStats) void {
+            self.query_end_calls += 1;
+        }
+    };
+
+    var doc = Document.init(std.testing.allocator);
+    defer doc.deinit();
+    var hooks: Hooks = .{};
+
+    var input = "<div><span id='x'></span></div>".*;
+    try html.parseWithHooks(&doc, &input, .{}, &hooks);
+    _ = try html.queryOneRuntimeWithHooks(&doc, "span#x", &hooks);
+
+    try std.testing.expectEqual(@as(usize, 1), hooks.parse_start_calls);
+    try std.testing.expectEqual(@as(usize, 1), hooks.parse_end_calls);
+    try std.testing.expectEqual(@as(usize, 1), hooks.query_start_calls);
+    try std.testing.expectEqual(@as(usize, 1), hooks.query_end_calls);
+}

src/html/document.zig

@@ -1408,25 +1408,25 @@ test "leading child combinator works in node-scoped queries" {
     try std.testing.expectEqual(@as(usize, 1), hsoob_count);
 }
 
-test "attribute parsing preserves selector/query behavior for representative input" {
+test "parse option bundles preserve selector/query behavior for representative input" {
     const alloc = std.testing.allocator;
 
-    var eager_doc = Document.init(alloc);
-    defer eager_doc.deinit();
-    var deferred_doc = Document.init(alloc);
-    defer deferred_doc.deinit();
+    var strict_doc = Document.init(alloc);
+    defer strict_doc.deinit();
+    var fast_doc = Document.init(alloc);
+    defer fast_doc.deinit();
 
-    var eager_html = ("<html><body>" ++
+    var strict_html = ("<html><body>" ++
         "<div id='x' class='alpha beta' data-k='v' data-q='1>2'>x</div>" ++
         "<img id='im' src='a.png' />" ++
         "<a id='a1' href='https://example.com' class='nav button'>ok</a>" ++
         "<p id='p1'>a<span id='s1'>b</span></p>" ++
         "<div id='e' a= ></div>" ++
         "</body></html>").*;
-    var deferred_html = eager_html;
+    var fast_html = strict_html;
 
-    try eager_doc.parse(&eager_html, .{});
-    try deferred_doc.parse(&deferred_html, .{
+    try strict_doc.parse(&strict_html, .{});
+    try fast_doc.parse(&fast_html, .{
         .eager_child_views = false,
     });
 
@@ -1439,14 +1439,14 @@ test "attribute parsing preserves selector/query behavior for representative inp
     };
 
     for (selectors) |sel| {
-        const a = try eager_doc.queryOneRuntime(sel);
-        const b = try deferred_doc.queryOneRuntime(sel);
+        const a = try strict_doc.queryOneRuntime(sel);
+        const b = try fast_doc.queryOneRuntime(sel);
         try std.testing.expect((a == null) == (b == null));
     }
 
-    const eager_empty = (eager_doc.queryOne("#e") orelse return error.TestUnexpectedResult).getAttributeValue("a") orelse return error.TestUnexpectedResult;
-    const deferred_empty = (deferred_doc.queryOne("#e") orelse return error.TestUnexpectedResult).getAttributeValue("a") orelse return error.TestUnexpectedResult;
-    try std.testing.expectEqualStrings(eager_empty, deferred_empty);
+    const strict_empty = (strict_doc.queryOne("#e") orelse return error.TestUnexpectedResult).getAttributeValue("a") orelse return error.TestUnexpectedResult;
+    const fast_empty = (fast_doc.queryOne("#e") orelse return error.TestUnexpectedResult).getAttributeValue("a") orelse return error.TestUnexpectedResult;
+    try std.testing.expectEqualStrings(strict_empty, fast_empty);
 }
 
 test "attribute scanner handles quoted > and self-closing tails" {