Skip to content
carlos-swebPublic

About

Complete Zig 0.16 bindings and idiomatic wrapper for the lexbor HTML engine - vendored, hermetic, cross-platform

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

z-lexbor

Zig 0.17 bindings and idiomatic wrapper for the lexbor HTML engine.

The entire lexbor API is reachable from Zig, and the engine is compiled from vendored sources by zig build — no CMake, no pkg-config, no system lexbor.

View the published API documentation

const lexbor = @import("z_lexbor");

var parser = try lexbor.html.Parser.createInit();
defer parser.deinit();

const doc = try parser.parse("<div class=a><p>one</p><p>two</p></div>");

var engine = try lexbor.selectors.Engine.createInit();
defer engine.deinit();

var found = try engine.queryAll(allocator, doc.rootNode().?, "div.a > p");
defer found.deinit(allocator);

Guarantees

Guarantee How it is enforced
Complete API coverage zig build check-coverage parses all 226 public headers and fails if any of the 2408 public function-like names is missing from the bindings (currently 0 missing, 2740 extern fn emitted)
Hermetic, version-pinned engine lexbor v3.0.1 (7e278c0) vendored under vendor/lexbor/; the build never reads a system lexbor
Cross-platform x86_64-linux, aarch64-linux, x86_64-windows-gnu and wasm32-wasi all compile and link (see CI)
Easy integration verified by tools/check-consumer.sh, which builds a standalone project against this package

Every figure above, the method behind it, the assumptions that turned out to be wrong and the limits of what was checked are written up in AUDIT.md. | Behaviour is pinned by tests | 248 tests: exhaustive status mapping, OOM injection, deterministic fuzzing and adversarial input; all pass in Debug, ReleaseSafe and ReleaseFast |

Using it

Add the dependency and import the module:

// build.zig
const zlexbor = b.dependency("z_lexbor", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("z_lexbor", zlexbor.module("z_lexbor"));

That single import brings in the whole stack: the translated C bindings and the compiled lexbor engine.

API

Two layers are always available. Anything lexbor can do is reachable through sys, even where a dedicated wrapper does not exist yet.

z_lexbor.sys

The raw, complete, 1:1 translated C API (z_lexbor.sys.c).

Wrapper modules

Module Contents
html Parser (RAII, owns its documents), Document, serialize, serializeDocument; OwnedDocument for building a DOM by hand
dom Node, Element, Attr, NodeType, Children, Descendants, Attributes; createElement, createTextNode, appendChild, appendElement, appendText
css Parser (RAII), SelectorList
selectors Engine with compile, find, queryAll, queryFirst
url Parser (RAII), Url.serialize, base-relative resolution
encoding byName, name (WHATWG encoding labels)
status Status enum, Error set, check, isError, name

Ownership rules

  • html.Parser owns every Document it produces: a document lives in the parser's memory pool and is invalidated by Parser.deinit.
  • dom.Node / dom.Element / dom.Attr are non-owning views with no deinit — including the ones returned by createElement.
  • html.OwnedDocument owns a document built by hand and frees every node in it on deinit.
  • css.Parser owns the SelectorLists it parses; selectors.Engine owns both its CSS parser and its selector engine.
  • url.Parser owns the Urls it parses.
  • Memory that lexbor allocated is only ever freed by the corresponding lxb_*_destroy. A Zig allocator is never used on lexbor-owned pointers; queryAll allocates only the result list.

Building a DOM without parsing

lexbor can assemble a tree from scratch, and html.OwnedDocument wraps that. Note that lxb_html_document_create() returns an empty document: the tree builder only runs during parsing, so nothing creates the html/head/body skeleton for you.

const std = @import("std");
const lexbor = @import("z_lexbor");

pub fn main(init: std.process.Init) !void {
    const io = init.io;

    var document = try lexbor.html.OwnedDocument.create();
    defer document.deinit();

    // document -> html -> { head -> link, body -> h1 -> "Hello world" }
    const html = try document.appendElement("html");

    const head = try html.appendElement("head");
    const link = try head.appendElement("link");
    try link.setAttribute("rel", "stylesheet");
    try link.setAttribute("href", "style.css");

    const body = try html.appendElement("body");
    const h1 = try body.appendElement("h1");
    _ = try h1.appendText("Hello world");

    var buffer: [512]u8 = undefined;
    var writer = std.Io.Writer.fixed(&buffer);
    try document.serializeTo(&writer);

    var out_buffer: [512]u8 = undefined;
    var out = std.Io.File.stdout().writer(io, &out_buffer);
    try out.interface.writeAll(std.Io.Writer.buffered(&writer));
    try out.interface.writeAll("\n");
    try out.interface.flush();
}

Output:

<html><head><link rel="stylesheet" href="style.css"></head><body><h1>Hello world</h1></body></html>

The full runnable version is examples/build_dom.zig (zig build then ./zig-out/bin/build_dom).

Notes:

  • appendElement and appendText create the node in the document that owns the parent, then append it. Use document.createElement / createTextNode for a detached node you intend to attach later.
  • Node.appendChild runs the DOM's insertion steps (validity checks and mutation callbacks) and returns error.InsertRejected on a DOM exception. appendChildUnchecked skips those steps and is faster.
  • Appending a node that already lives in another document is accepted by lexbor and moves the node, leaving the original document without a root.
  • An empty element name is rejected with error.InvalidName. This is not cosmetic: a zero-length name makes lexbor's tag hash underflow (lexbor_shs_entry_get_lower_static in core/shs.c), which aborts under safety checks. The wrapper refuses it before the call. See AUDIT.md.
  • The document node is available as documentNode() if you need to append at the top level yourself.

CSS

lexbor is a CSS engine, not only a CSS parser. Three layers are available:

Layer What it does
css Full CSS Syntax parsing and a CSSOM (rules, at-rules, declarations, properties, values, units)
selectors Selector parsing and matching against the DOM (querySelector)
style Applies matched rules to elements and stores a per-element computed style tree

Cascade resolution is real. examples/css_cascade.zig is a self-checking demonstration of specificity ordering, !important, inline-style precedence and source order:

$ ./zig-out/bin/css_cascade
lexbor CSS cascade (7 cases)

  ok    specificity: #id beats .class beats type         color: green
  ok    specificity wins over source order               color: green
  ok    !important beats higher specificity              color: red !important
  ok    author !important beats inline style             color: red !important
  ok    inline style beats author normal declarations    color: blue
  ok    equal specificity: later rule wins               color: blue
  ok    attribute selector (b) beats type selector (c)   color: blue

Style application is opt-in and needs lxb_style_init(). The high-level lxb_engine_t does it for you:

const c = lexbor.sys.c;

const engine = c.lxb_engine_create();
defer _ = c.lxb_engine_destroy(engine);
try lexbor.status.check(c.lxb_engine_init(engine));
try lexbor.status.check(c.lxb_engine_parse(engine, html.ptr, html.len, 0));

// Then, for any element:
var str = std.mem.zeroes(c.lexbor_str_t);
try lexbor.status.check(c.lxb_dom_element_style_serialize_str(element, &str, 0));
// or: c.lxb_dom_element_style_by_name(element, "color", 5)

Careful: lxb_dom_element_style_by_name() and friends dereference the document's css field without a null check. On a document built by html.Parser (which does not call lxb_style_init()) that field is null and the call aborts. See AUDIT.md.

Idiomatic API

var engine = try lexbor.style.Engine.create();   // owns the document + CSS state
defer engine.deinit();

const doc = try engine.parse("<style>p{color:red}</style><p class=x>hi</p>");
const p = ...;                                    // any dom.Element

const computed = try doc.styleOf(p);
const text = try computed.serializeAlloc(allocator);   // "color: red"
const color = computed.get("color");                   // ?Entry, with specificity
try std.testing.expect((color.?.specificity).classes() == 1);

try doc.applyStylesheet(".x { font-size: 12px }");     // inject CSS later
Type Role
style.Engine Owns the document and its CSS state; only path that guarantees document.css != null
style.StyledDocument Borrowed view; styleOf, applyStylesheet
style.Computed One element's computed style: get, property, count, serialize, walk, collect
style.Entry A declaration + the Specificity that selected it
style.Specificity !important, style-attribute flag, a/b/c counts, order()

style.of(element) !Computed is the checked escape hatch for an arbitrary element: it returns error.StyleNotInitialized rather than aborting.

Known lexbor limitations, pinned by tests: styles are resolved at insertion time (changing an attribute later does not recompute them), and var() is not substituted.

Layout

Path Purpose
src/sys/ Complete raw bindings, 1:1 with the C API
src/*.zig Idiomatic wrapper modules
tools/gen_c_header.zig Builds the umbrella header fed to addTranslateC
tools/check_coverage.zig Public-API coverage gate
tools/check-consumer.sh External-consumer integration check
vendor/lexbor/ Vendored lexbor v3.0.1 (see vendor/lexbor/VENDOR.md)
examples/ parse.zig (raw sys), query.zig (wrappers), build_dom.zig (DOM by hand), css_cascade.zig (CSS cascade)

Build steps

Step Action
zig build test Everything: inline unit tests + the full tests/ suite
zig build test-unit Only the inline unit tests in src/
zig build test-suite Only the tests/ suite
zig build check-coverage Fail if the bindings miss any public symbol
zig build docs Generate native Zig HTML API documentation in zig-out/docs/
zig build Build the examples
zig build -Dtarget=... Cross-compile for another target
zig build -Dsystem-lexbor Link a system lexbor instead (not hermetic)

Testing

248 tests, split in two halves that zig build test runs together.

Inline unit tests (src/)

Small, fast tests next to the code they cover, including an exhaustive table of every lxb_status_t enumerator.

The tests/ suite

File Focus
status_test.zig Every status enumerator; a full sweep of raw values proves the mapping never panics
convert_test.zig The C-string/slice boundary, including null and out-of-range lengths
callback_test.zig callconv(.c) bridges and how write failures cross back out
dom_test.zig Traversal, iterators, attributes, deep trees
html_test.zig Parsing, document structure, serialization stability
css_test.zig Selector-list parsing, including garbage and 2000-combinator input
selectors_test.zig Matching, document order, early exit, callback errors
url_test.zig WHATWG parsing, relative resolution, IDNA, path traversal strings
encoding_test.zig Label lookup, case-insensitivity, 100 KB labels
ownership_test.zig Idempotent teardown, Document has no deinit, leak checking
adversarial_test.zig 1 MiB documents, 5000-deep nesting, 64 KiB attributes, NUL bytes, exhausted buffers
fuzz_test.zig Deterministic (seeded) fuzzing of HTML, markup, selectors and URLs
build_dom_test.zig Assembling a DOM by hand, including the lexbor empty-name defect
style_test.zig CSS cascade via the raw sys API
style_deep_test.zig The style module: cascade, specificity, injection, guard
style_adversarial_test.zig Hostile CSS, OOM injection, seeded fuzzing
integration_test.zig End-to-end scenarios: scraping, tables, mutation round-trips

How failures are provoked

Several techniques are used deliberately, rather than only testing the happy path:

  • Allocation-failure injection — std.testing.checkAllAllocationFailures fails every allocation point in turn and requires that nothing leaks and that the error surfaces. Applied to queryAll and queryFirst.
  • Deterministic fuzzing — seeded std.Random.DefaultPrng, so any failure is reproducible; the invariant under fuzz is "typed error or well-formed result, never a trap".
  • Adversarial sizing — inputs far outside what any real page contains.
  • Error-path assertions — every fallible wrapper API is asserted with expectError for its specific error, not just "some error".

Mutation-checked

The suite was validated by injecting deliberate bugs and confirming it fails:

Injected bug Result
status.check swallows LXB_STATUS_ERROR_NOT_EXISTS 3 tests fail
conv.slice drops its null guard tests abort with panic: attempt to use null value
FixedSink stops reporting truncation 3 tests fail
the createElement empty-name guard is removed the process aborts inside lexbor (core/shs.c integer underflow)

This is also how a real coverage gap was found and closed: the inline status test originally missed NotExists, which the suite caught.

See AUDIT.md for the full write-up, including the behaviours this suite pinned down and the parts of the system it does not cover.

Notes

  • lexbor's generated res.h / *_res.h static tables are excluded from the bindings: they are translation-unit-private and not self-contained. They are still compiled as part of their own .c files.
  • translate-c emits @compileError placeholders for a number of glibc macros (never for lexbor symbols). They are inert while unreferenced, which is why sys must not be passed to refAllDeclsRecursive.

License

MIT for this project. lexbor is Apache-2.0; see vendor/lexbor/LICENSE.

About

Complete Zig 0.16 bindings and idiomatic wrapper for the lexbor HTML engine - vendored, hermetic, cross-platform

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages