ContentsOverview
The XML actions allow you to efficiently and effectively work with any valid XML (Extensible Markup Language) file.
We've made the XML actions extremely powerful, yet remarkably easy to use. Using an innovative XML referencing scheme which we've named "XML Paths," these actions make reading, writing and manipulating XML files simple and straightforward.
If you need to work with XML data, these actions are for you.
Many of the XML actions contain a parameter called XMLPath. This path is used to locate a specific element in the XML file. For example, in the sample XML document, the "address" element inside the first "customer" element can be accessed using:
database/customer/address_info/address
Since an XML document can contain multiple elements with the same name, you often cannot access every element in a document by name alone. For example, what if you need to access the information in the second customer element?
The secret is to add an optional index to each element name in order to specify which occurrence of that name the path refers to. In XML paths, an index consists of a single colon (:) followed by a number. (If no index is specified, the index is assumed to be 1.)
For example, to access the second "customer" element in the first "database" element of the sample XML document, you could use:
database/customer:2
As another example, to access the second "phone" element in the second "customer" element, you would use:
database/customer:2/phone:2
An asterisk (*) can be used in an XML path to find the first matching element at a given level.
For example, you can use paths like this:
*/customer
...which refers to the first customer element in the first root element, no matter what the root element is named. In other words, the above path wouldn't care whether the root element was "database" or "moonbase_alpha."
You can use an asterisk with an index to refer to an element by position instead of by name. For example, you could use the following path to access the second element inside the customer element, no matter what that element is named:
database/customer/*:2
Using the above path, it wouldn't matter what the first two elements inside customer were named; they could be "first_name" and "last_name" or they could be "nose_length" and "hair_color"...either way, it would be the second element that would be referenced.
You can even form a path with nothing but asterisks. For example, the following path would refer to the third child element within the second root element:
*:2/*:3
Note: An asterisk always matches a single element. It doesn't match "all" elements at that level.
If you need to, you can change the index delimiter from ':' to something else by assigning a different value to the special Lua variable XML.Delimiter. For example, if your XML document has element names with ':' characters in them, you could change the delimiter to '|' instead by using this script:
XML.Delimiter = "|";
...after which you would specify paths like this:
database/customer|2/phone|2
Note: Most of the examples assume the following XML to be already loaded into memory. To test the examples you can save the text below as an .xml file and then use an XML.Load action to load it into memory.
<database>
<customer id="1010" product="AutoPlay">
<first_name>John</first_name>
<last_name>Smith</last_name>
<company>Indigo Rose</company>
<address_info>
<address>100 Mystreet</address>
<city>Winnipeg</city>
<province>Manitoba</province>
<country>Canada</country>
<postal_code>R3B 0R3</postal_code>
</address_info>
<phone location="daytime">(204)946-0263</phone>
<phone location="evening">(204)946-0242</phone>
<fax>(204)942-3421</fax>
<email>[email protected]</email>
</customer>
<customer id="1040" product="Setup Factory">
<first_name>Sara</first_name>
<last_name>Winters</last_name>
<company>Indigo Rose</company>
<address_info>
<address>200 Secondstreet</address>
<city>Winnipeg</city>
<province>Manitoba</province>
<country>Canada</country>
<postal_code>R3B 0R4</postal_code>
</address_info>
<phone location="daytime">(204)946-0244</phone>
<phone location="evening">(204)946-0289</phone>
<fax>(204)942-3422</fax>
<email>[email protected]</email>
</customer>
</database>
The following XML actions are available:
XML.Count
XML.GetAttribute
XML.GetAttributeNames
XML.GetElementNames
XML.GetElementXML
XML.GetValue
XML.GetXML
XML.InsertXML
XML.Load
XML.RemoveAttribute
XML.RemoveElement
XML.Save
XML.SetAttribute
XML.SetValue
XML.SetXML