# 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

```typescript
// 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

```typescript
// 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.

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

#### `Attribute`

Represents an XML attribute.

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

#### `Element`

Represents an XML element.

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

#### `Document`

Represents an XML document with a root element.

```typescript
type Document = { root: Element };
```

#### `Node`

A union type representing different kinds of XML nodes.

```typescript
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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.novacura.com/flow-connect/reference/reference/flowscript/walkthrough/xml-module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.