Skip to content

std::xml

Reading and writing XML 1.0 with namespaces. xml.decode reads a document into a tree of Elements, and Element.child, Element.text and Element.attribute find what a program wants in it:

import std::xml.{self, Element}

doc = xml.decode("<feed><title>News</title></feed>")?

title = Element.child_text(doc, "title")

xml.tokens reads a Reader a token at a time, for a document too large to hold. xml.encode and xml.write write a tree, escaped, with an optional indent and XML declaration.

A name keeps both the namespace it is in and the prefix the document wrote, so a tree written back says what it said. CDATA sections are read as text, and the XML declaration is checked and dropped. Comments and processing instructions are nodes of the tree. Text must be UTF-8; a declaration of any other encoding is an error.

Reading is Go’s encoding/xml, which fetches nothing: it never reads an external entity or DTD, and the only entities it knows are the five XML predefines (&lt;, &gt;, &amp;, &apos;, &quot;) and character references. A document with a DOCTYPE is refused unless allow_doctype is set, and then its DTD is skipped unread, so an entity it declares is still an error where it is used. An XXE or “billion laughs” document fails before it expands anything.

Import with import std::xml.

fn xml_namespace() -> String

The namespace the xml prefix is bound to in every document.

struct Name
    local: String
    space: String = ""
    prefix: String = ""
end

An element’s or attribute’s name: its local part, the namespace it is in ("" for none), and the prefix written before it ("" for none). An element with no prefix is in the default namespace, if one is declared; an attribute with no prefix is in none.

assert "${Name{local: "Key"}}" == "Key"

assert "${Name{local: "href", space: "http://www.w3.org/1999/xlink", prefix: "xlink"}}"
    == "xlink:href"

impl Display for Name

fn to_string(name: Name) -> String

impl Display.to_string

The name as written: prefix:local, or local with no prefix.

impl Equatable for Name

fn equal(a: Name, b: Name) -> Bool

impl Equatable.equal

impl Debug for Name

fn inspect(value: Name) -> String

impl Debug.inspect

struct Attribute
    name: Name
    value: String
end

An attribute: its name and its value, with entities and character references replaced.

impl Equatable for Attribute

fn equal(a: Attribute, b: Attribute) -> Bool

impl Equatable.equal

impl Debug for Attribute

fn inspect(value: Attribute) -> String

impl Debug.inspect

struct Namespace
    prefix: String
    uri: String
end

A namespace declaration on an element: xmlns:prefix="uri", or xmlns="uri" when prefix is "".

impl Equatable for Namespace

fn equal(a: Namespace, b: Namespace) -> Bool

impl Equatable.equal

impl Debug for Namespace

fn inspect(value: Namespace) -> String

impl Debug.inspect

struct Element
    name: Name
    attributes: List<Attribute> = []
    namespaces: List<Namespace> = []
    children: List<Node> = []
end

An element: its name, its attributes, the namespaces it declares, and its children in document order.

a = Element{name: Name{local: "a"}, children: [Node.Text("hi")]}
assert xml.encode(a) == Ok("<a>hi</a>")
fn new(local: String, children: List<Node> = []) -> Element

type function on Element

An element named local, in no namespace, with children.

assert Element.new("b", [Node.Text("x")]) == Element{
    name:     Name{local: "b"},
    children: [Node.Text("x")],
}
fn elements(element: Element) -> List<Element>

type function on Element

The child elements, in order.

doc = decode("<a>x<b/><!-- c --><d/></a>")!
assert Element.elements(doc) |> Iter.map(fn e -> e.name.local) |> Iter.to_list() == ["b", "d"]
fn child(element: Element, local: String, space: Maybe<String> = None) -> Maybe<Element>

type function on Element

The first child element named local, in the namespace space, or in any namespace when space is None.

doc = decode("<r xmlns='urn:x'><k>1</k><k>2</k></r>")!
assert Element.child(doc, "k") |> Maybe.map(&Element.text(&1)) == Some("1")
assert Element.child(doc, "k", space: Some("urn:y")) == None
fn children_named(element: Element, local: String, space: Maybe<String> = None) -> List<Element>

type function on Element

Every child element named local, in the namespace space, or in any namespace when space is None.

doc = decode("<r><k>1</k><j/><k>2</k></r>")!

assert Element.children_named(doc, "k") |> Iter.map(&Element.text(&1)) |> Iter.to_list() == [
    "1",
    "2",
]
fn child_text(element: Element, local: String, space: Maybe<String> = None) -> Maybe<String>

type function on Element

The text of the first child element named local, as Element.text reads it.

doc = decode("<Error><Code>NoSuchKey</Code></Error>")!
assert Element.child_text(doc, "Code") == Some("NoSuchKey")
assert Element.child_text(doc, "Message") == None
fn text(element: Element) -> String

type function on Element

All the text in the element and the elements in it, in document order, with no comment or instruction.

doc = decode("<p>a <b>bold</b> <![CDATA[<raw>]]>& more<!-- no --></p>")!
assert Element.text(doc) == "a bold <raw>& more"
fn attribute(element: Element, local: String, space: String = "") -> Maybe<String>

type function on Element

The value of the attribute named local in the namespace space, which is "", none, for an attribute written with no prefix.

doc = decode("<a id='7' xmlns:x='urn:x' x:id='8'/>")!
assert Element.attribute(doc, "id") == Some("7")
assert Element.attribute(doc, "id", space: "urn:x") == Some("8")
assert Element.attribute(doc, "name") == None

impl Equatable for Element

fn equal(a: Element, b: Element) -> Bool

impl Equatable.equal

impl Debug for Element

fn inspect(value: Element) -> String

impl Debug.inspect

enum Node
    Element Element
    Text String
    Comment String
    Instruction { target: String, data: String }
end

What an element holds: an element, text, a comment or a processing instruction. Adjacent text and CDATA are one Text.

impl Equatable for Node

fn equal(a: Node, b: Node) -> Bool

impl Equatable.equal

impl Debug for Node

fn inspect(value: Node) -> String

impl Debug.inspect

enum Token
    Start { name: Name, attributes: List<Attribute>, namespaces: List<Namespace> }
    End { name: Name }
    Text String
    Comment String
    Instruction { target: String, data: String }
    Doctype String
end

A token of a document, as tokens reads them. Text between tags is Text, white space included; adjacent CDATA and text may be more than one token. White space outside the root element is not a token, and neither is the XML declaration.

Variants

  • Start

    A start tag, or the start of an empty-element tag <a/>, which an End follows.

  • Doctype

    A DOCTYPE, with what follows <! and before >, read only with allow_doctype.

impl Equatable for Token

fn equal(a: Token, b: Token) -> Bool

impl Equatable.equal

impl Debug for Token

fn inspect(value: Token) -> String

impl Debug.inspect

enum Error
    Syntax { message: String, line: Int, column: Int }
    Io { error: io.Error }
    Invalid { message: String }
end

Why XML could not be read or written.

Variants

  • Syntax

    The text is not well-formed XML, at line and column, both from 1, the column in code points.

  • Io

    The Reader or the Writer failed.

  • Invalid

    A tree cannot be written: a name that is not an XML name, a comment holding --, an instruction holding ?>, or a prefix with no namespace.

assert decode("<a><b></a>") |> Result.map_err(&Display.to_string(&1)) == Err(
    "line 1, column 7: <b> is closed by </a>"
)

impl Display for Error

fn to_string(error: Error) -> String

impl Display.to_string

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

fn decode(text: String, allow_doctype: Bool = False) -> Result<Element, Error>

The root element of the document text. Comments and processing instructions outside the root are dropped.

doc = decode(
    """
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Name>photos</Name>
      <Contents><Key>a&b.jpg</Key><Size>42</Size></Contents>
    </ListBucketResult>
    """
)!

assert doc.name == Name{local: "ListBucketResult", space: "http://s3.amazonaws.com/doc/2006-03-01/"}

assert Element.child(doc, "Contents") |> Maybe.flat_map(&Element.child_text(&1, "Key")) == Some(
    "a&b.jpg"
)

assert decode("<a>&ext;</a>") == Err(Error.Syntax{
        message: "invalid character entity &ext;",
        line:    1,
        column:  9,
    })
fn decode_bytes(data: Bytes, allow_doctype: Bool = False) -> Result<Element, Error>

The root element of the document data, which must be UTF-8.

assert decode_bytes(String.to_bytes("<a/>")) == Ok(Element.new("a"))
fn read(reader: Reader, allow_doctype: Bool = False) -> Result<Element, Error>

The root element of the document reader holds, read to its end.

assert read(Reader.from_text("<a>1</a>")) == Ok(Element.new("a", [Node.Text("1")]))
fn tokens(reader: Reader, allow_doctype: Bool = False) -> Iter<Result<Token, Error>>

Each token left in reader, read as the iterator runs, so a large document is never held whole. A failure is an item, and the last one. Like Reader.lines, it runs once: a second run carries on from where the stream is.

r = Reader.from_text("<a x='1'>hi<b/></a>")

assert Result.collect(tokens(r)) == Ok([
        Token.Start{
            name: Name{local: "a"},
            attributes: [
                Attribute{name: Name{local: "x"}, value: "1"},
            ],
            namespaces: [],
        },
        Token.Text("hi"),
        Token.Start{name: Name{local: "b"}, attributes: [], namespaces: []},
        Token.End{name: Name{local: "b"}},
        Token.End{name: Name{local: "a"}},
    ])
struct WriteOptions
    indent: String = ""
    declaration: Bool = False
end

How encode and write write a tree.

tree = Element.new(
    "a",
    [Node.Element(Element.new("b", [Node.Text("1")])), Node.Element(Element.new("c"))],
)

assert encode(tree, WriteOptions{indent: "  ", declaration: True}) == Ok(
    """
    <?xml version="1.0" encoding="UTF-8"?>
    <a>
      <b>1</b>
      <c/>
    </a>
    """
)

impl Debug for WriteOptions

fn inspect(value: WriteOptions) -> String

impl Debug.inspect

fn encode(root: Element, options: WriteOptions = WriteOptions{}) -> Result<String, Error>

The tree under root as XML text. Text and attribute values are escaped, an element with no children is written <a/>, and a namespace an element’s or attribute’s name is in is declared where it is not already, so the text reads back as the same tree, with any declarations added. A tree that cannot be written is Err(.Invalid).

a = Element{
    name: Name{local: "a", space: "urn:x"},
    attributes: [
        Attribute{name: Name{local: "q"}, value: "1 < 2 & \"3\""},
    ],
    children: [Node.Text("<&>")],
}

assert encode(a) == Ok("<a xmlns=\"urn:x\" q=\"1 &lt; 2 & &quot;3&quot;\">&lt;&&gt;</a>")

assert decode(encode(a)!) == Ok({
        ..a,
        namespaces: [Namespace{prefix: "", uri: "urn:x"}],
    })

assert encode(Element.new("a b")) == Err(Error.Invalid{message: "\"a b\" is not an XML name"})
fn write(w: Writer, root: Element, options: WriteOptions = WriteOptions{}) -> Result<Unit, Error>

Writes the tree under root to w as encode writes it.

(written, data) = Writer.collect(fn w -> write(w, Element.new("a")))
assert written == Ok(Unit)
assert Bytes.to_string(data) == Ok("<a/>")