El

object

An XML element: read its text and attributes, move to its children and parent, and add or remove content. Editing functions that return the element itself (`text`, `attribute`, `namespace`, `detach`) can be chained. Namespace arguments are a URI or a prefix and URI in one string (`o, urn:orders`).

Kind Object
Library Xml
Category APIs & Data
Functions 12

How to get one

local doc = Xml.create()
local el = doc.root()

Returned by

Functions

root El Returns the element you started from with `Doc.root` or `Doc.element`, the top of this tree.
up El Returns the parent element, so you can step back after `child`, `children` or `element`.
string string Returns this element and everything below it as compact XML text (no indentation).
value string Returns the text of the element: its own text and that of all elements below it, without tags.
attributeValue string Returns the value of an attribute.
child El Returns the first child element with the given name.
children El[] Returns the child elements as a list, in document order: all children, or only those with the given name.
element El Creates a new element, appends it as the last child of this element and returns it, so `text` and `attribute` can be chained on it.
text self Appends text to the element, after any text and children it already has.
attribute self Sets an attribute, replacing an attribute with the same name.
namespace self Declares a namespace on the element (an `xmlns` attribute).
detach self Removes the element from its parent.

`root()`

el.root()→El

Returns the element you started from with `Doc.root` or `Doc.element`, the top of this tree.

Returns

El An XML element: read its text and attributes, move to its children and parent, and add or remove content.

`up()`

el.up()→Elel.up(amount: number)→El

Returns the parent element, so you can step back after `child`, `children` or `element`. Only elements reached through those functions know their parent: on the element from `Doc.root` or `Doc.element` (the top of the tree) `up()` returns nil. With a number the call climbs that many levels (`up(2)` is `up().up()`) and throws `Can't get upper element` when the top is reached before that. The number must be above 0.

Parameters

amount number optional: Number of levels to climb, above 0 (see description)

Returns

El An XML element: read its text and attributes, move to its children and parent, and add or remove content.

`string()`

el.string()→string

Returns this element and everything below it as compact XML text (no indentation).

Returns

string The XML text of the element

`value()`

el.value()→string

Returns the text of the element: its own text and that of all elements below it, without tags.

Returns

string The concatenated text content

`attributeValue()`

el.attributeValue(name: string)→stringel.attributeValue(name: string, ns: string)→string

Returns the value of an attribute. An attribute that is not there gives an empty string, so a missing attribute cannot be told apart from an empty one.

Parameters

name string: Attribute name
ns string optional: Namespace of the attribute: a URI, or `prefix, uri`

Returns

string The attribute value, or an empty string when absent

`child()`

el.child(child: string)→Elel.child(child: string, ns: string)→El

Returns the first child element with the given name. Without a namespace argument only children that are in no namespace match; give the namespace for namespaced children. Returns nil when there is no such child, so an optional child can be tested with `if child then`.

Parameters

child string: Name of the child element
ns string optional: Namespace of the child: a URI, or `prefix, uri`

Returns

El An XML element: read its text and attributes, move to its children and parent, and add or remove content.

Example runs in CI

local doc = Xml.read("<order><customer>Alice</customer><item>Widget</item></order>")
local order = doc.root()
print(order.child("customer").value())
print(#order.children("discount"))

`children()`

el.children()→El[]el.children(child: string)→El[]el.children(child: string, ns: string)→El[]

Returns the child elements as a list, in document order: all children, or only those with the given name. The list is empty when there are none. Without a namespace argument only children that are in no namespace match; pass the namespace to find namespaced children.

Parameters

child string optional: Name of the child elements
ns string optional: Namespace of the children: a URI, or `prefix, uri`

Returns

El[] An XML element: read its text and attributes, move to its children and parent, and add or remove content.

Example runs in CI

local doc = Xml.read("<orders><order id='1'>A</order><order id='2'>B</order></orders>")
for _, order in ipairs(doc.root().children("order")) do
    print(order.attributeValue("id"), order.value())
end

`element()`

el.element(name: string)→Elel.element(name: string, ns: string)→Elel.element(name: string, prefix: string, uri: string)→El

Creates a new element, appends it as the last child of this element and returns it, so `text` and `attribute` can be chained on it. Use `up` to come back to this element. A single namespace argument is a URI or `prefix, uri`; the prefix and URI can also be passed as two arguments.

Parameters

name string: Name of the new element
prefix string: Namespace prefix
uri string: Namespace URI
ns string: Namespace of the element: a URI, or `prefix, uri`

Returns

El An XML element: read its text and attributes, move to its children and parent, and add or remove content.

`text()`

el.text(content: string)→self

Appends text to the element, after any text and children it already has. The text is escaped.

Parameters

content string: Text to append

Returns

self chainable The el itself, so calls can be chained.

`attribute()`

el.attribute(name: string, value: string)→selfel.attribute(name: string, value: string, uri: string)→self

Sets an attribute, replacing an attribute with the same name. With a namespace the attribute is put in that namespace: pass `prefix, uri`, or just a URI, in which case a prefix that is already declared for the URI is used, or a new one (`ns1`, `ns2`, ...).

Parameters

name string: Name of the attribute
value string: Value of the attribute
uri string optional: Namespace of the attribute: a URI, or `prefix, uri`

Returns

self chainable The el itself, so calls can be chained.

`namespace()`

el.namespace(ns: string)→selfel.namespace(prefix: string, uri: string)→self

Declares a namespace on the element (an `xmlns` attribute). With one argument, a URI declares the default namespace and `prefix, uri` a prefixed one; with two arguments the prefix and URI are given separately. The declaration does not move the element itself into the namespace.

Parameters

prefix string: Namespace prefix
uri string: Namespace URI
ns string: Namespace to declare: a URI, or `prefix, uri`

Returns

self chainable The el itself, so calls can be chained.

`detach()`

el.detach()→self

Removes the element from its parent. The detached element is returned and can still be read or added elsewhere.

Returns

self chainable The el itself, so calls can be chained.