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);| 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 |
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.
Two layers are always available. Anything lexbor can do is reachable through
sys, even where a dedicated wrapper does not exist yet.
The raw, complete, 1:1 translated C API (z_lexbor.sys.c).
| 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 |
html.Parserowns everyDocumentit produces: a document lives in the parser's memory pool and is invalidated byParser.deinit.dom.Node/dom.Element/dom.Attrare non-owning views with nodeinit— including the ones returned bycreateElement.html.OwnedDocumentowns a document built by hand and frees every node in it ondeinit.css.Parserowns theSelectorLists it parses;selectors.Engineowns both its CSS parser and its selector engine.url.Parserowns theUrls 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;queryAllallocates only the result list.
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:
appendElementandappendTextcreate the node in the document that owns the parent, then append it. Usedocument.createElement/createTextNodefor a detached node you intend to attach later.Node.appendChildruns the DOM's insertion steps (validity checks and mutation callbacks) and returnserror.InsertRejectedon a DOM exception.appendChildUncheckedskips 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_staticincore/shs.c), which aborts under safety checks. The wrapper refuses it before the call. SeeAUDIT.md. - The document node is available as
documentNode()if you need to append at the top level yourself.
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'scssfield without a null check. On a document built byhtml.Parser(which does not calllxb_style_init()) that field is null and the call aborts. SeeAUDIT.md.
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.
| 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) |
| 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) |
248 tests, split in two halves that zig build test runs together.
Small, fast tests next to the code they cover, including an exhaustive table of
every lxb_status_t enumerator.
| 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 |
Several techniques are used deliberately, rather than only testing the happy path:
- Allocation-failure injection —
std.testing.checkAllAllocationFailuresfails every allocation point in turn and requires that nothing leaks and that the error surfaces. Applied toqueryAllandqueryFirst. - 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
expectErrorfor its specific error, not just "some error".
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.
- lexbor's generated
res.h/*_res.hstatic tables are excluded from the bindings: they are translation-unit-private and not self-contained. They are still compiled as part of their own.cfiles. - translate-c emits
@compileErrorplaceholders for a number of glibc macros (never for lexbor symbols). They are inert while unreferenced, which is whysysmust not be passed torefAllDeclsRecursive.
MIT for this project. lexbor is Apache-2.0; see vendor/lexbor/LICENSE.