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 (<, >, &, ', ") 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.
Exports
Section titled “Exports”xml.xml_namespace
Section titled “xml.xml_namespace”fn xml_namespace() -> String
The namespace the xml prefix is bound to in every document.
struct Name
Section titled “struct Name”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"
Name.to_string
Section titled “Name.to_string”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.
Name.equal
Section titled “Name.equal”impl Equatable for Name
fn equal(a: Name, b: Name) -> Bool
impl Equatable.equal
Name.inspect
Section titled “Name.inspect”impl Debug for Name
fn inspect(value: Name) -> String
impl Debug.inspect
struct Attribute
Section titled “struct Attribute”struct Attribute name: Name value: String end
An attribute: its name and its value, with entities and character references replaced.
Attribute.equal
Section titled “Attribute.equal”impl Equatable for Attribute
fn equal(a: Attribute, b: Attribute) -> Bool
impl Equatable.equal
Attribute.inspect
Section titled “Attribute.inspect”impl Debug for Attribute
fn inspect(value: Attribute) -> String
impl Debug.inspect
struct Namespace
Section titled “struct Namespace”struct Namespace prefix: String uri: String end
A namespace declaration on an element: xmlns:prefix="uri", or
xmlns="uri" when prefix is "".
Namespace.equal
Section titled “Namespace.equal”impl Equatable for Namespace
fn equal(a: Namespace, b: Namespace) -> Bool
impl Equatable.equal
Namespace.inspect
Section titled “Namespace.inspect”impl Debug for Namespace
fn inspect(value: Namespace) -> String
impl Debug.inspect
struct Element
Section titled “struct Element”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>")
Element.new
Section titled “Element.new”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")],
}
Element.elements
Section titled “Element.elements”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"]
Element.child
Section titled “Element.child”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
Element.children_named
Section titled “Element.children_named”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",
]
Element.child_text
Section titled “Element.child_text”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
Element.text
Section titled “Element.text”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"
Element.attribute
Section titled “Element.attribute”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
Element.equal
Section titled “Element.equal”impl Equatable for Element
fn equal(a: Element, b: Element) -> Bool
impl Equatable.equal
Element.inspect
Section titled “Element.inspect”impl Debug for Element
fn inspect(value: Element) -> String
impl Debug.inspect
enum Node
Section titled “enum Node”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.
Node.equal
Section titled “Node.equal”impl Equatable for Node
fn equal(a: Node, b: Node) -> Bool
impl Equatable.equal
Node.inspect
Section titled “Node.inspect”impl Debug for Node
fn inspect(value: Node) -> String
impl Debug.inspect
enum Token
Section titled “enum Token”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
-
StartA start tag, or the start of an empty-element tag
<a/>, which anEndfollows. -
DoctypeA DOCTYPE, with what follows
<!and before>, read only withallow_doctype.
Token.equal
Section titled “Token.equal”impl Equatable for Token
fn equal(a: Token, b: Token) -> Bool
impl Equatable.equal
Token.inspect
Section titled “Token.inspect”impl Debug for Token
fn inspect(value: Token) -> String
impl Debug.inspect
enum Error
Section titled “enum Error”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
-
SyntaxThe text is not well-formed XML, at
lineandcolumn, both from 1, the column in code points. -
IoThe
Readeror theWriterfailed. -
InvalidA 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>"
)
Error.to_string
Section titled “Error.to_string”impl Display for Error
fn to_string(error: Error) -> String
impl Display.to_string
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
xml.decode
Section titled “xml.decode”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,
})
xml.decode_bytes
Section titled “xml.decode_bytes”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"))
xml.read
Section titled “xml.read”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")]))
xml.tokens
Section titled “xml.tokens”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
Section titled “struct WriteOptions”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>
"""
)
WriteOptions.inspect
Section titled “WriteOptions.inspect”impl Debug for WriteOptions
fn inspect(value: WriteOptions) -> String
impl Debug.inspect
xml.encode
Section titled “xml.encode”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 < 2 & "3"\"><&></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"})
xml.write
Section titled “xml.write”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/>")