🥮 mooncakes.io

    moonxml

    HTML, XML and SVG for MoonBit: parse, query and edit.

    html
    html5
    xml
    svg
    xpath
    css-selectors
    selector
    dom
    parser
    namespace
    streaming
    event
    sax
    htmx
    query
    edit
    moonbit
    Download zip
    Version
    0.1.6
    License
    Apache-2.0
    Repository
    Last updated
    10 hours ago
    Downloads
    224

    No dependencies

    #<moonxml/>

    HTML, XML and SVG for MoonBit — one mutable tree: parse it, query it by CSS selector or XPath 1.0, edit it in place, write it back.

    CI docs license

    Documentation · Quick start · Selectors · API · How it works

    let page = @html.loads("<ul id=list><li>coffee<li>tea</ul>")

    // the document closed neither item; the reader closed both
    assert_eq(page.css("li").length(), 2)
    assert_eq(page.xpath("//li[2]").text(), "tea")
    assert_eq(
      page.dumps(),
      "<html><head></head><body><ul id=\"list\"><li>coffee</li><li>tea</li></ul></body></html>",
    )

    HTML is read the way a browser reads it; XML is read strictly, as XML 1.0 requires; both become the same node kinds, so a query written for a page works on a feed.

    #Why this shape

    One tree, two syntaxesNode is element, text, CDATA, comment, processing instruction, doctype, attribute or namespace. Nothing about a node says which parser made it.
    One chainEvery query answers a Selection, so css → xpath → selector → custom → items[i] → children()[j] → css again never changes type.
    Two engines, and yoursCSS Selectors 4's statically decidable subset — namespace prefixes resolved through a map you pass — all of XPath 1.0, and a Selector trait you implement and register by name.
    Editing, not re-parsingA full set of editing verbs on the same selection the query returned, with parent pointers kept true.
    Two ways to readBuild the tree, or stream Events into your own Sink and build nothing — @xml.scan for XML, @html.scan for HTML's tokens. The tree builder is itself a sink: one parser, no drift.
    One error familyRefused: malformed input names its offset, a bad selector names its fault. HTML never refuses — it repairs, and tells you what it repaired.

    #Install

    moon add moonbitstack/moonxml

    import {
      "moonbitstack/moonxml",       // tree, chain, engines, writer
      "moonbitstack/moonxml/html",  // @html.loads
      "moonbitstack/moonxml/xml",   // @xml.loads
      "moonbitstack/moonxml/event", // Event, Sink
      "moonbitstack/moonxml/htmx",  // @htmx.Hx — htmx's attributes, read and carried out
    }

    Two dependencies: moonbitlang/core, and nothing else.

    #The chain

    let page = @html.loads(
      "<table><tr><td>one</td></tr><tr><td><span>two</span></td></tr></table>")

    // your own selector is one more link in the chain: register a name for it
    page.register("mine", @moonxml.SelectorFn::new(fn(ctx, _query) {
      ctx.by_tag("td")
    }))

    page
      .xpath("//table")          // any engine
      .css("tr:nth-child(2)")    // any other
      .selector("mine", "")      // one you registered
      .items[0]                  // a Node, not a selection
      .css("span")               // and query again
      .set_text("done")

    assert_eq(page.xpath("//td/span").text(), "done")

    // one you never registered goes straight to custom
    assert_eq(
      page.css("tr").custom(@moonxml.SelectorFn::new(fn(ctx, _query) {
        ctx.filter(fn(node) { node.text() == "one" })
      })).text(),
      "one",
    )

    Results arrive in document order, deduplicated by identity — two <li>coffee</li> are different nodes and both are kept — and an empty selection stays empty rather than widening to the document.

    Where XPath answers something that is not a node-set, xpath_value answers it typed: Nodes, Str, Num or Flag. An attribute is a node of its own, so //a/@href keeps an identity and attribute::x/self::node() has something to answer; the namespace axis answers what is in scope on an element.

    CSS prefixes come from the caller, the way a stylesheet's @namespace rules declare them:

    let page = @html.loads("<svg viewBox='0 0 1 1'><rect/><rect/></svg><rect/>")
    let ns : @moonxml.NamespaceMap = {
      default: "",
      prefixes: [("svg", "http://www.w3.org/2000/svg")],
    }

    assert_eq(page.css("svg|rect", namespaces=ns).length(), 2)   // one prefix
    assert_eq(page.css("*|rect", namespaces=ns).length(), 3)     // any namespace
    assert_eq(page.css("|rect", namespaces=ns).length(), 1)      // no namespace

    Every selector the engine implements, run against one document — the query, the nodes it answered, and the text or attribute taken out of them — is the selector board. It is generated by running src/examples/selectors, so it cannot claim a selector works that the engine does not have.

    #Filtering text

    A query answers nodes, and what a node says is a string. No selector can narrow on that string — there is no :contains in the specification — so filter is where the two meet: it hands the whole node to a predicate, and the predicate reads whatever it needs.

    let page = @html.loads("<ul id=list><li>coffee 4.5<li>tea<li>beans 12</ul>")

    // the items whose text carries an amount
    let priced = page.css("li").filter(fn(li) {
      li.text().contains_any(chars="0123456789")
    })

    assert_eq(priced.length(), 2)
    assert_eq(priced.last().text(), "beans 12")

    The predicate sees a node rather than a string, so it can read an attribute as easily as the text, and what comes back is still a Selection: the chain goes on from there.

    #The interface

    Four types, and every method sits on the type it acts on: Selection is a node list, Element is one node, Node is any node, Document is the container the tree hangs from. Query methods exist on all four, so a chain never has to stop and re-wrap.

    #Document

    readroot document_element() flavour() repairs()
    searchcss(q) xpath(q) xpath_value(q) selector(name, q) custom(sel) by_id(v) by_class(v) by_tag(v) by_name(v)
    contenttext() html() children() descendants() dumps() dump() dumps_html() dump_html() events()
    changeappend(node) prepend(node) clear() smooth() register(name, sel) push(event)

    A document's root is a container, not a node of the document, so the verbs that act on one node among siblings are deliberately not forwarded to Document: remove, replace_with, wrap, unwrap, parent, first, last, eq, length, attr, set_attr, remove_attr, add_class, remove_class, filter, closest, set_text. Each would answer for the container itself — remove the document from the document, ask what a document is named — which is not an operation a caller can mean. They stay on Selection and Element, where they name something real.

    #Selection

    searchcss xpath xpath_value selector custom by_id by_class by_tag by_name filter(f) closest(q)
    narrowfirst() last() eq(i) children() parent() descendants() items[i]
    readlength() text() html() attr(name)
    changeappend prepend remove replace_with unwrap wrap clear set_text set_attr remove_attr add_class remove_class smooth

    #Element

    fieldsname attrs children parent closed
    structureappend prepend insert(at, node) insert_before insert_after replace_with remove unwrap wrap clear set_children(nodes) smooth
    positionchild_elements() index_in_parent() previous_element_sibling() next_element_sibling()
    attributesattr has_attr set_attr remove_attr classes has_class add_class remove_class
    contenttext() set_text(s) html() walk(f) document()
    languagelang() is_lang(tag)

    #Node

    name() is_element() is_text() text() children() clone_deep(), plus the query methods above. A node that is not an element answers an empty selection rather than refusing, so .items[0].css("a") never needs a guard. clone_deep answers a copy that belongs to no tree, so an edit to it leaves the original alone.

    Selection-level edits apply to every matched element; the verbs that need a position (insert, insert_before, insert_after) live on Element, where a position means one thing.

    #Parsers

    HTML — WHATWG's tokenizer and tree construction, whole: implied html/head/body/tbody, cells that close themselves, foster parenting in front of tables, formatting reopened after a block closed it, the adoption agency for misnested markup, character references with the Windows-1252 repair. The one switch the algorithm takes is scripting: off by default, because reading a document is not running it, and when on a noscript's content is text rather than markup — as a browser that would run it reads it. Foreign content is parsed as foreign: <svg> and <math> carry their namespaces, their tags and attributes are spelled the way SVG and MathML spell them, and the integration points (foreignObject, desc, title, mi, mtext, annotation-xml) are where HTML resumes. A <template>'s contents live in a fragment of their own, on element.content(), so what is inside a template is inert until someone puts it in the document. Framesets are documents too. What the parser fixed is countable afterwards on document.repairs().

    XML — XML 1.0 with Namespaces 1.0, strict: a document reads whole or is refused with the offset of the fault. Names become {uri}local, and writing back reproduces attribute order, CDATA, comments, processing instructions, the doctype with its internal subset, and <a/> versus <a></a>.

    The internal subset is read: entity declarations, general and parameter, nested and with recursion refused; attribute defaults and their types; the content models that decide whether a declaration is well-formed. Nothing is fetched — a document whose entities live in a file beside it is read without them, and document.unresolved() names what was skipped, as XML 1.0 asks a non-validating processor to. standalone="yes" turns that gap into a fault, because the document said it needed nothing from outside. Expansion is bounded by entity_limit, a million characters by default, so a document built to expand for ever is refused instead of read.

    Fragments — @html.loads_fragment(text, context="div") reads markup the way innerHTML does, inside the element named as the context; svg desc and math mi name a foreign context. @xml.loads_fragment(text) reads a snippet that has no single root.

    Streaming — @xml.scan(text, sink) emits Events to any Sink, and @html.scan(text, sink) emits HTML's tokens the same way, before any tree is built; document.events() reads a finished tree back as the same stream.

    #Hypermedia

    moonxml/htmx reads the attributes htmx defines and carries them out: when to ask, what to ask, and where the answer goes.

    let page = @html.loads(
      "<form hx-post='/todos' hx-target='#list' hx-swap='beforeend'>" +
      "<input name='title' value='write it down'><button>Add</button></form>" +
      "<ul id='list'></ul>")

    let form = match page.css("form").items[0] {
      ElementNode(element) => element
      _ => abort("no form")
    }
    let request = @htmx.Hx::of(form).request("submit").unwrap()

    assert_eq(request.address(), "/todos")
    assert_eq(request.query(), "title=write+it+down")
    assert_eq(request.headers().length(), 2)

    ignore(request.answer("<li>a second one</li>"))
    assert_eq(page.css("#list").html(), "<li>a second one</li>")

    The verbs (hx-get, hx-post, hx-put, hx-patch, hx-delete), hx-trigger with once, changed, delay:, throttle:, from:, queue: and every; hx-target with this, closest, find, next, previous and bare selectors; hx-swap with its seven positions and its timing; hx-vals, hx-headers, hx-include, hx-params, hx-select, hx-confirm, hx-indicator, hx-push-url, hx-boost and hx-swap-oob. Attributes inherit down the tree, and hx-disinherit and unset stop them, as htmx does.

    What it does not do is the two things a library cannot: send the request, and wait for the answer. It describes the first and applies the second.

    #Conformance

    Every case of the suites below is replayed and compared against what its source published, whole, rather than against whether it ran:

    SuiteCasesResult
    html5lib tree construction1792all, scripting off and on as each case asks
    html5lib tokenizer7017all
    W3C XML conformance suite1154all: every document it calls well-formed reads, every other is refused
    libxml2's XPath 1.0 corpus326324 agree; the two below answer as XPath 1.0 asks
    W3C CSS3 Selectors test suite99 filesall

    Two XPath cases part ways on purpose. string(12345678901234567890) and its negation: libxml2 prints a number that large in exponent form, and XPath 1.0 wants the decimal form, which is what this library answers.

    A tree built from any of the 1792 documents is written back and read again, and what the writer emits has to read as the same tree. The trees a writer cannot express are counted by the construct that makes them unwritable, and each family has a ceiling: one more case in a family than the ceiling allows fails rather than hides.

    #Examples

    src/examples/tourthe whole surface in one run: moon run src/examples/tour
    src/examples/hypermediaa page that declares its requests: read it, make one, swap the answer in
    src/examples/selectorsevery built-in selector against one document — the run behind the selector board
    src/examples/scrapea page in, a table out: query, filter, reshape, serialize
    src/examples/rewriteread a feed, edit every entry, write it back byte-faithfully

    #What is not here

    document.write, scripting-enabled branches, and the CSS pseudo-classes that need a live browser (:hover, :visited) — none of those can be decided from a document alone, so each is a named answer rather than a silent miss. XSLT, DTD validation and XPath 2.0 are transformations and languages of their own, not features of a tree library. The same goes for htmx's ws: and sse: extensions, hx-on handlers and history cache: they need an event loop and a connection, so moonxml/htmx stops at the request and the swap.

    #Licence

    Apache-2.0. See LICENSE. Test fixtures generated from html5lib-tests (MIT), libxml2's XPath tests (MIT) and the W3C CSS3 Selectors Test Suite in web-platform-tests (BSD-3-Clause).

    Selector

    source
    pub(open) trait Selector {
      fn select(Self, ctx : Selection, query : String) -> Selection raise Refused
    }

    One query language plugged into the chain. Implement this to add your own, register it with Document::register, and run it with selector(name, query) — or pass it straight to custom and skip the registry entirely.

     struct DeepLinks {}
 impl Selector for DeepLinks with select(_self, ctx, _query) {
   ctx.css("a[href]").filter(fn(node) {
     node is ElementNode(e) && e.attr("href").has_prefix("https://")
   })
 }

    Refused

    source
    pub(all) suberror Refused {
      Malformed(at~ : Int, why~ : String)
      BadQuery(at~ : Int, why~ : String)
      UnknownSelector(name~ : String)
      Unsupported(what~ : String)
      Exceeded(at~ : Int, limit~ : Int, got~ : Int)
    } derive(Eq, 
    Debug    )

    Why a document could not be read, or a query could not be run. One family for the whole library, so there is one thing to catch.
    impl Show for Refused

    Refused::equal

    source
    fn Refused::equal(Refused, Refused) -> Bool

    Refused::not_equal

    source
    fn Refused::not_equal(x : Refused, y : Refused) -> Bool

    Refused::output

    source
    fn Refused::output(self : Refused, logger : &Logger) -> Unit

    Refused::to_repr

    source

    Refused::to_string

    source
    fn Refused::to_string(self : Refused) -> String

    Attribute

    source
    pub(all) struct Attribute {
      owner : Element
      name : String
      value : String
    }

    An attribute as a node of its own: XPath's attribute node. It is not a child of its element — the element's attributes stay in attrs, which is what the writer reads — but a query that asks for @href or for the attribute axis answers these, so that attribute::x/self::node() has something with an identity to answer.

    Document

    source
    pub struct Document {
      root : Element
      // private fields
    }

    A document: the virtual root (named #document) holding the top-level nodes, the flavour it was read as, the selector registry, and — for HTML — the tally of what the parser repaired.
    impl Sink for Document

    Document::append

    source
    fn Document::append(self : Document, node : Node) -> Unit

    Add a node at the end of the document: where a comment, a processing instruction or a second document element would go. The usual use is a doctype written before the root, which is what prepend is for.

    Document::by_class

    source
    fn Document::by_class(self : Document, name : String) -> Selection

    The elements carrying the class name.

    Document::by_id

    source
    fn Document::by_id(self : Document, id : String) -> Selection

    The elements whose id attribute is id — getElementById, over the whole document.

    Document::by_name

    source
    fn Document::by_name(self : Document, name : String) -> Selection

    The elements whose name attribute is name.

    Document::by_tag

    source
    fn Document::by_tag(self : Document, name : String) -> Selection

    The elements named name; * answers every element.

    Document::children

    source
    fn Document::children(self : Document) -> Selection

    The document's top-level nodes — the doctype, comments and processing instructions beside the document element, in document order.

    Document::clear

    source
    fn Document::clear(self : Document) -> Unit

    Empty the document: every top-level node goes, and the document is then what a freshly created one is.

    Document::css

    source
    fn Document::css(self : Document, query : String, namespaces? : NamespaceMap) -> Selection raise Refused

    Narrow with a CSS selector over the whole document. Descendant search from the virtual root, so every element is a candidate.

    Document::custom

    source
    fn Document::custom(self : Document, sel : &Selector) -> Selection raise Refused

    Run a selector that was never registered.

    Document::descendants

    source
    fn Document::descendants(self : Document) -> Selection

    Every node in the document, in document order.

    Document::document_element

    source
    fn Document::document_element(self : Document) -> Element?

    The document element — the root's first element child, documentElement in the DOM, getroot() in lxml.

    Document::dump

    source
    fn Document::dump(self : Document) -> Bytes

    A whole document as bytes, in the flavour it was read as.

    Document::dump_html

    source
    fn Document::dump_html(self : Document) -> Bytes

    A whole document as bytes, by HTML's rules.

    Document::dumps

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

    A whole document, in the flavour it was read as.

    Document::dumps_html

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

    A whole document, HTML rules whatever it was read as.

    Document::events

    source

    Read a finished tree back as the event stream it would have produced.

    Document::flavour

    source
    fn Document::flavour(self : Document) -> Flavour

    The flavour this document writes itself back in.

    Document::html

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

    The whole document as markup, in the flavour it was read as.

    Document::new

    source
    fn Document::new(flavour? : Flavour, scripting? : Bool) -> Document

    A fresh document. A tree built by hand has no syntax it was read from, so it writes back with XML's exact rules; ask for flavour=Html when the tree came from HTML.

    Document::prepend

    source
    fn Document::prepend(self : Document, node : Node) -> Unit

    Add a node before everything else in the document.

    Document::push

    source
    fn Document::push(self : Document, event : 
    Event    ) -> Unit

    Document::register

    source
    fn Document::register(self : Document, name : String, sel : &Selector) -> Unit

    Register a selector under a name. Re-registering a name replaces what was there, built-in or not — and a built-in stays reachable through its own method, which calls the engine directly and never consults the registry.

    Document::repairs

    source
    fn Document::repairs(self : Document) -> Repairs

    What the HTML parser repaired; a tree that was not parsed as HTML has an empty tally.

    Document::scripting

    source
    fn Document::scripting(self : Document) -> Bool

    Whether the reader that made this document was allowed to run what it read.

    Document::selector

    source
    fn Document::selector(self : Document, name : String, query : String) -> Selection raise Refused

    Run the selector registered under name, built-in or the caller's own.

    Document::set_repairs

    source
    fn Document::set_repairs(self : Document, repairs : Repairs) -> Unit

    Record what a parser repaired; the parsers call this when they are done.

    Document::set_unresolved

    source
    fn Document::set_unresolved(self : Document, names : Array[String]) -> Unit

    Record the external entities a reader skipped; the XML parser calls this.

    Document::smooth

    source
    fn Document::smooth(self : Document) -> Unit

    Fuse adjacent text nodes everywhere in the document, which is what a writer wants after editing several places.

    Document::text

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

    The text of the whole document, concatenated.

    Document::unresolved

    source
    fn Document::unresolved(self : Document) -> Array[String]

    The external entities the document named but the parser did not read, in the order they were referenced, each name once.

    The library does no I/O, so a document whose entities live in a file beside it is read without them: XML 1.0 says a non-validating processor need not read them, but must tell the application which ones it skipped. That is this list. It is empty for a document that needed nothing from outside.

    Document::xpath

    source
    fn Document::xpath(self : Document, query : String) -> Selection raise Refused

    Narrow to the nodes an XPath 1.0 expression answers, over the whole document.

    Document::xpath_value

    source
    fn Document::xpath_value(self : Document, query : String) -> XPathValue raise Refused

    The typed answer of an XPath 1.0 expression, read from the whole document.

    Element

    source
    pub struct Element {
      name : String
      attrs : Array[(String, String)]
      children : Array[Node]
      parent : Element?
      closed : Bool
      // private fields
    }

    An element: the {uri}local name — the James Clark spelling, chosen over registered prefixes so a node reads the same whichever prefixes the document declared — its attributes in document order, its children, its parent, and how it was closed (<a/> versus <a></a>) for the writer.

    Element::add_class

    source
    fn Element::add_class(self : Element, name : String) -> Unit

    Add a class; an element that already carries it is untouched.

    Element::append

    source
    fn Element::append(self : Element, node : Node) -> Unit

    Append a child node, claiming its parentage.

    Element::attr

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

    The value of an attribute, or None when the element does not carry it.

    Element::by_class

    source
    fn Element::by_class(self : Element, name : String) -> Selection

    The descendants of this element that carry the class name.

    Element::by_id

    source
    fn Element::by_id(self : Element, id : String) -> Selection

    The descendants of this element whose id attribute is id.

    Element::by_name

    source
    fn Element::by_name(self : Element, name : String) -> Selection

    The descendants of this element whose name attribute is name.

    Element::by_tag

    source
    fn Element::by_tag(self : Element, name : String) -> Selection

    The descendants of this element named name; * answers every element.

    Element::child_elements

    source
    fn Element::child_elements(self : Element) -> Array[Element]

    The element children, in order: what a walk of the tree skips the text of.

    Element::classes

    source
    fn Element::classes(self : Element) -> Array[String]

    The class list: the class attribute split on whitespace, empty parts dropped, as HTML says.

    Element::clear

    source
    fn Element::clear(self : Element) -> Unit

    Drop every child, answering each of them to no parent: a node that is no longer in a tree must not still name the tree it left.

    Element::closest

    source
    fn Element::closest(self : Element, query : String) -> Selection raise Refused

    The nearest ancestor of this element, itself included, that matches a CSS selector.

    Element::content

    source
    fn Element::content(self : Element) -> Element?

    The contents of a <template>: a fragment of its own, the way the DOM keeps them, and None for every other element.

    What sits in a template is inert — it is not a child of the element, so a query does not reach it and text() does not read it, which is what a browser does too. set_content is how a caller that builds a template by hand gives it contents.

    Element::css

    source
    fn Element::css(self : Element, query : String, namespaces? : NamespaceMap) -> Selection raise Refused

    Narrow to the descendants of this element that match a CSS selector.

    Element::custom

    source
    fn Element::custom(self : Element, sel : &Selector) -> Selection raise Refused

    Run a selector that was never registered, over this element's descendants.

    Element::document

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

    The document an element belongs to, or None when it is detached: the registry a selector(name, ..) call consults lives on the document.

    Element::has_attr

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

    Whether the element carries an attribute of this name.

    Element::has_class

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

    Whether the element's class list names this class.

    Element::html

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

    The element's inner markup, written in the flavour its document was read as.

    Element::index_in_parent

    source
    fn Element::index_in_parent(self : Element) -> Int

    The position among the parent's children, counting every node; -1 when the element has no parent.

    Element::insert

    source
    fn Element::insert(self : Element, at : Int, node : Node) -> Unit

    Insert node at at; an index past either end clamps to it.

    Element::insert_after

    source
    fn Element::insert_after(self : Element, node : Node) -> Bool

    Insert node after self among its siblings.

    Element::insert_before

    source
    fn Element::insert_before(self : Element, node : Node) -> Bool

    Insert node before self among its siblings.

    Element::is_lang

    source
    fn Element::is_lang(self : Element, wanted : String) -> Bool

    Whether an element's language is wanted, or a regional variety of it: a document in en-GB answers lang("en") and lang("en-gb").

    Element::lang

    source
    fn Element::lang(self : Element) -> String?

    The language an element declares: its lang attribute in HTML, xml:lang in XML. A tree read from either may carry both spellings, so both are read.

    Element::new

    source
    fn Element::new(name : String, children? : Array[Node], attrs? : Array[(String, String)], closed? : Bool) -> Element

    A fresh element. The constructor claims the parentage of the children it is given, so a tree built this way keeps its parent pointers true.

    Element::next_element_sibling

    source
    fn Element::next_element_sibling(self : Element) -> Element?

    The element just after this one among its siblings, skipping text and the other node kinds.

    Element::prepend

    source
    fn Element::prepend(self : Element, node : Node) -> Unit

    Insert node as the first child.

    Element::previous_element_sibling

    source
    fn Element::previous_element_sibling(self : Element) -> Element?

    The element just before this one among its siblings, skipping text and the other node kinds.

    Element::remove

    source
    fn Element::remove(self : Element) -> Bool

    Detach self from the parent, answering true when there was one. bs4's extract; the collector owns the rest.

    Element::remove_attr

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

    Drop an attribute; true when it was there.

    Element::remove_class

    source
    fn Element::remove_class(self : Element, name : String) -> Unit

    Remove one class. The attribute stays, empty if that is what is left — bs4's behaviour, so a caller is never surprised by a missing attribute.

    Element::replace_with

    source
    fn Element::replace_with(self : Element, node : Node) -> Bool

    Take self's place in the parent. bs4's replace_with; false when self has no parent.

    Element::selector

    source
    fn Element::selector(self : Element, name : String, query : String) -> Selection raise Refused

    Run the selector registered under name, over this element's descendants.

    Element::set_attr

    source
    fn Element::set_attr(self : Element, name : String, value : String) -> Unit

    Set or replace an attribute, keeping its place when it is already there.

    Element::set_children

    source
    fn Element::set_children(self : Element, children : Array[Node]) -> Unit

    Replace the children with these, in this order. Every node named is taken out of wherever it sat, and every node the element held is let go, so the parent pointers are true afterwards whichever side of the edit a node was on.

    Element::set_content

    source
    fn Element::set_content(self : Element, content : Element) -> Unit

    Give a <template> a content fragment. A caller who builds one by hand uses this; the parser does it on its own.

    Element::set_text

    source
    fn Element::set_text(self : Element, text : String) -> Unit

    Replace the contents with one text node: the DOM's textContent = …, and what an edit that rewrites a label wants.

    Element::smooth

    source
    fn Element::smooth(self : Element) -> Unit

    Fuse adjacent text nodes. What a writer wants after edits, and what keeps a tree that was cut and rebuilt from carrying confetti. CDATA is left alone: it is a distinct kind so it can round-trip.

    Element::text

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

    The text of this element and everything under it.

    Element::unwrap

    source
    fn Element::unwrap(self : Element) -> Bool

    Unwrap the element: its children move up to its place, the element itself is dropped. bs4's unwrap; false when the element has no parent.

    Element::walk

    source
    fn Element::walk(self : Element, visit : (Node) -> Unit) -> Unit

    Pre-order walk over the whole subtree. Iterative, so a deep tree cannot outrun the stack.

    Element::wrap

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

    Wrap self in a fresh element with the given name, answering the wrapper. None when self has no parent to be replaced in.

    Element::xpath

    source
    fn Element::xpath(self : Element, query : String) -> Selection raise Refused

    Narrow to the nodes an XPath 1.0 expression answers from this element.

    Element::xpath_value

    source
    fn Element::xpath_value(self : Element, query : String) -> XPathValue raise Refused

    The typed answer of an XPath 1.0 expression, read from this element.

    Flavour

    source
    pub(all) enum Flavour {
      Xml
      Html
    } derive(Eq, 
    Debug    )

    How a document was read, and therefore how it writes itself back.
    impl Show for Flavour

    Flavour::equal

    source
    fn Flavour::equal(Flavour, Flavour) -> Bool

    Flavour::not_equal

    source
    fn Flavour::not_equal(x : Flavour, y : Flavour) -> Bool

    Flavour::output

    source
    fn Flavour::output(self : Flavour, logger : &Logger) -> Unit

    Flavour::to_repr

    source

    Flavour::to_string

    source
    fn Flavour::to_string(self : Flavour) -> String

    Namespace

    source
    pub(all) struct Namespace {
      owner : Element
      prefix : String
      uri : String
    }

    A namespace as a node of its own: XPath's namespace node, answered by the namespace axis. prefix is "" for the default namespace.

    NamespaceMap

    source
    pub(all) struct NamespaceMap {
      default : String
      prefixes : Array[(String, String)]
    }

    The namespaces a selector's prefixes resolve against — what @namespace declares in a stylesheet, handed over by the caller.

     doc.css("a|ref", namespaces={ default: "", prefixes: [("a", "urn:x")] })

    Node

    source
    pub(all) enum Node {
      ElementNode(Element)
      TextNode(String)
      CDataNode(String)
      CommentNode(String)
      ProcessingInstructionNode(ProcessingInstruction)
      DoctypeNode(String)
      AttributeNode(Attribute)
      NamespaceNode(Namespace)
    }

    One node of the tree. Mixed content survives: text, CDATA, elements, comments, processing instructions and the doctype are all nodes, in document order — none of which fits in a JSON-shaped value, which is why this is not moonjson.

    Node::by_class

    source
    fn Node::by_class(self : Node, name : String) -> Selection

    The descendants of this node that carry the class name.

    Node::by_id

    source
    fn Node::by_id(self : Node, id : String) -> Selection

    The descendants of this node whose id attribute is id.

    Node::by_name

    source
    fn Node::by_name(self : Node, name : String) -> Selection

    The descendants of this node whose name attribute is name.

    Node::by_tag

    source
    fn Node::by_tag(self : Node, name : String) -> Selection

    The descendants of this node named name.

    Node::children

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

    The children of a node that is an element; a node with no children answers an empty list.

    Node::clone_deep

    source
    fn Node::clone_deep(self : Node) -> Node

    A copy of this node and everything under it, belonging to no tree: editing the copy leaves the original alone. An attribute or a namespace node answers itself — it is not a tree of its own, it is a name on an element, and copying the element copies it.

    Node::closest

    source
    fn Node::closest(self : Node, query : String) -> Selection raise Refused

    The nearest ancestor of this node, itself included, that matches a CSS selector.

    Node::css

    source
    fn Node::css(self : Node, query : String, namespaces? : NamespaceMap) -> Selection raise Refused

    Narrow to the descendants of this node that match a CSS selector; a node that is not an element answers empty.

    Node::custom

    source
    fn Node::custom(self : Node, sel : &Selector) -> Selection raise Refused

    Run a selector that was never registered, over this node's descendants.

    Node::is_element

    source
    fn Node::is_element(self : Node) -> Bool

    Whether the node is an element.

    Node::is_text

    source
    fn Node::is_text(self : Node) -> Bool

    Text, CDATA included: XPath's text() node test matches both.

    Node::name

    source
    fn Node::name(self : Node) -> String

    An element's name, or "" for a node that is not an element.

    Node::selector

    source
    fn Node::selector(self : Node, name : String, query : String) -> Selection raise Refused

    Run the selector registered under name, over this node's descendants.

    Node::text

    source
    fn Node::text(self : Node) -> String

    A node's text content — the DOM's textContent: an element answers the text of its descendants, a text, CDATA, comment or processing-instruction node answers what it carries.

    Node::xpath

    source
    fn Node::xpath(self : Node, query : String) -> Selection raise Refused

    Narrow to the nodes an XPath 1.0 expression answers from this node.

    Node::xpath_value

    source
    fn Node::xpath_value(self : Node, query : String) -> XPathValue raise Refused

    The typed answer of an XPath 1.0 expression, read from this node.

    ProcessingInstruction

    source
    pub(all) struct ProcessingInstruction {
      target : String
      data : String
    }

    A processing instruction: <?target data?>, with data the raw text between the target and the ?>, so an instruction round-trips exactly.

    Repairs

    source
    pub(all) struct Repairs {
      implied : Int
      dropped : Int
      reparented : Int
      closed_at_eof : Int
    }

    What the HTML parser repaired. WHATWG says repairs happen silently; this tally makes them answerable afterwards, for a caller who wants to ask.

    Repairs::any

    source
    fn Repairs::any(self : Repairs) -> Bool

    Whether the parser repaired anything at all.

    Repairs::new

    source
    fn Repairs::new() -> Repairs

    A tally with nothing in it.

    Repairs::total

    source
    fn Repairs::total(self : Repairs) -> Int

    Every repair the parser made, added up.

    Selection

    source
    pub struct Selection {
      items : Array[Node]
      // private fields
    }

    A selection: the nodes a query returned, and the document they belong to. The empty result is an empty list, never a special value, so a chain never branches — and every query method exists on Selection, on Element and on Document, so a chain never has to stop at a node.

     doc.xpath("//ul").css("li.external").xpath("@href")
    .selector("tag", "a").custom(DeepLinks::new())
    .items[2].children[0].css("span").text()

    Selection::add_class

    source
    fn Selection::add_class(self : Selection, name : String) -> Unit

    Add a class to every selected element.

    Selection::append

    source
    fn Selection::append(self : Selection, node : Node) -> Unit

    Append a node to every selected element.

    Selection::at

    source
    #alias("_[_]")
    fn Selection::at(self : Selection, index : Int) -> Node

    selection[i] in the chain: the node at that position, so a chain can step down into one node and carry on. Out of range answers a detached empty element rather than panicking.

    Selection::attr

    source
    fn Selection::attr(self : Selection, name : String) -> String?

    The named attribute of the first selected element that carries it.

    Selection::by_class

    source
    fn Selection::by_class(self : Selection, name : String) -> Selection

    The elements among the descendants that carry the class name.

    Selection::by_id

    source
    fn Selection::by_id(self : Selection, id : String) -> Selection

    The elements among the descendants whose id attribute is id.

    Selection::by_name

    source
    fn Selection::by_name(self : Selection, name : String) -> Selection

    The elements among the descendants whose name attribute is name.

    Selection::by_tag

    source
    fn Selection::by_tag(self : Selection, name : String) -> Selection

    The elements among the descendants whose name is name; * answers them all.

    Selection::children

    source
    fn Selection::children(self : Selection) -> Selection

    The children of every selected node.

    Selection::clear

    source
    fn Selection::clear(self : Selection) -> Unit

    Drop the children of every selected element.

    Selection::closest

    source
    fn Selection::closest(self : Selection, query : String, namespaces? : NamespaceMap) -> Selection raise Refused

    The nearest ancestor — self included — matching a CSS selector.

    Selection::css

    source
    fn Selection::css(self : Selection, query : String, namespaces? : NamespaceMap) -> Selection raise Refused

    Narrow with a CSS selector, Selectors Level 4's statically decidable subset. Searches the descendants of the selected nodes — the context itself is never a candidate, querySelectorAll's rule.

    namespaces resolves the prefixes a selector writes, the way a stylesheet's @namespace rules do; the default matches no prefix at all.

    Selection::custom

    source
    fn Selection::custom(self : Selection, sel : &Selector) -> Selection raise Refused

    Run a selector that was never registered: no name, no state.

    Selection::descendants

    source
    fn Selection::descendants(self : Selection) -> Selection

    Every node below the selected nodes, in document order.

    Selection::eq

    source
    fn Selection::eq(self : Selection, i : Int) -> Selection

    The selected node at i; a negative index counts from the end, the way jQuery's eq does. Out of range answers empty.

    Selection::filter

    source
    fn Selection::filter(self : Selection, keep : (Node) -> Bool) -> Selection

    Keep the selected nodes a closure accepts.

    Selection::first

    source
    fn Selection::first(self : Selection) -> Selection

    The first selected node; empty stays empty.

    Selection::html

    source
    fn Selection::html(self : Selection) -> String

    The inner HTML of the first selected element, written in the flavour its document was read as; "" when the selection holds no element.

    Selection::last

    source
    fn Selection::last(self : Selection) -> Selection

    The last selected node; empty stays empty.

    Selection::length

    source
    fn Selection::length(self : Selection) -> Int

    How many nodes the selection holds.

    Selection::new

    source
    fn Selection::new() -> Selection

    An empty selection, belonging to no document.

    Selection::of

    source
    fn Selection::of(nodes : Array[Node]) -> Selection

    A selection of these nodes, in the order given, carrying the document the first of them belongs to.

    Selection::parent

    source
    fn Selection::parent(self : Selection) -> Selection

    The parent of every selected node that has one.

    Selection::prepend

    source
    fn Selection::prepend(self : Selection, node : Node) -> Unit

    Insert a node as the first child of every selected element.

    Selection::remove

    source
    fn Selection::remove(self : Selection) -> Unit

    Detach every selected element from its parent.

    Selection::remove_attr

    source
    fn Selection::remove_attr(self : Selection, name : String) -> Unit

    Remove an attribute from every selected element.

    Selection::remove_class

    source
    fn Selection::remove_class(self : Selection, name : String) -> Unit

    Remove a class from every selected element.

    Selection::replace_with

    source
    fn Selection::replace_with(self : Selection, node : Node) -> Unit

    Put a node in the place of every selected element.

    Selection::selector

    source
    fn Selection::selector(self : Selection, name : String, query : String) -> Selection raise Refused

    Run a selector by the name it was registered under, built-in or the caller's own. An unregistered name raises.

    Selection::set_attr

    source
    fn Selection::set_attr(self : Selection, name : String, value : String) -> Unit

    Set an attribute on every selected element.

    Selection::set_text

    source
    fn Selection::set_text(self : Selection, text : String) -> Unit

    Replace the children of every selected element with one text node.

    Selection::smooth

    source
    fn Selection::smooth(self : Selection) -> Unit

    Fuse adjacent text nodes under every selected element.

    Selection::text

    source
    fn Selection::text(self : Selection) -> String

    The text content of every selected node, concatenated.

    Selection::unwrap

    source
    fn Selection::unwrap(self : Selection) -> Unit

    Replace every selected element with its children.

    Selection::wrap

    source
    fn Selection::wrap(self : Selection, name : String) -> Unit

    Wrap every selected element in a fresh element of this name.

    Selection::xpath

    source
    fn Selection::xpath(self : Selection, query : String) -> Selection raise Refused

    Narrow the selection with an XPath 1.0 expression, evaluated with each selected node as the context node.

    The answer is a node-set; an expression that evaluates to a string, number or boolean answers its string value as one text node, so the chain never breaks — doc.xpath("string(//h1)").text() reads the way it should. xpath_value is the typed answer.

    Selection::xpath_value

    source
    fn Selection::xpath_value(self : Selection, query : String) -> XPathValue raise Refused

    The typed XPath 1.0 answer: nodes, a string, a number or a boolean.

    SelectorFn

    source
    pub struct SelectorFn {
      f : (Selection, String) -> Selection raise Refused
    }

    A selector that is a closure — the shape a selector with no state of its own takes. A selector that carries configuration is a struct implementing Selector directly, with a constructor of its own.

    SelectorFn::new

    source
    fn SelectorFn::new(f : (Selection, String) -> Selection raise Refused) -> SelectorFn

    A selector made of a closure: the shape one with no state of its own takes.

    SelectorFn::select

    source
    fn SelectorFn::select(self : SelectorFn, ctx : Selection, query : String) -> Selection raise Refused

    XPathValue

    source
    pub(all) enum XPathValue {
      Nodes(Selection)
      Str(String)
      Num(Double)
      Flag(Bool)
    }

    An XPath 1.0 result: what the expression actually answered.
    impl Show for XPathValue

    XPathValue::output

    source
    fn XPathValue::output(self : XPathValue, logger : &Logger) -> Unit

    XPathValue::to_string

    source
    fn XPathValue::to_string(self : XPathValue) -> String

    dump

    source
    fn dump(node : Node) -> Bytes

    The XML serialization of a node, as bytes.

    dump_html

    source
    fn dump_html(node : Node) -> Bytes

    The HTML serialization of a node, as bytes.

    dumps

    source
    fn dumps(node : Node) -> String

    The XML serialization of a node.

    dumps_html

    source
    fn dumps_html(node : Node) -> String

    The HTML serialization of a node, WHATWG's rules.

    local_of

    source
    fn local_of(name : String) -> String

    The local part of a {uri}local name.

    namespace_map

    source
    let namespace_map : NamespaceMap

    No namespaces declared: type selectors match any namespace, and an unprefixed attribute selector matches the attribute with no namespace.

    namespace_of

    source
    fn namespace_of(name : String) -> String?

    The URI of a {uri}local name, or None when the name carries none.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io