`std/xml/node`

std/xml/src/node.trb

The tree of an XML document, XmlNode, with the pieces it is made of: a qualified name, an attribute and the XML declaration.

type XmlName

type XmlName with Show, Equals, Hash

A name in the sense of Namespaces in XML: the local part, the prefix it was written with and the namespace the prefix stood for where it was read.

Two names are the same name when their namespace and local part are equal, but the tree keeps the prefix too, so that a document is written back the way it was written. A name that has no prefix has the default namespace of its place, if there is one; an attribute without a prefix has no namespace at all.

Examples

const name = XmlName local: "Contents", namespace: "urn:example:bucket"
print name.qualified()

field local

local: String

The part after the colon, or the whole name where there is no colon.

field prefix

prefix: String? = None

The prefix the name was written with, None where it was written without one.

field namespace

namespace: String? = None

The namespace the name belongs to, None for a name in no namespace.

fn qualified

fn qualified(): String

The name as it is written: prefix:local, or local where there is no prefix.

fn isNamed

fn isNamed(local: String, namespace: String? = None): Bool

Whether this is the name local in the namespace namespace, whatever prefix either was written with.

fn show

fn show(): String

The qualified name.

type XmlAttribute

type XmlAttribute with Show, Equals, Hash

One attribute of an element, in the order the document wrote it. A declaration of a namespace, xmlns="uri" or xmlns:prefix="uri", is an attribute too: its name is in the namespace http://www.w3.org/2000/xmlns/.

field name

name: XmlName

The name of the attribute, with its namespace: none for a name without a prefix.

field value

value: String

The value with its references resolved and its white space normalised, as XML 1.0 section 3.3.3 says.

type XmlDeclaration

type XmlDeclaration with Show, Equals, Hash

What the XML declaration at the start of a document says: <?xml version="1.0" encoding="UTF-8"?>.

field version

version: String = "1.0"

The version of XML: always 1.0, the only one this package reads.

field encoding

encoding: String? = None

The encoding the document says it is in, None where it says nothing. A String is read as it is.

field standalone

standalone: Bool? = None

The standalone pseudo-attribute: Some(true) for yes, Some(false) for no, None where it is left out.

type XmlNode

type XmlNode with Show, Equals, Hash

One node of an XML document, as a tree: the document, an element, a run of text, a CDATA section, a comment, a processing instruction or the document type declaration.

The tree keeps what a document says and what a writer needs to say it again: the order of the attributes and children, the prefixes, comments, processing instructions and CDATA sections. It does not keep how a character was written (A and A are one text), the quotes of an attribute, the white space inside a tag or the white space between the nodes of the prolog and of the epilog.

Examples

use Xml from "std/xml"

const tree = Xml().parse("<point x=\"1\" y=\"2\"/>")?
print tree.root()?.attribute("y")

case Document

case Document(declaration: XmlDeclaration?, children: List<Self>)

A whole document: its declaration, if it has one, and its children in order - comments, processing instructions, the document type declaration and the one root element.

case Doctype

case Doctype(name: String, publicId: String?, systemId: String?)

The document type declaration, <!DOCTYPE name PUBLIC "public" "system">. Its external identifier is never read.

case Element

case Element(name: XmlName, attributes: List<XmlAttribute>, children: List<Self>)

An element with its attributes and children in document order.

case Text

case Text(value: String)

A run of text with its references resolved. The reader never makes two texts in a row.

case CData

case CData(value: String)

A CDATA section: text that was written without escapes, kept apart from the text around it.

case Comment

case Comment(value: String)

A comment without its .

case Instruction

case Instruction(target: String, data: String)

A processing instruction: its target and the data after the white space that follows the target.

fn declaration

fn declaration(): XmlDeclaration?

The declaration when this is a document that starts with one.

fn isElement

fn isElement(): Bool

true for an element.

fn name

fn name(): XmlName?

The name when this is an element.

fn attributes

fn attributes(): List<XmlAttribute>

The attributes of an element, in document order, and an empty list for every other node.

fn children

fn children(): List<Self>

The children of a document or an element in document order, and an empty list for every other node.

fn elements

fn elements(): List<Self>

The children that are elements.

fn root

fn root(): Self?

The root element of a document.

fn child

fn child(local: String): Self?

The first child element whose local name is local, whatever its namespace.

fn childrenNamed

fn childrenNamed(local: String): List<Self>

The child elements whose local name is local, whatever their namespace.

fn attribute

fn attribute(local: String): String?

The value of the attribute of an element with the local name local and no namespace.

fn text

fn text(): String

The text of this node: what a text, a CDATA section, or the descendants of an element or document, hold, joined.