🥮 mooncakes.io
    Sign in

    xml

    A document-buffered pull XML parser for MoonBit

    xml
    parser
    Download zip
    Author
    Version
    0.6.1
    License
    Apache-2.0
    Repository
    Last updated
    7 days ago
    Downloads
    58K

    #xml

    A document-buffered pull XML parser for MoonBit, inspired by quick-xml.

    #Features

    • Pull-parser model - Read XML events one at a time (like StAX in Java)
    • Document-buffered input - Constructors load the full input, then callers pull events one at a time
    • Multi-backend - Works on wasm, wasm-gc, js, and native
    • XML 1.0 + Namespaces 1.0 - Unicode names plus namespace-aware events
    • Source-aware parsing - Authored ranges for events and attributes, plus contextual spans for errors

    #Usage

    let xml = "<root><item id=\"1\">Hello</item></root>"
    let reader = @xml.Reader::from_string(xml)

    while true {
      let event = reader.read_event()
      match event.kind {
        Start(elem) => println("Start: \{elem.name}")
        End(name) => println("End: \{name}")
        Text(content) => println("Text: \{content}")
        Eof => break
        _ => continue
      }
    }

    Callers obtain XML text from files, network responses, or other sources before passing it to Reader::from_string or NamespaceReader::from_string.

    #Namespace-aware parsing

    Use NamespaceReader when callers need namespace URI, prefix, and local-name information. The original Reader remains available for raw qualified names and namespace declaration attributes.

    let reader = @xml.NamespaceReader::from_string(
      "<p:root xmlns:p=\"urn:example\" p:id=\"1\"/>",
    )

    match reader.read_event().kind {
      Empty(element) => {
        println(element.name.local_name) // root
        println(element.name.namespace_uri) // Some("urn:example")
      }
      _ => ()
    }

    Namespace declarations are exposed through NamespaceElement::namespace_declarations and are not included in its normal attributes. Default namespaces apply to element names but not to unprefixed attribute names.

    #Checked writing

    Writer validates XML names, characters, delimiter sequences, and document structure as output is added. Its write methods and to_string raise WriterError instead of returning malformed XML; to_string also requires exactly one complete root element.

    #Source locations

    Every event returned by Reader::read_event includes its authored source range. Event and attribute spans are half-open; offsets count UTF-16 code units, so they can slice the original MoonBit String directly.

    let input = "<root id='a&amp;b'/>"
    let reader = @xml.Reader::from_string(input)
    let parsed = reader.read_event()
    let authored = input[parsed.span.start.offset:parsed.span.end.offset]
    assert_eq(authored, input)
    guard parsed.kind is Empty(element) else { abort("expected empty element") }
    assert_eq(element.attributes[0].value, "a&b")

    Each XmlAttribute contains the whole attribute span plus separate name and unquoted value spans. Parse failures raise XmlError::At, which contains an XmlErrorKind and a relevant authored source span. Syntax failures normally cover input consumed while detecting the error, while an unclosed-element error points to the unmatched opening tag. Events produced by entity expansion point to the authored entity reference. Defaulted attributes point to their definitions in the internal DTD subset.

    #Event Types

    Event contains an EventKind and a SourceSpan. The EventKind variants are:

    EventDescription
    Start(XmlElement)Opening tag <name>
    End(String)Closing tag </name>
    Empty(XmlElement)Self-closing tag <name/>
    Text(String)Text content (entities decoded)
    CData(String)CDATA section <![CDATA[...]]>
    Comment(String)Comment <!-- ... -->
    PI(target, data)Processing instruction <?target data?>
    Decl(version, encoding, standalone)XML declaration
    DocType(String)DOCTYPE declaration
    EofEnd of document

    #W3C Conformance

    Tests are compiled from the complete W3C XML Conformance Test Suite 20130923 catalog. Expected acceptance and rejection come from the catalog; output comparisons use the suite's official OUTPUT files, rather than expectations generated by another parser.

    Local validation: 1,821 tests pass on wasm, wasm-gc, js, and native; one known conformance failure is explicitly skipped.

    CategoryTestsAssertion
    W3C accepted documents771Includes valid and DTD invalid documents; 246 also compare official canonical output
    W3C malformed documents899Reject through the reader selected by namespace metadata
    Unit and property tests152Raw events, reader, writer, escape, namespaces, source spans, resources, properties and mutation fuzzing

    One of the 771 acceptance tests, rmt-e3e-13, remains a known failure, with its original W3C expectation intact. After a skipped parameter entity, an undeclared general entity can be a validity error rather than a well-formedness error. The current API rejects it and has no unresolved-entity event. The generated test has a named #skip reason, and can be run explicitly:

    moon test --target native --include-skipped --filter 'w3c/invalid/rmt-e3e-13'
# Currently fails: undefined entity reference &ent2;

    The coverage ledger accounts for all 2,585 catalog entries, including every fixture URI, classification, assertion, exclusion reason and known failure. Included collections cover XMLTEST, Sun, OASIS/NIST, IBM, XML 1.0 edition errata, Namespaces 1.0 and namespace errata. The upstream root catalog's incorrect base for eduni/misc is corrected explicitly.

    The test adapter implements the suite's Second Canonical Form. It retains qualified names and namespace declarations, sorts attributes by Unicode code point, escapes data, expands empty elements and removes comments as required by that format. It does not verify raw lexical event boundaries or source spans; separate public-API regressions check those. The 13 official outputs containing NOTATION declarations cannot be reproduced by the current event API; their acceptance tests remain enabled and their output checks are explicitly recorded as unavailable. Accepted cases without a usable official output check acceptance only.

    Property tests run 1,280 generated cases with fixed seeds. Mutation fuzzing runs 3,000 mutated inputs through both readers, checking source ranges on accepted documents and errors and failing on panics. CI also runs 12 generator tests and checks reproducibility against the pinned W3C archive.

    #Running Tests

    The generated MoonBit tests embed their fixtures and need no runtime file I/O or Python:

    moon test --target all --deny-warn

    #Regenerating Tests

    Python 3.12+, lxml and moonfmt are required. The generator verifies the downloaded archive's SHA-256 before reading the full catalog. Missing fixtures, missing outputs and duplicate IDs stop generation.

    python3 -m pip install -r scripts/requirements.txt
python3 scripts/generate_conformance_tests.py --download
python3 -m unittest discover -s scripts -p 'test_*.py'

# Check that committed tests and coverage match the pinned source:
python3 scripts/generate_conformance_tests.py --download --check

    #Scope Exclusions

    The ledger records 915 excluded entries:

    ReasonEntries
    XML 1.1 / Namespaces 1.1274
    Tests restricted to older XML editions310
    Requires external entity contents265
    Byte decoding / encoding-declaration tests outside the decoded String API57
    Optional errors with no required accept/reject result9

    DTD invalid documents are included: this library does not validate DTD constraints and should accept them. No fixture is excluded because another parser accepts it, rejects it or produces a different result. The explicitly named known failure is separate from these scope exclusions.

    #Performance checks

    Run the benchmarks with:

    moon bench --target native --release --filter 'bench *'

    Inputs are built outside the measured closures; each run constructs a reader and collects all events. The cases cover character-reference queues, deep namespace scopes with 512 inherited bindings, nested replacement markup, and large text documents.

    Measurements on 2026-10-10, Apple M3 Max, MoonBit v0.10.14+7d59c7ec9, native release builds. The baseline is commit 19e6070; both versions used the same benchmark cases. Values are local mean timings, not portable performance thresholds.

    CaseBaselineAfter optimization
    1,024 character references801 µs375 µs
    4,096 character references11.55 ms1.57 ms
    16,384 character references228.67 ms6.30 ms
    Namespace depth 2567.02 ms916 µs
    Namespace depth 1,02426.68 ms1.50 ms
    4,096 children from nested entities345.00 ms8.79 ms
    2 MiB of text11.14 ms10.96 ms

    Pending events are consumed by index, and namespace scopes store only changed bindings. Replacement content is parsed directly while sharing DTD tables, recursion tracking, and the document expansion budget. Attribute values retain their separate XML normalization rules.

    #Limitations

    • Non-validating - Does not validate against DTD
    • UTF-8 only - Other encodings not supported
    • XML 1.0 only - XML 1.1 not supported
    • Bounded entity expansion - Internal entities are limited to 32 nesting levels and 262,144 expanded characters per document

    External entity declarations are parsed, but their contents are not resolved. Referencing an external entity raises an error.

    #License

    Apache-2.0

    WriterError

    source
    pub(all) suberror WriterError {
      InvalidName(String)
      InvalidContent(String)
      InvalidStructure(String)
      InvalidDeclaration(String)
    } derive(Eq, 
    Debug    )

    An error raised when Writer would produce an invalid XML document.

    WriterError::equal

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

    WriterError::not_equal

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

    WriterError::to_repr

    source

    XmlError

    source
    pub(all) suberror XmlError {
      At(error~ : XmlErrorKind, span~ : SourceSpan)
    } derive(Eq, 
    Debug    )

    An XML parsing error paired with its relevant authored source range. Syntax errors normally cover input consumed while detecting the failure; an unclosed-element error covers the unmatched opening tag.
    impl Show for XmlError

    XmlError::equal

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

    XmlError::not_equal

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

    XmlError::output

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

    XmlError::to_repr

    source

    XmlError::to_string

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

    XmlErrorKind

    source
    pub(all) suberror XmlErrorKind {
      UnexpectedEof
      InvalidSyntax(String)
      UnmatchedTag(expected~ : String, found~ : String)
      InvalidAttribute(String)
      InvalidEntity(String)
    } derive(Eq, 
    Debug    )

    XML parsing error

    XmlErrorKind::equal

    source

    XmlErrorKind::not_equal

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

    XmlErrorKind::output

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

    XmlErrorKind::to_repr

    source

    XmlErrorKind::to_string

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

    Event

    source
    pub struct Event {
      kind : EventKind
      span : SourceSpan
    } derive(Eq)

    An XML event together with its authored source range.
    impl Show for Event
    impl Debug for Event

    Event::equal

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

    Event::not_equal

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

    Event::output

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

    Event::to_repr

    source

    Event::to_string

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

    EventKind

    source
    pub(all) enum EventKind {
      Start(XmlElement)
      End(String)
      Empty(XmlElement)
      Text(String)
      CData(String)
      Comment(String)
      PI(target~ : String, data~ : String)
      Decl(version~ : String, encoding~ : String?, standalone~ : String?)
      DocType(String)
      Eof
    } derive(Eq, 
    Debug    )

    An XML event returned by the parser
    impl Show for EventKind

    EventKind::equal

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

    EventKind::not_equal

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

    EventKind::output

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

    EventKind::to_repr

    source

    EventKind::to_string

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

    NamespaceAttribute

    source
    pub struct NamespaceAttribute {
      name : XmlName
      value : String
      span : SourceSpan
      name_span : SourceSpan
      value_span : SourceSpan
    } derive(Eq, 
    Debug    )

    An XML attribute with a namespace-resolved name.

    NamespaceAttribute::equal

    source

    NamespaceAttribute::not_equal

    source

    NamespaceAttribute::to_repr

    source

    NamespaceDeclaration

    source
    pub struct NamespaceDeclaration {
      prefix : String?
      namespace_uri : String
      span : SourceSpan
      name_span : SourceSpan
      value_span : SourceSpan
    } derive(Eq, 
    Debug    )

    A namespace declaration from an element start tag. None denotes the default namespace declaration.

    NamespaceDeclaration::equal

    source

    NamespaceDeclaration::not_equal

    source

    NamespaceDeclaration::to_repr

    source

    NamespaceElement

    source
    pub struct NamespaceElement {
      name : XmlName
      attributes : Array[NamespaceAttribute]
      namespace_declarations : Array[NamespaceDeclaration]
    } derive(Eq, 
    Debug    )

    An XML element with namespace-resolved element and attribute names. Namespace declarations are exposed separately and are not normal attributes.

    NamespaceElement::equal

    source

    NamespaceElement::not_equal

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

    NamespaceElement::to_repr

    source

    NamespaceEvent

    source
    pub struct NamespaceEvent {
      kind : NamespaceEventKind
      span : SourceSpan
    } derive(Eq, 
    Debug    )

    A namespace-aware XML event with its authored source range.

    NamespaceEvent::equal

    source

    NamespaceEvent::not_equal

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

    NamespaceEvent::to_repr

    source

    NamespaceEventKind

    source
    pub(all) enum NamespaceEventKind {
      Start(NamespaceElement)
      End(XmlName)
      Empty(NamespaceElement)
      Text(String)
      CData(String)
      Comment(String)
      PI(target~ : String, data~ : String)
      Decl(version~ : String, encoding~ : String?, standalone~ : String?)
      DocType(String)
      Eof
    } derive(Eq, 
    Debug    )

    The semantic kind of a namespace-aware XML event.

    NamespaceEventKind::equal

    source

    NamespaceEventKind::not_equal

    source

    NamespaceEventKind::to_repr

    source

    NamespaceReader

    source
    pub struct NamespaceReader {
      reader : Reader
      scope : Map[String, String]
      scopes : Array[Array[(String, String?)]]
    }

    A namespace-aware adapter over the raw XML Reader event stream.

    NamespaceReader::column

    source
    fn NamespaceReader::column(self : NamespaceReader) -> Int

    Get the current one-indexed column number.

    NamespaceReader::from_string

    source
    fn NamespaceReader::from_string(input : String) -> NamespaceReader

    Create a namespace-aware reader from a string.

    NamespaceReader::is_eof

    source
    fn NamespaceReader::is_eof(self : NamespaceReader) -> Bool

    Check whether the underlying reader has consumed its input.

    NamespaceReader::line

    source
    fn NamespaceReader::line(self : NamespaceReader) -> Int

    Get the current one-indexed line number.

    NamespaceReader::read_event

    source
    fn NamespaceReader::read_event(self : NamespaceReader) -> NamespaceEvent raise XmlError

    Read the next namespace-aware XML event.

    NamespaceReader::read_events_until_eof

    source
    fn NamespaceReader::read_events_until_eof(self : NamespaceReader) -> Array[NamespaceEvent] raise XmlError

    Read all namespace-aware events through the final Eof event.

    Reader

    source
    pub struct Reader {
      input : Array[Char]
      pos : Int
      offset : Int
      line : Int
      column : Int
      entities : Map[String, String]
      entity_expansion_remaining : 
    Ref    [Int]
      entity_stack : Array[String]
      namespace_aware : Bool
      attr_types : Map[String, String]
      default_attributes : Map[String, Array[XmlAttribute]]
      tag_stack : Array[(String, SourceSpan)]
      seen_root : Bool
      seen_doctype : Bool
      root_closed : Bool
      seen_content : Bool
      just_saw_decl : Bool
      pending_events : Array[Event]
      pending_index : Int
      internal_subset_events : Array[Event]
      just_saw_doctype : Bool
      in_entity_content : Bool
      in_reference : Bool
    }

    A pull XML reader over a fully buffered document

    Reader::column

    source
    fn Reader::column(self : Reader) -> Int

    Get current column number (1-indexed)

    Reader::from_string

    source
    fn Reader::from_string(input : String) -> Reader

    Create a new reader from a string

    Reader::is_eof

    source
    fn Reader::is_eof(self : Reader) -> Bool

    Check if the reader has reached the end

    Reader::line

    source
    fn Reader::line(self : Reader) -> Int

    Get current line number (1-indexed)

    Reader::read_event

    source
    fn Reader::read_event(self : Reader) -> Event raise XmlError

    Read the next XML event

    Reader::read_events_until_eof

    source
    fn Reader::read_events_until_eof(self : Reader) -> Array[Event] raise XmlError

    Read all events until EOF (inclusive) as an Array. Includes the final Eof event in the result. Raises XmlError if parsing fails.

    SourcePosition

    source
    pub struct SourcePosition {
      offset : Int
      line : Int
      column : Int
    } derive(Eq, 
    Debug    )

    A position in the original XML source. offset is a zero-indexed UTF-16 code-unit offset suitable for slicing the original MoonBit String; line and column are one-indexed and count Unicode characters.

    SourcePosition::equal

    source

    SourcePosition::not_equal

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

    SourcePosition::to_repr

    source

    SourceSpan

    source
    pub struct SourceSpan {
      start : SourcePosition
      end : SourcePosition
    } derive(Eq, 
    Debug    )

    A half-open range [start, end) in the original XML source.

    SourceSpan::equal

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

    SourceSpan::not_equal

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

    SourceSpan::to_repr

    source

    Writer

    source
    pub struct Writer {
      buffer : StringBuilder
      element_stack : Array[String]
      seen_root : Bool
      wrote_anything : Bool
      doctype_root : String?
    }

    An XML writer for generating XML output

    Writer::cdata

    source
    fn Writer::cdata(self : Writer, content : String) -> Unit raise WriterError

    Write CDATA section

    Writer::comment

    source
    fn Writer::comment(self : Writer, content : String) -> Unit raise WriterError

    Write a comment

    Writer::empty_element

    source
    fn Writer::empty_element(self : Writer, name : String, attributes : Array[(String, String)]) -> Unit raise WriterError

    Write a self-closing element

    Writer::end_element

    source
    fn Writer::end_element(self : Writer, name : String) -> Unit raise WriterError

    Write an end element

    Writer::new

    source
    fn Writer::new() -> Writer

    Create a new writer

    Writer::start_element

    source
    fn Writer::start_element(self : Writer, name : String, attributes : Array[(String, String)]) -> Unit raise WriterError

    Write a start element

    Writer::text

    source
    fn Writer::text(self : Writer, content : String) -> Unit raise WriterError

    Write text content (escaped)

    Writer::to_string

    source
    fn Writer::to_string(self : Writer) -> String raise WriterError

    Get the generated XML string

    Writer::write_event

    source
    fn Writer::write_event(self : Writer, event : Event) -> Unit raise WriterError

    Write an XML event

    XmlAttribute

    source
    pub struct XmlAttribute {
      name : String
      value : String
      span : SourceSpan
      name_span : SourceSpan
      value_span : SourceSpan
    } derive(Eq, 
    Debug    )

    A parsed attribute together with its authored source ranges. value_span excludes the surrounding quote characters. Defaulted attributes refer to their definitions in the internal DTD subset.

    XmlAttribute::equal

    source

    XmlAttribute::not_equal

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

    XmlAttribute::to_repr

    source

    XmlElement

    source
    pub struct XmlElement {
      name : String
      attributes : Array[XmlAttribute]
    } derive(Eq)

    An XML element with tag name and attributes
    impl Show for XmlElement
    impl Debug for XmlElement

    XmlElement::equal

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

    XmlElement::get

    source
    fn XmlElement::get(self : XmlElement, attr_name : String) -> String?

    Get an attribute value by name

    XmlElement::not_equal

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

    XmlElement::output

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

    XmlElement::to_repr

    source

    XmlElement::to_string

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

    XmlName

    source
    pub struct XmlName {
      qualified_name : String
      prefix : String?
      local_name : String
      namespace_uri : String?
    } derive(Eq, 
    Debug    )

    An XML qualified name resolved against the namespace declarations in scope.

    XmlName::equal

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

    XmlName::not_equal

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

    XmlName::to_repr

    source

    escape

    source
    fn escape(text : String) -> String

    Escape special XML characters in text Replaces: < > & " ' and carriage returns (to preserve text on XML readback).

    unescape

    source
    fn unescape(text : String) -> String raise XmlErrorKind

    Unescape XML entities Handles: < > & " ' &#NN; &#xHH;

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io