GOLF(2gg)

NAME
xml-doc - (XML-parsing)

PURPOSE
Parse XML text.

SYNTAX

        xml-doc <text> to <xml> \
            [ status <status> ] [ length <length> ] \
            [ error-text <error text> ] \
                [ error-line <line> ] \
                [ error-char <char> ]

        xml-doc delete <xml>

DESCRIPTION
xml-doc will parse XML <text> into <xml> variable, which can be used with read-xml to get the data.

The length of <text> may be specified with "length" clause in <length> variable, or if not, it will be the string length of <text>.

The "status" clause specifies the return <status> number, which is GG_OKAY if successful or GG_ERR_XML if there is an error in parsing, in which case <error text> in "error-text" clause is the error message. You can also obtain the error's line number (with number <line> in clause "error-line") and the character position within that line (with number <char> in clause "error-char").

The maximum depth of nested elements in XML document is 32, and the maximum length of a normalized element name is 500 (see read-xml for more on normalized names).

An XML element that is comprised of multiple anonymous sub-elements is presented as a concatenated single element; this is likely how most applications expect to see such data. All data is trimmed for whitespace on left and right.

Golf uses libxml2 library for XML parsing.

DELETING

To delete an XML variable, use "delete" clause with the <xml>. This will delete all memory associated with it, and the variable <xml> itself.

EXAMPLES
Parse the following XML document and display all element names and values from it. You can use them as they come along, or store them into new-hash or new-tree for instance for searching of large documents. This also demonstrates usage of UTF characters:

        %% /xml public
            set-string xmld unquoted =<?xml version="1.0" encoding="UTF-8"?>\
        <countries>\
            <country id='1'>\
                <name>USA&amp;America</name>\
                <state id='1'>Arizona\
                    <city id="1">\
                        <name>Phoenix</name>\
                        <population>5000000</population>\
                    </city>\
                    <city id="2">\
                        <name>Tuscon</name>\
                        <population>1000000</population>\
                    </city>\
                </state>\
                <state id='2'>California\
                    <city id="1">\
                        <name>Los Angeles</name>\
                        <population>19000000</population>\
                    </city>\
                    <city id="2">\
                        <name>Irvine</name>\
                    </city>\
                </state>\
            </country>\
            <country id='2'>\
                <name>Mexico</name>\
                <state id='1'>Veracruz\
                    <city id="1">\
                        <name>Xalapa-Enriquez</name>\
                        <population>8000000</population>\
                    </city>\
                    <city id="2">\
                        <name>C\u00F3rdoba</name>\
                        <population>220000</population>\
                    </city>\
                </state>\
                <state id='2'>Sinaloa\
                    <city id="1">\
                        <name>Culiac\u00E1n Rosales</name>\
                        <population>3000000</population>\
                    </city>\
                </state>\
            </country>\
        </countries>

            xml-doc xmld to x
            start-loop
                read-xml x key k value v status s next
                if-true s equal GG_ERR_EXIST
                    break-loop
                end-if
                text-utf v
                @Key [<<print-out k>>] Value [<<print-out v>>]
            end-loop
            xml-doc delete x
        %%

The output would be:

        Key [countries/country/id/@] Value [1]
        Key [countries/country/name/] Value [USA&America]
        Key [countries/country/state/id/@] Value [1]
        Key [countries/country/state/city/id/@] Value [1]
        Key [countries/country/state/city/name/] Value [Phoenix]
        Key [countries/country/state/city/population/] Value [5000000]
        Key [countries/country/state/city/id/@] Value [2]
        Key [countries/country/state/city/name/] Value [Tuscon]
        Key [countries/country/state/city/population/] Value [1000000]
        Key [countries/country/state/] Value [Arizona]
        Key [countries/country/state/id/@] Value [2]
        Key [countries/country/state/city/id/@] Value [1]
        Key [countries/country/state/city/name/] Value [Los Angeles]
        Key [countries/country/state/city/population/] Value [19000000]
        Key [countries/country/state/city/id/@] Value [2]
        Key [countries/country/state/city/name/] Value [Irvine]
        Key [countries/country/state/] Value [California]
        Key [countries/country/id/@] Value [2]
        Key [countries/country/name/] Value [Mexico]
        Key [countries/country/state/id/@] Value [1]
        Key [countries/country/state/city/id/@] Value [1]
        Key [countries/country/state/city/name/] Value [Xalapa-Enriquez]
        Key [countries/country/state/city/population/] Value [8000000]
        Key [countries/country/state/city/id/@] Value [2]
        Key [countries/country/state/city/name/] Value [Córdoba]
        Key [countries/country/state/city/population/] Value [220000]
        Key [countries/country/state/] Value [Veracruz]
        Key [countries/country/state/id/@] Value [2]
        Key [countries/country/state/city/id/@] Value [1]
        Key [countries/country/state/city/name/] Value [Culiacán Rosales]
        Key [countries/country/state/city/population/] Value [3000000]
        Key [countries/country/state/] Value [Sinaloa]

SEE ALSO
 XML parsing

read-xml xml-doc See all documentation