GOLF(2gg)

💖 GOLF(2gg) — xml-doc 💖

okay bestie, pull up a chair, we're doing the GOLF(2gg) manual page for xml-doc and honestly? it's giving parser excellence. no cap. 🦋

---

✨ NAME ✨

xml-doc — (XML-parsing)

🎯 PURPOSE 🎯

Parse XML text. that's it. that's the whole job. and it ate. 💅

📜 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 🌸

so xml-doc will parse XML <text> into the <xml> variable, and then you can hand that off to read-xml to actually get the data out. dynamic duo fr fr. 🫶

The length of <text> may be specified with the "length" clause in the <length> variable — or, if you don't bother, it will just be the string length of <text>. lowkey convenient. ✨

The "status" clause specifies the return <status> number, which is GG_OKAY if everything went off without a hitch, or GG_ERR_XML if there's an error in parsing. and when it is an error? the <error text> in the "error-text" clause is your error message. you can also get the error's line number (with number <line> in the clause "error-line") and the character position within that line (with number <char> in "error-char"). full receipts. 🔍

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

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. clean. ✂️

Golf uses the libxml2 library for XML parsing. shoutout. 👑

🗑️ DELETING 🗑️

To delete an XML variable, use the "delete" clause with the <xml>. This will delete all memory associated with it, and the variable <xml> itself. like, gone gone. not me cleaning up my resources. 💀

heads up bestie: delete takes the variable itself out too, so don't go using <xml> after that.

🧪 EXAMPLES 🧪

okay so this one's a whole moment. 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

---

and that's the whole page, bestie!! 🎀 this gem of a manual is from version $VERSION dated $DATE — GOLF(2gg) forever, mwah 💖✨