NativeElixirPdfUtilities.HtmlToPdf.HtmlParser (native_elixir_pdf_utilities v1.1.0)

View Source

Strict HTML parser for the native HTML-to-PDF renderer.

Supports a strict subset of document-oriented HTML: structural html/head/body/style tags, paragraphs, headings, inline emphasis/color containers, div containers for flex/grid layouts, lists, links, tables, images, static form controls, and CSS-targeting attributes, including data-* and aria-* metadata used by attribute selectors and generated content. Unsupported or malformed markup returns an error by default. html_recovery: true enables the documented end-tag and trailing-slash repairs.

Parsed elements retain accepted names in :attribute_order, normalized for their namespace. Validators use this additive source fact for initial hints whose result depends on original token order.

Summary

Functions

Parses an HTML binary into a renderer DOM tree.

Parses an HTML binary and returns source-location details when parsing fails.

Parses a complete rendering document, constructing omitted document and table groups.

Parses a fragment in a supported HTML, SVG, or MathML context without adding a wrapper.

Parses a fragment with the same source diagnostics and resource limits as parse_detailed/1.

Parses a canonical fragment with live insertion parents in the supplied context.

Types

dom_tree()

@type dom_tree() :: %{
  type: :document,
  node_id: reference(),
  document_id: reference(),
  tree_scope_id: reference(),
  parent_id: nil,
  source: %{text: String.t(), line: pos_integer(), column: pos_integer()},
  children: [text_node() | element_node() | processing_instruction_node()]
}

element_node()

@type element_node() :: %{
  :type => :element,
  :tag => String.t(),
  :attributes => map(),
  :children => [text_node() | element_node() | processing_instruction_node()],
  :node_id => reference(),
  :document_id => reference(),
  :tree_scope_id => reference(),
  :parent_id => reference() | nil,
  :source => %{text: String.t(), line: pos_integer(), column: pos_integer()},
  optional(:namespace) => :html | :svg | :mathml,
  optional(:attribute_namespaces) => map(),
  optional(:attribute_order) => [String.t()],
  optional(:content) => %{
    type: :document_fragment,
    node_id: reference(),
    document_id: reference(),
    tree_scope_id: reference(),
    parent_id: nil,
    source: %{text: String.t(), line: pos_integer(), column: pos_integer()},
    children: [text_node() | element_node() | processing_instruction_node()]
  }
}

fragment_tree()

@type fragment_tree() :: %{
  type: :document_fragment,
  node_id: reference(),
  document_id: reference(),
  tree_scope_id: reference(),
  parent_id: nil,
  source: %{text: String.t(), line: pos_integer(), column: pos_integer()},
  children: [text_node() | element_node() | processing_instruction_node()]
}

parse_option()

@type parse_option() :: {:html_recovery, boolean()}

processing_instruction_node()

@type processing_instruction_node() :: %{
  type: :processing_instruction,
  target: String.t(),
  data: String.t(),
  node_id: reference(),
  document_id: reference(),
  tree_scope_id: reference(),
  parent_id: reference() | nil,
  source: %{text: String.t(), line: pos_integer(), column: pos_integer()}
}

text_node()

@type text_node() :: %{
  type: :text,
  text: String.t(),
  node_id: reference(),
  document_id: reference(),
  tree_scope_id: reference(),
  parent_id: reference() | nil,
  source: %{text: String.t(), line: pos_integer(), column: pos_integer()}
}

Functions

parse(html, opts \\ [])

@spec parse(term(), [parse_option()]) ::
  {:ok, dom_tree()}
  | {:error,
     :invalid_encoding
     | :invalid_html
     | :invalid_options
     | :unsupported_html
     | :resource_limit_exceeded}

Parses an HTML binary into a renderer DOM tree.

Set html_recovery: true to accept optional end tags, close unclosed HTML elements at end of input, and ignore nonvoid HTML trailing slashes. Recovery defaults to false and leaves SVG/MathML and static input restrictions intact.

Processing instructions retain case-sensitive targets and literal data. They occupy authored tree positions without painting or acting as element siblings. Every node has a unique logical node_id, an authored document_id, a tree_scope_id and parent_id. Document and fragment roots have no parent; template fragments establish separate tree scopes in the same authored document. These identities carry no resource permissions. source contains exactly text, line and column, preserving original bytes before newline preprocessing, with positive line numbers and Unicode grapheme columns. Document source text is the complete input. Elements retain their opening token, processing instructions their complete token, and text nodes their tokenizer span before reference decoding or initial newline suppression. Template fragments retain the owning template's opening token. Implied elements have empty source text at line 1, column 1. Text tokens retain their boundaries across comments; CDATA spans include the original delimiters.

parse_detailed(html, opts \\ [])

@spec parse_detailed(term(), [parse_option()]) ::
  {:ok, dom_tree()}
  | {:error,
     {:invalid_encoding
      | :invalid_html
      | :invalid_options
      | :unsupported_html
      | :resource_limit_exceeded, map()}}

Parses an HTML binary and returns source-location details when parsing fails.

parse_document_detailed(html, opts \\ [])

@spec parse_document_detailed(term(), [parse_option()]) ::
  {:ok, dom_tree()}
  | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Parses a complete rendering document, constructing omitted document and table groups.

Returns an html element containing head and body, and constructs tbody and colgroup elements before their authored children are parsed, so live insertion locations include these implied parents. parse_detailed/1 retains its existing wrapper-free tree representation.

parse_fragment(html, context, opts \\ [])

@spec parse_fragment(term(), term(), [parse_option()]) ::
  {:ok, dom_tree()}
  | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Parses a fragment in a supported HTML, SVG, or MathML context without adding a wrapper.

For example, the "tr" context accepts table cells, and "select" accepts options. Context names are case-insensitive. Raw-text, RCDATA and plaintext contexts consume the entire input as text. "svg" and "math" select foreign roots; maps such as %{namespace: :mathml, tag: "annotation-xml", attributes: %{"encoding" => "text/html"}} describe foreign integration contexts. Foreign elements retain :namespace and qualified :attribute_namespaces. Unsupported contexts return an error.

parse_fragment_detailed(html, context, opts \\ [])

@spec parse_fragment_detailed(term(), term(), [parse_option()]) ::
  {:ok, dom_tree()}
  | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Parses a fragment with the same source diagnostics and resource limits as parse_detailed/1.

parse_fragment_tree_detailed(html, context, opts \\ [])

@spec parse_fragment_tree_detailed(term(), term(), [parse_option()]) ::
  {:ok, fragment_tree()}
  | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Parses a canonical fragment with live insertion parents in the supplied context.

The root is a document_fragment with its own tree scope. Omitted tbody and colgroup parents exist before their authored children are parsed, both in a table context and in nested tables. HTML, SVG and MathML contexts use the same strict validation and tokenizer rules as parse_fragment_detailed/2. Original source bytes and authored logical identities are retained. This operation grants no resource permissions and does not enable template patches. The existing fragment API retains its wrapper-free document projection.