Module parserino

HTML5 parser and DOM manipulation library.

Parserino is a fast html5 parser and DOM manipulation library written in pure D (the tree construction is derived from the lexbor library).

import parserino;
void main()
{
   auto doc = Document("<html><body><p>Hello World!</p></body></html>");
   assert(doc.body.firstChild.textContent == "Hello World!");
   assert(doc.byTagName("p").front.textContent == "Hello World!");
}

LLM-friendly documentation: llms.txt, the whole API in llms-full.txt, a skill for agents in SKILL.md.

The main types are Document, Node and Element: - a Node is any node of the tree: an element, a text, a comment, a doctype, ...; - an Element is a node that is an element: it adds attributes, innerHTML, matches, ... It converts implicitly to Node; node.asElement goes the other way.

Navigation

one method for each direction, with the kinds of nodes to see as a template parameter (Show, as whatToShow in the DOM). The default is Show.Element, and then the result is an Element (or a range of Element); with other filters it's a Node.

p.children                           // the child elements
p.children!(Show.All)                // all the child nodes
doc.descendants!(Show.Comment)       // all the comments of the document
p.firstChild!(Show.Text)             // the first child text node
doc.body.descendants.retro           // reverse document order

Errors

searches and navigation give an invalid node (== null, isValid is false) or an empty range when nothing is found; a node that can't have children (a text, a comment) just has no children. Calling a method on an invalid node or document, or a mutation that is not possible (a child of a text, a node inside itself, a node of another document, a sibling of a node without parent), throws a ParserinoException.

Views

the getters that copy a string stored in the document have a ...View variant that returns a slice of the document memory instead (localNameView, idView, getAttributeView, classesView, attributesView, dataView). The slice is valid until that value changes or the document is destroyed. Computed values (textContent of an element, innerHTML, title) have no view.

Memory

a Document is reference counted. Every Node keeps its document alive, so nodes are always safe to use, even after the Document variable goes out of scope. Nodes removed from the tree stay valid (they are released with their document).

Lazy parsing: Document(html, Parsing.Lazy) builds the tree only as far as your queries need. doc.byClass("x").take(3) stops parsing a little after the third match.

Input

the html must be UTF-8 (invalid bytes become U+FFFD, a BOM is removed). For other encodings see toUtf8.

Functions

Name	Description
`asFragment(s)`	Create a fragment from a string. The fragment is not attached to any document by default. The fragment is not a valid element or document, it's just a piece of html you can add to a document.
`ctDocument()`	A document parsed at compile time. The compiler parses `html` once and stores the tree in the executable. At runtime each call returns a new document (mutable, independent from the others) copied from that tree, without tokenizing or building it again.
`ctSelector()`	A selector parsed at compile time: syntax errors are compile errors.
`frontOr(range, fallback)`	Get the first element of a range or return the second args
`frontOrInit(range)`	Get the first element of a range, or its `init` (an invalid node for the ranges of nodes)
`frontOrThrow(range)`	Get the first element of a range or throw an exception
`isValidSelector(css)`	Is this a valid css selector? It works at compile time too.

Classes

Name	Description
`ParserinoException`	Thrown on invalid operations (invalid node, impossible mutation, bad selector, ...)

Structs

Name	Description
`AttributeRange`	A range of attributes. It keeps the document alive.
`ClassRange`	A range of the classes of an element (`classes`, `classesView`). It keeps the document alive.
`Document`	The HTML5 Document
`Element`	A node that is an element. It converts implicitly to `Node`.
`Node`	A node of a document: an element, a text, a comment, a doctype, the document itself, ... See the module documentation for the navigation (`Show`) and the rules on errors.
`NodeRange`	A lazy range of nodes in tree order (or in reverse tree order). It is returned by `descendants`, `children`, `byTagName`, `byClass`, `bySelector`, ... It is a forward range: `save` gives an independent copy. A lazy range of nodes in tree order: `descendants`, `children`, `byTagName`, `byClass`, `bySelector`, ... return it. It's a bidirectional range: `save` gives an independent copy, `back`/`popBack` (and so `retro`) go in reverse document order. The elements are `Element`s if `show` is `Show.Element`, else `Node`s.
`ParseError`	A parse error: the html is not valid (the parser recovers anyway, as a browser does). The codes of the tokenizer are the ones of the HTML standard; the standard doesn't name the errors of the tree construction, so they have codes in the same style (`misnested-tag`, ...).
`ParseOptions`	Options of the parser (see `Document.this`)
`Selector`	A compiled css selector. It can be used with any document, many times.
`Snapshot`	A compact copy of a document tree, made by `Document.snapshot`: `Document(snapshot)` makes new documents from it without parsing. It can be shared between threads.

Enums

Name	Description
`Parsing`	How `Document` parses its input
`Show`	The kinds of nodes that a navigation or a range gives: the same bits of `NodeFilter.whatToShow` in the DOM. Combine them with `\|`: `children!(Show.Text \| Show.Comment)`.

Manifest constants

Name	Type	Description
`DefaultChunkSize`		Default chunk size for `Parsing.Lazy`

Aliases

Name	Type	Description
`NodeOf`	`Element`	The result of a navigation with the filter `show`: `Element` for `Show.Element`, else `Node`