.. highlightlang:: us

.. index:: xml_simple

.. _xml_simple:

xml_simple
================

.. us.tag xml_simple NOTREADYENGLISH XML New5600

:ref:`xml_simple` converts a valid XML string into a UniScript object.

.. function:: o = xml_simple(ssXML)
    o = xml_simple(ssFilename)

.. us.return

**Return Value**

*o* is an XML tree or an Error object (see :ref:`error_create`). *o* contains the
elements *name* and the optional elements *attr*. The child elements are saved in
enumerated keys starting with 1.

::

    xml_simple("<a>1</a>")
    [.
        a = "1"
    ]
    xml_simple("<a b='1'><c>2</c></a>")
    [.
        a = [.
            b = "1"
            c = "2"
        ]
    ]
    xml_simple("<a><b>1</b><c>2</c></a>")
    [.
        a = [.
            b = "1"
            c = "2"
        ]
    ]

.. us.params

**Parameters**

.. uparam:: ssXML

   *ssXML* is a valid XML string. 

.. uparam:: ssFilename

   *ssFilename* is a valid file name. 

.. us.comment

**Comment**

The XML declaration at the beginning of the string will be ignored:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8" ?>

The input string *ssXML* must contain valid UNICODE characters. 
:ref:`text_file_read` returns for ANSI- and utf-8 coded text files UNICODE 
strings.

The :ref:`xml_simple` function loses the element order.

The call::

    xml_simple("<a><b>1</b><c>2</c></a>")

and the call::

    xml_simple("<a><c>2</c><b>1</b></a>")

both return the identical object::

    [.
        a = [.
            b = "1"
            c = "2"
        ]
    ]

If the order is important the function :ref:`xml_parse_string` can be used.

If an elment has child elements with identical names, the child elements
will be saved as an array::

    s = "[[<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <directory>
        <title>Example</title>
        <entry>
            <key>Test 1</key>
            <text>Test 1 ...</text>
        </entry>
        <entry a='Hallo'>
            <key>Test 2</key>
            <text>Test 2 ...</text>
        </entry>
    </directory>]]"

    o1 = xml_simple(s)
    [.
        directory = [.
            entry = [.
                [1] = [.
                    key = "Test 1"
                    text = "Test 1 ..."
                ]
                [2] = [.
                    key = "Test 2"
                    text = "Test 2 ..."
                ]
            ]
            title = "Example"
        ]
    ]

If an element has only one child element, the child element is save in the parent
element. No vector is created::

    s = "[[<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <directory>
        <title>Example</title>
        <entry>
            <key>Test 1</key>
            <text>Test 1 ...</text>
        </entry>
    </directory>]]"
    o2 = xml_simple(s)
    [.
        directory = [.
            entry = [.
                key = "Test 1"
                text = "Test 1 ..."
            ]
            title = "Example"
        ]
    ]

The ``xml_simple_get(element)`` function can be used to access the 
vector child elements, if it is not known if the element has 0, 1 or
more child elements. The elements in the return value can always be
accessed as a vector::

    entry = xml_simple_get(o2.directory.entry)  // or o1.directory.entry
    for (i in 1:entry.count_num) {
        print entry[i].text
    }

Another example::

    * xml_simple("<a b = '789'>456</a>")
    [.
        a = [.
            #text = "456"
            b = "789"
        ]
    ]

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2014
     - New.

.. seealso::
   :ref:`Overview-XML`,
   :ref:`text_file_read`,
   :ref:`xml_parse_string`

:sub:`id-1561986`