Xml

Reads, builds, transforms and writes XML documents. `Xml.read` (text), `Xml.open` (file) and `Xml.create` (empty) give a `Doc`. From a `Doc` you get `El` elements to read text and attributes, walk the tree and add content. Functions that take a namespace accept a plain URI (`urn:orders`) or a prefix and URI in one string separated by a comma and a space (`o, urn:orders`); elements are looked up by URI. Look-ups do not return `nil` for something that is not there: `child` of an unknown name returns an empty element that fails with a Java error as soon as you use it, so test with `#el.children("name")` first. Files are read and written in the JVM default charset (UTF-8 on current Java versions).

• Kind Library, a global in every script
• Category APIs & Data
• Functions 3

Objects

• Doc
• El

Functions

• create Doc Creates an empty document without a root element.
• open Doc Parses an XML file into a document.
• read Doc Parses XML text into a document.

create()

Xml.create()→Doc

Creates an empty document without a root element. Add the root with `Doc.element`, then build the tree with `El.element`, `El.attribute` and `El.text`.

Returns

Doc An XML document: get its root element, build it up, convert it to text, transform it with XSLT and write it to a file.

Example runs in CI

local doc = Xml.create()
local order = doc.element("order").attribute("id", "7")
order.element("item").text("Widget")
order.element("item").text("Gadget")
print(doc.toString())

open()

Xml.open(fileName: string)→Doc

Parses an XML file into a document. The file is read in the JVM default charset, whatever the XML declaration says. Throws `Failed to open XML file` when the file is missing or is not well-formed XML.

Parameters

fileName string

XML file to read, relative to the workspace

Returns

Doc An XML document: get its root element, build it up, convert it to text, transform it with XSLT and write it to a file.

Example runs in CI

Fl.write("orders.xml", "<orders><order id='1'/><order id='2'/></orders>")
local doc = Xml.open("orders.xml")
print(#doc.root().children("order"))

read()

Xml.read(input: string)→Doc

Parses XML text into a document. Throws `Failed to convert string to xml` when the text is empty or not well-formed.

Parameters

input string

Well-formed XML text

Returns

Doc An XML document: get its root element, build it up, convert it to text, transform it with XSLT and write it to a file.

Example runs in CI

local doc = Xml.read("<orders><order id='1'>Widget</order><order id='2'>Gadget</order></orders>")
local order = doc.root().child("order")
print(order.attributeValue("id"), order.value())