PureHTML.TreeBuilder (PureHTML v0.5.0)

Builds an HTML document tree from a tokenizer, following the WHATWG tree construction stage.

Architecture

Parsing context: the stack of open elements (refs), the list of active formatting elements, the insertion mode, the stack of template insertion modes, and the element pointers, all in the State struct.
DOM structure: elements stored in a map keyed by make_ref(), each with its tag, attributes, children, and parent ref. The stack top is the insertion parent; foster parenting is resolved at insertion time.
Dispatch: each token goes to the foreign content rules (PureHTML.TreeBuilder.ForeignContent) or to the module for the current insertion mode. The modes switch the tokenizer state for raw text, RCDATA, script data, and plaintext.
After parsing: PureHTML.TreeBuilder.SelectedContent replays the customizable select's selectedcontent mirroring over the finished tree.

Final output: {tag, attrs, children} tuples (attrs are lists of {name, value} tuples)

document_node()

Builds a document from a tokenizer.

Builds a fragment from a tokenizer using the given context element.

Builds a fragment from a tokenizer, returning both children and parse error count.

Builds a document from a tokenizer, returning both nodes and parse error count.

@type document_node() :: PureHTML.html_node()

@spec build(PureHTML.Tokenizer.t(), boolean()) :: [document_node()]

Builds a document from a tokenizer.

Returns a list of top-level nodes. If a doctype is present, it appears first as {:doctype, name, public_id, system_id}.

@spec build_fragment(PureHTML.Tokenizer.t(), atom() | nil, String.t(), boolean()) :: [
  document_node()
]

Builds a fragment from a tokenizer using the given context element.

Implements the WHATWG "parsing HTML fragments" algorithm. The context element determines the initial insertion mode and parser behavior.

Returns a list of child nodes (no <html>/<head>/<body> wrappers).

@spec build_fragment_with_errors(
  PureHTML.Tokenizer.t(),
  atom() | nil,
  String.t(),
  boolean()
) ::
  {[document_node()], non_neg_integer()}

Builds a fragment from a tokenizer, returning both children and parse error count.

Same as build_fragment/4 but returns {children, error_count}.

@spec build_with_errors(PureHTML.Tokenizer.t(), boolean()) ::
  {[document_node()], non_neg_integer()}

Builds a document from a tokenizer, returning both nodes and parse error count.

Same as build/2 but returns {nodes, error_count}.