# zigquery
[](https://github.com/OrlovEvgeny/zigquery/actions/workflows/ci.yml)
[](https://github.com/OrlovEvgeny/zigquery/releases/latest)
[](https://ziglang.org/)
jQuery-like HTML DOM manipulation library for Zig. Parse HTML, query elements with CSS selectors, traverse the tree, and manipulate the document.
## Quick start
```zig
const std = @import("std");
const zq = @import("zigquery");
pub fn main() !void {
const allocator = std.heap.page_allocator;
var doc = try zq.Document.initFromSlice(allocator,
\\
\\
\\
\\
Hello
\\
First paragraph
\\
Second paragraph
\\
About
\\
appended
");
try div.prependHtml("prepended
");
// Insert around selection.
const p = try doc.find("p");
try p.afterHtml("
");
try p.beforeHtml("");
// Replace and remove.
_ = try p.replaceWithHtml("replaced
");
_ = p.remove();
_ = try div.empty(); // remove all children
// Set content.
try div.setHtml("new content");
try div.setText("plain text");
// Wrap / unwrap.
try div.wrapHtml("");
try div.unwrap();
```
### Selection — Iteration
```zig
const rows = try doc.find("tr");
// Iterator (idiomatic Zig).
var it = rows.iterator();
while (it.next()) |row| {
const cells = try row.find("td");
// ...
}
// Callback-based.
rows.each(struct {
fn f(i: usize, sel: zq.Selection) void {
_ = i;
_ = sel;
}
}.f);
```
### Selection — Set operations
```zig
const a = try doc.find(".foo");
const b = try doc.find(".bar");
const combined = try a.add(".bar");
const merged = try a.addSelection(b);
const union_sel = try a.@"union"(b);
const common = try a.intersection(b);
```
### Compiled selectors
Compile a selector once when it is reused across queries or documents:
```zig
var active_links = try zq.CompiledSelector.init(allocator, "a.active");
defer active_links.deinit();
const links = try doc.findCompiled(&active_links);
const matches = links.isCompiled(&active_links);
```
## Ownership and errors
`Document.initFromSlice`, `Document.initFromNode`, `Document.clone`, parsed fragments,
attributes, and inserted nodes own their data through the document arena. Input buffers
and source documents may be released after these operations complete. Use
`Document.initBorrowedNode` only when the source tree is guaranteed to outlive the
document.
Operations that allocate return an error union. In v0.2 this includes traversal methods
such as `children`, positional methods such as `first`, attribute/class updates, and DOM
mutations. Mutations parse or clone all required data before changing the tree, so an
allocation failure does not leave a partially updated selection.
## v0.2 migration
Add `try` to allocating `Selection` calls. Node insertion now deep-clones supplied nodes
for every destination and never detaches the caller's source nodes. Invalid selector
syntax is returned as an error by `Selection.is` instead of being treated as no match.
## Parser scope
The parser is intentionally lenient and covers common HTML document and fragment use,
including implicit `html/head/body`, raw text/RCDATA, optional closing for common list
and table elements, comments, and core character references. It is not yet a complete
WHATWG tree builder; foreign content, templates, the adoption agency algorithm, and the
full named entity table remain roadmap items. See [ROADMAP.md](ROADMAP.md).
## Running tests
```sh
zig build test
```
Inspired by Go's [goquery](https://github.com/PuerkitoBio/goquery) and, by extension, jQuery
## License
[MIT](LICENSE)