XML Module

You can use the XML module to read or write XML data. XML documents are represented as a DOM (Document Object Model) struture.

Examples

Reading an XML document

// Read an example document and extract information from it.

open XML;
open Seq;

let data = `<items>
                <item id="001">
                    <name>Apple (Cox Pomona)</name>
                </item>

                <item id="002">
                    <name>Apple (Ingrid Marie)</name>
                </item>

                <item id="003">
                    <name>Orange (Valencia)</name>
                </item>
            </items>`;

// Use the 'parse' function to turn the text into an XML DOM document.
let doc = parse(data);

// For each child element of the document root (i.e. for each <item> element),
// map that into a record containing the value of the "id" attribute
// and the value of the <name> child element.
return doc.root
          .getChildren()
          .map(e => {
            id: e.getNamedAttribute("id").value,
            name: e.getNamedChild("name").value 
           });
  
// The resulting FlowScript sequence will look like this:
// [
//    {
//        id: "001",
//        name: "Apple (Cox Pomona)"
//    },
//    {
//        id: "002",
//        name: "Apple (Ingrid Marie)"
//    },
//    {
//        id: "003",
//        name: "Orange (Valencia)"
//    }
// ] 

Creating an XML document

// Use the document, element and attribute functions to create an XML document.

open XML;

let xmlns = "http://www.w3.org/2000/xmlns/";
let myNamespace = "http://example.org/schema/my-schema.xsd";

let doc = document(
    element("Document",
        attribute(qualifiedName(xmlns, "test"), myNamespace),
        element("Messages",
            element("Message", "Hello world"),
            element("Message", "Good bye")
        ),
        element(qualifiedName(myNamespace, "Item"), "Namespaced")
    )
);

return print(doc);

// The resulting text will look like this:
//
// <Document xmlns:test="http://example.org/schema/my-schema.xsd">
//  <Messages>
//    <Message>Hello world</Message>
//    <Message>Good bye</Message>
//  </Messages>
//  <test:Item>Namespaced</test:Item>
// </Document>

Types

QName

Represents a qualified name with an optional namespace.

type QName = { namespace: text?, localName: text };

Attribute

Represents an XML attribute.

type Attribute = { type: 'attribute', name: QName, value: text };

Element

Represents an XML element.

type Element = {
    type: 'element',
    name: QName,
    attributes: Attribute*,
    value: text?
};

Document

Represents an XML document with a root element.

type Document = { root: Element };

Node

A union type representing different kinds of XML nodes.

type Node = Element | Attribute | text;

Functions

Functions for reading XML

parse(value: text) -> Document

Parses an XML string into a Document.

• value: The XML text to parse.

• Returns: A Document representing the parsed XML.

getDescendants(self el: Element) -> Element*

Returns all descendant elements of the given element, including itself.

• el: The element from which to start traversal.

• Returns: A sequence of all descendant elements.

getNamedChildren(self el: Element?, localName: text) -> Element*

Finds all direct child elements with the given local name.

• el: The parent element.

• localName: The name of the child elements to retrieve.

• Returns: A sequence of matching elements.

getNamedChild(self el: Element?, localName: text) -> Element?

Finds the first direct child element with the given local name.

• el: The parent element.

• localName: The name of the child element to retrieve.

• Returns: The first matching child element or null if none is found.

getNamedAttribute(self el: Element?, localName: text) -> Attribute?

Finds an attribute by its local name.

• el: The element to search in.

• localName: The name of the attribute.

• Returns: The matching attribute or null if not found.

getChildren(self el: Element?) -> Element*

Returns the direct children of an element.

• el: The parent element.

• Returns: A sequence of child elements.

Functions for creating XML

print(doc: Document) -> text

Serializes a Document into an XML string.

• doc: The document to serialize.

• Returns: The XML text representation of the document.

document(root: Element) -> Document

Creates a new XML document with the given root element.

• root: The root element.

• Returns: A Document.

element(name: text | QName, ...contents: Node*) -> Element

Creates an XML element with the given name and contents.

• name: The name of the element.

• contents: A sequence of child elements, attributes, and text nodes.

• Returns: An Element.

attribute(name: text | QName, value: text) -> Attribute

Creates an XML attribute with the given name and value.

• name: The name of the attribute.

• value: The value of the attribute.

• Returns: An Attribute.

qualifiedName(namespace: text?, localName: text) -> QName

Creates a qualified name with an optional namespace.

• namespace: (Optional) The namespace.

• localName: The local name.

• Returns: A QName.