html

    The fastest MoonBit HTML parser: ~240 µs for a 157 KB page on native, 20–440x faster than other MoonBit parsers. Lossless, with source offsets, CSS selectors, and an optional mutable tree

    html
    parser
    dom
    css
    selector
    Download zip
    Author
    Version
    0.1.3
    License
    MIT
    Last updated
    4 days ago
    Downloads
    28

    No dependencies

    #justjavac/html

    coverage

    Fast, lossless HTML parsing with UTF-16 source offsets, lazy entity decoding, CSS selectors, and an optional mutable tree. Supports native, js, wasm, and wasm-gc.

    #Performance

    The fastest MoonBit HTML parser on every backend: parsing a 157 KB Wikipedia page takes ~240 µs on native — 20× faster than the next-fastest MoonBit parser and 440×+ faster than the WHATWG-conforming one — with precompiled selector queries in ~13 µs. Numbers and methodology: benchmark/README.md.

    #Install

    moon add justjavac/html

    #Quick Start

    ///|
    test "parse and query HTML" {
    let doc = @html.parse(
    "<head><title>Hi &amp; bye</title><link rel=canonical href=\"/\"></head>",
    )
    inspect(doc.find("head > title").unwrap().text(), content="Hi & bye")
    assert_eq(
    doc.find("link[rel=canonical]").unwrap().get_attr("href"),
    Some("/"),
    )
    let title = doc.find("title").unwrap()
    assert_eq(doc.position(title.start()), { line: 1, column: 7, })
    inspect(title.stringify(), content="<title>Hi &amp; bye</title>")
    }

    #Mutable Trees

    Import justjavac/html/mutable for attribute, text, and child edits. Mutable nodes preserve untouched source and rebuild only edited branches.

    This package follows htmlparser2-style recovery, not the WHATWG tree-construction algorithm. Do not use it as an HTML sanitizer.

    Stringify

    pub trait Stringify {
    fn stringify(Self) -> String
    }

    Values that can be serialized back to HTML.

    For nodes of an immutable document the result is always the exact original source slice, so parse(source).stringify() == source.

    SelectorError

    pub suberror SelectorError {
    InvalidSelector(String)
    }

    A malformed or unsupported CSS selector.

    Raised by the selector-taking functions (find, all, matches, closest, and Selector::parse); the message describes the first syntax problem found.

    Comment

    pub struct Comment {
    // private fields
    }

    A handle to a normal or bogus comment node.

    value returns the comment content without the <!-- and --> markers.
    impl Eq for Comment

    Comment::document

    fn Comment::document(self : Comment) -> Document

    The document this comment belongs to.

    Comment::end

    fn Comment::end(self : Comment) -> Int

    The zero-based UTF-16 offset just past the comment's -->.

    Comment::parent

    fn Comment::parent(self : Comment) -> Parent

    The comment's parent: an enclosing element, or the document for top-level comments.

    Comment::start

    fn Comment::start(self : Comment) -> Int

    The zero-based UTF-16 offset at which the comment starts, pointing at <!.

    Comment::stringify

    fn Comment::stringify(self : Comment) -> String

    Comment::value

    fn Comment::value(self : Comment) -> String

    The comment content without the surrounding <!-- and -->.

    Directive

    pub struct Directive {
    // private fields
    }

    A handle to a doctype declaration.

    value returns the raw content of the declaration, e.g. doctype html for <!doctype html>.
    impl Eq for Directive

    Directive::document

    fn Directive::document(self : Directive) -> Document

    The document this directive belongs to.

    Directive::end

    fn Directive::end(self : Directive) -> Int

    The zero-based UTF-16 offset just past the directive's closing >.

    Directive::parent

    fn Directive::parent(self : Directive) -> Parent

    The directive's parent: always the document, since directives only appear at the top level.

    Directive::start

    fn Directive::start(self : Directive) -> Int

    The zero-based UTF-16 offset at which the directive starts, pointing at <!.

    Directive::stringify

    fn Directive::stringify(self : Directive) -> String

    Directive::value

    fn Directive::value(self : Directive) -> String

    The directive's raw content, e.g. doctype html for <!doctype html>.

    Document

    pub struct Document {
    // private fields
    }

    An HTML document produced by parse.

    The document owns the compact parse tree; every handle obtained from it (Element, Text, Comment, Directive) is a cheap view that stores no content of its own. Attribute maps, decoded text, and the line table are computed lazily on first read.

    let doc = @html.parse("<p>Hello &amp; goodbye</p>")
    doc.find("p").unwrap().text() // "Hello & goodbye"
    impl Eq for Document

    Document::all

    fn Document::all(self : Document, selector : String) -> Array[Element] raise SelectorError

    All elements matching selector in source order.

    Raises SelectorError for a malformed or unsupported selector.

    Document::all_with

    fn Document::all_with(self : Document, selector : Selector) -> Array[Element]

    All elements matching a selector compiled by Selector::parse.

    Document::children

    fn Document::children(self : Document) -> Array[Node]

    The document's top-level nodes in source order.

    Document::end

    fn Document::end(self : Document) -> Int

    The end of the document's range: the source length in UTF-16 code units.

    Document::find

    fn Document::find(self : Document, selector : String) -> Element? raise SelectorError

    The first element matching selector in source order, or None.

    Raises SelectorError for a malformed or unsupported selector.

    doc.find("main > p.intro")

    Document::find_with

    fn Document::find_with(self : Document, selector : Selector) -> Element?

    The first element matching a selector compiled by Selector::parse, or None.

    Document::position

    fn Document::position(self : Document, offset : Int) -> Position

    Convert a zero-based UTF-16 source offset to a one-based Position.

    The line table is built on the first call and cached on the document.

    Document::source

    fn Document::source(self : Document) -> String

    The exact source string the document was parsed from.

    Document::start

    fn Document::start(_self : Document) -> Int

    The start of the document's range: always 0.

    Document::stringify

    fn Document::stringify(self : Document) -> String

    Document::text

    fn Document::text(self : Document) -> String

    The decoded text of all text nodes in document order.

    Entities are decoded on the fly; tags, comments, and directives contribute nothing.

    Element

    pub struct Element {
    // private fields
    }

    A handle to an element node in a Document.

    Handles are cheap views into the document's compact tree: copying one costs nothing, and two handles compare equal (Eq) exactly when they point at the same node of the same document. Offsets returned by start and end are zero-based UTF-16 code-unit offsets into the original source.
    impl Eq for Element

    Element::all

    fn Element::all(self : Element, selector : String) -> Array[Element] raise SelectorError

    All matching descendant elements in source order.

    Raises SelectorError for a malformed or unsupported selector.

    Element::all_with

    fn Element::all_with(self : Element, selector : Selector) -> Array[Element]

    All matching descendants using a selector compiled by Selector::parse.

    Element::attributes

    fn Element::attributes(self : Element) -> Map[String, String]

    An independent map of the element's attributes.

    Keys are lowercase and values are entity-decoded. The returned map is a copy: mutating it does not affect the document.

    Element::children

    fn Element::children(self : Element) -> Array[Node]

    The element's child nodes in source order.

    Element::closest

    fn Element::closest(self : Element, selector : String) -> Element? raise SelectorError

    The element itself if it matches selector, otherwise the nearest matching ancestor; None if neither matches.

    Raises SelectorError for a malformed or unsupported selector.

    Element::closest_with

    fn Element::closest_with(self : Element, selector : Selector) -> Element?

    The element itself if it matches a selector compiled by Selector::parse, otherwise the nearest matching ancestor; None if neither matches.

    Element::document

    fn Element::document(self : Element) -> Document

    The document this element belongs to.

    Element::end

    fn Element::end(self : Element) -> Int

    The zero-based UTF-16 offset just past the element.

    For void elements this is the end of the open tag; for all others it is just past the close tag, so source[start..end] spans the whole element.

    Element::find

    fn Element::find(self : Element, selector : String) -> Element? raise SelectorError

    The first matching descendant element in source order, or None.

    Raises SelectorError for a malformed or unsupported selector.

    Element::find_with

    fn Element::find_with(self : Element, selector : Selector) -> Element?

    The first matching descendant using a selector compiled by Selector::parse, or None.

    Element::get_attr

    fn Element::get_attr(self : Element, name : String) -> String?

    The decoded value of an attribute, matched without regard to ASCII case, or None if the attribute is absent.

    A present-but-empty attribute such as disabled returns Some("").

    Element::has_attr

    fn Element::has_attr(self : Element, name : String) -> Bool

    Whether the element has the attribute, matched without regard to ASCII case.

    Element::html

    fn Element::html(self : Element) -> String

    The element's inner HTML exactly as written in the source, without decoding or reformatting.

    Element::matches

    fn Element::matches(self : Element, selector : String) -> Bool raise SelectorError

    Whether the element itself matches selector.

    Raises SelectorError for a malformed or unsupported selector.

    Element::matches_with

    fn Element::matches_with(self : Element, selector : Selector) -> Bool

    Whether the element itself matches a selector compiled by Selector::parse.

    Element::name

    fn Element::name(self : Element) -> String

    The tag name.

    HTML element names are lowercase; foreign-content (SVG/MathML) names keep their canonical camelCase form, e.g. foreignObject.

    Element::parent

    fn Element::parent(self : Element) -> Parent

    The element's parent: an enclosing element, or the document for top-level elements.

    Element::start

    fn Element::start(self : Element) -> Int

    The zero-based UTF-16 offset at which the element's open tag starts.

    Element::stringify

    fn Element::stringify(self : Element) -> String

    Element::text

    fn Element::text(self : Element) -> String

    The decoded text of all descendant text nodes, concatenated in source order.

    Node

    pub(all) enum Node {
    Element(Element)
    Text(Text)
    Comment(Comment)
    Directive(Directive)
    } derive(Eq,
    Debug
    )

    A child node in an HTML document: an element, text, comment, or directive.

    Returned by children. All node kinds share the document, start, end, parent, and stringify methods.
    impl Stringify for Node

    Node::document

    fn Node::document(self : Node) -> Document

    The document this node belongs to.

    Node::end

    fn Node::end(self : Node) -> Int

    The zero-based UTF-16 offset just past this node.

    Node::parent

    fn Node::parent(self : Node) -> Parent

    The node's parent: an enclosing element, or the document for top-level nodes.

    Node::start

    fn Node::start(self : Node) -> Int

    The zero-based UTF-16 offset at which this node starts.

    Node::stringify

    fn Node::stringify(self : Node) -> String

    Parent

    pub(all) enum Parent {
    Document(Document)
    Element(Element)
    } derive(Eq,
    Debug
    )

    The parent of a node: either the document or an enclosing element.

    Position

    pub(all) struct Position {
    line : Int
    column : Int
    } derive(Eq,
    Debug
    )

    A one-based line and column in the original UTF-16 source.

    Both line and column start at 1. Columns count UTF-16 code units, not Unicode scalar values or grapheme clusters.

    Selector

    pub struct Selector {
    // private fields
    }

    A CSS selector list compiled by Selector::parse.

    Compiling once and reusing the value with find_with, all_with, matches_with, and closest_with skips re-parsing the selector text on every query and enables precomputed candidate-tag lookups.

    Selector::parse

    fn Selector::parse(input : String) -> Selector raise SelectorError

    Compile a CSS selector list once for repeated matching.

    Raises SelectorError for a malformed or unsupported selector. Use the result with find_with, all_with, matches_with, or closest_with.

    let content = @html.Selector::parse("div.content").unwrap()
    doc.find_with(content) // like doc.find("div.content"), without re-parsing

    Text

    pub struct Text {
    // private fields
    }

    A handle to a text node, including foreign-content CDATA sections.

    value returns the entity-decoded content, while stringify returns the exact original source slice.
    impl Stringify for Text
    impl Eq for Text

    Text::document

    fn Text::document(self : Text) -> Document

    The document this text node belongs to.

    Text::end

    fn Text::end(self : Text) -> Int

    The zero-based UTF-16 offset just past the text.

    Text::parent

    fn Text::parent(self : Text) -> Parent

    The text node's parent: an enclosing element, or the document for top-level text.

    Text::start

    fn Text::start(self : Text) -> Int

    The zero-based UTF-16 offset at which the text starts.

    Text::stringify

    fn Text::stringify(self : Text) -> String

    Text::value

    fn Text::value(self : Text) -> String

    The text content with entities decoded, e.g. &amp; becomes &.

    parse

    fn parse(source : String) -> Document

    Parse HTML into an immutable document.

    Never raises: malformed markup is recovered htmlparser2-style (implied end tags, foreign content, and bogus comments are handled leniently), which is not the WHATWG browser tree-construction algorithm. Do not use the result as a security boundary, e.g. as an HTML sanitizer.

    let doc = @html.parse("<ul><li>one<li>two</ul>")
    doc.all("li").length() // 2

    stringify

    fn[T : Stringify] stringify(target : T) -> String

    Serialize any Stringify value to its HTML string.

    Equivalent to calling the value's own stringify method; useful when the concrete node type is abstracted away.

    @html.stringify(@html.parse("<p>a</p>")) // "<p>a</p>"