XML Parsing

Info

This how-to assumes you are familiar with setting up a project either manually or via VoltScript Dependency Management. If you are not, follow the Intro to VoltScript Tutorials.

Introduction

The main feature of XMLVSE is to load XML strings or files and convert them to an XML object for parsing. Once parsed, the XML object can now be modified using various XMLVSE functions.

VoltScript dependencies

Incorporating XMLVSE is straightforward. You just need to add the following JSON object to the vsesDependencies element in your atlas.json.

        "XmlVSE": {
            "library": "25893",
            "version": "1.0.0",
            "module": "25892/20856",
            "repository": "volt-mx-marketplace"
        }

You'll need to add to your repositories object in the atlas.json of your project:

        {
            "id": "volt-mx-marketplace",
            "type": "marketplace",
            "url": "https://community.demo-hclvoltmx.com/marketplace/asset"
        }

To use the extension in your script, enter UseVSE "*XMLVSE".

XMLParser class

The XMLParser class is used to generate an XML object from reading strings or a file content.

Parse XML strings

To parse an XML string, you need to pass it using the LoadFromXML() method:

Function parseXMLString(xml as String) as XMLObject

    Dim parser as New XMLParser()
    Call parser.loadFromXML(xml)
    Return parser.getRootXML

End Function

If the passed string is not valid XML, a 404 error is returned. The error message is Must supply a valid XML string.

Parse XML files

To parse an XML file, you need to pass it using the LoadFromFile() method:

Function parseXMLFile(fileName as String) as XMLObject

    Dim parser as New XMLParser()
    Call parser.loadFromFile(CurDir & "/" & fileName)
    Return parser.getRootXML

End Function

If the XML file isn't found at the specified path, a 404 error is returned. The error message is File could not be opened: followed by the provided path.

If the file does not contain valid XML, a 404 error is returned. The error message is XML file is not a valid XML.

Parse XML objects

The XMLObject class is used to hold the whole XML tree. You can traverse throughout the XML Tree by diving into a Child Element using GetChild() by providing the specific Tag or step back using GetParent().

You can also get all the child element in an array of XMLObject using GetChildren()

Sub Initialize

    Dim parser as New XMLParser
    DIm object as New XMLObject
    Dim helloWorld as String
    helloWorld = "<Profile version='1' publish='2024'><Employee>John Doe</Employee></Profile>"
    Call parser.loadFromXML(helloWorld)
    Set object = parser.getRootXML()

    DIm newObject as New XMLObject

    Set newObject =  object.getChild("Employee")
    Print newObject.toString("true")

    Set newObject =  object.getParent()
    Print newObject.toString("true")

    Dim arrayVals as Variant
    arrayVals =  object.getChildren()

    ForAll child in arrayVals         
    Set newObject = child
    Print newObject.Tag() & " - " & newObject.Value()
    End ForAll

End Sub

Warning

.GetChild() throws an error code 404, Child XML not found: if there is no child matching the passed label.

Verify and troubleshoot values

For both XMLParser and XMLObject, you can use ToString() to return the full XML object as a string. If the passed argument is True, a prettified or indented XML is printed. If the passed argument is False, a compact XML is printed.

You can also verify the XML existence within the XML Object using the IsEmpty checking.

The complete implementations of the code snippets are available on GitHub.