Element

An XML element: a name, attributes, and children.

An element has no link to a parent, so the same element can appear in several trees.

Attribute keys are local-name strings or (namespace_uri, local_name) tuples. Tuple namespaces are URIs, not prefixes. Serialization uses a prefix declared by namespaces on the element or an ancestor, and otherwise makes an element's namespace the default or generates a prefix.

Changes are checked as they are made, so any tree without a cycle can be serialized inside a document. Setting an invalid name, an empty namespace, or the xmlns namespace raises ValueError, as does adding text or an attribute value containing a character XML forbids.

Implements: Index[{*(Str | (Str, Str)): Str, *Node}], Assign[Str | (Str, Str), Str], Spread[Node]

Constructor

Element tag *items …

Creates an element, optionally with attributes and children.

Parameters

Name	Type	Description
tag	Str	Local element name.
:namespace?	Str	Namespace URI.
:namespaces?	BaseDict[Sym | Str, Str]	Initial namespaces, with Sym or Str keys.
:attrs?	BaseDict[Sym | Str | (Str, Str), Str]	Attributes; bareword keys name unnamespaced attributes.
*items	Node	Children in document order.

Errors

ValueError if a name, string, or namespace declaration is invalid, or two attributes have the same expanded name.

Example

let item = Element item namespace: "urn:inventory" namespaces: {inv: "urn:inventory"}
let disk = Element disk
  attrs:
    type: file
    device: disk
  - $ Element driver attrs: {name: "qemu", type: "qcow2"}

Fields

attrs @ MutMap[Str | (Str, Str), Str] ^[get]

Mutable map of attribute values by expanded name, in document order.

Keys are local-name strings or (namespace_uri, local_name) tuples. Setting an existing attribute keeps its position.

Example

node.attrs[("urn:inventory", "id")] = "123"
let id = node.attrs.get ("urn:inventory", "id")

children @ MutSeq[Node] ^[get]

Mutable array-like view of child values in document order.

Iterating a node iterates this view directly.

namespace @ (Str | nil) ^{[get, set]}

Mutable namespace URI, or nil for no namespace.

namespaces @ MutMap[Str, Str] ^[get]

Mutable map of the namespace declarations this element makes itself.

Keys are prefix strings; "" is the default namespace. Serialization declares these, uses them to spell names in this element's subtree, and adds whatever else those names need. Declarations choose prefixes, and are required for prefixes used in content, such as attribute values naming a qualified type. A parsed element holds the declarations written on it, not those it inherits.

Declaring a binding XML forbids, such as a prefix for an empty URI or another prefix for the XML namespace, raises ValueError.

tag @ Str ^{[get, set]}

Mutable local element name.

Methods

(assign) key value

Sets an attribute by string or namespace/name tuple, adding it if missing.

Parameters

Name	Type	Description
key	(Str | (Str, Str))
value	Str

(index)[K] key -> std.IndexItem[{*(Str | (Str, Str)): Str, *Node}, K] ^{overload 1 of 2}

Reads an attribute by string or namespace/name tuple, or a child by integer index.

Negative integer indexes count from the end.

Parameters

Name	Type	Description
key	K

(iter)() -> Iter[Node]

Iterates the children.

(spread)() -> Spread[Node]

Spreads the children positionally.

push child

Appends a child.

Parameters

Name	Type	Description
child	Node	Child value.

traverse() -> Iter[Node]

Returns a depth-first, parent-first iterator over this node and descendants.