Xml Module

xml.parse

xml.parse(stream) xml.parse(stream, haltOnError)

Parses an already-opened file or a string. See xml.open if you want the file to be opened for you, as well. If 'haltOnError' is not specified, it is assumed to be true.

If an error occurs, this function will return nil as the first argument followed by the error message, line, column number, and character position. Otherwise, it will return the root XML node.

Example:

-- Parse a string
local xmlString = "<root><tag>Testing</tag></root>";
local root, err = xml.parse(xmlString);

if( root == nil ) then
  printf("Oh no! An error occured: %s\n", err);
end

-- Or, parse an XML file we already have opened:
local file = io.open("file.xml");
local root, err = xml.parse(file);
file:close();

if( root == nil ) then
  printf("Oh no! An error occured: %s\n", err);
end

xml.open

xml.open(filename)

Opens and parses an XML file, and returns a class containing the root node. If 'haltOnError' is not specified, it is assumed to be true.

If an error occurs, this function will return nil as the first argument followed by the error message, line, column number, and character position. Otherwise, it will return the root XML node.

Example:

<root name="Root" type="Example">
	<elem1>
		<subelement value="1" />
		<subelement value="2" />
		<subelement value="3" />
	</elem1>

	<elem2 number="1234" string="This is a string" />

	<elem3>Element 3 has a text value</elem3>

	<elem4 num="123">999</elem4>
</root>

function main()
  local root = xml.open(getExecutionPath() .. "/test.xml");
  printf("root._NAME: %s\n", root:getName()); -- "_NAME" should be 'root'
  printf("root.name: %s\n", root:getAttribute("name"));    -- "name" will be set in XML
  printf("root.attribute count: %d\n", root:getAttributeCount());

  local elem1 = root:getElement("elem1");
  elements = elem1:getElements();
  printf("\n---ELEM1---\n");
  for i,v in pairs(elements) do
    local name = v:getName();
    local value = v:getAttribute("value");
    printf(" ==> [%s]: %s\n", name, value);
  end


  local elem2 = root:getElement("elem2");
  printf("\n---ELEM2---\n");
  printf("elem2.number: %d\n", elem2:getAttribute("number"));
  printf("elem2.string: %s\n", elem2:getAttribute("string"));

  local elem3 = root:getElement("elem3");
  printf("\n---ELEM3---\n");
  printf("elem3._VALUE: %s\n", elem3:getValue());

  local elem4 = root:getElement("elem4");
  printf("\n---ELEM4---\n");
  local val = elem4:getValue();
  local num = elem4:getAttribute("num");

  if( num == nil ) then
    printf("num is nil\n");
  end

  printf("elem4.num(type): %s\n", type(num));
  printf("elem4.num: %d\n", num);

  printf("elem4._VALUE(type): %s\n", type(val));
  printf("elem4._VALUE: %d\n", val);
end
startMacro(main);

XML Node class

Note: Several XML node member functions have a second optional argument that allows you to specify a return type. This should be used to ensure that the value you are retrieving is casted to the type you want. If you use this optional argument, 'type' should be a string of one of the following: "string", "number", or "boolean".

Node:getElement(name) Node:getElement(name, type)

Node:getElement(index) Node:getElement(index, type)

Return an element (node) inside this node with the name 'name' or index 'index'.

Node:getElements()

Returns all elements (nodes) inside this node.

Node:getElementCount()

Returns the number of elements (nodes) inside this node.

Node:getAttribute(name) Node:getAttribute(name, type)

Node:getAttribute(index) Node::getAttribute(index, type)

Returns an attribute for this node with the name 'name' or index 'index'.

Node:getAttributes()

Returns all attributes for this node.

Node:getAttributeCount()

Returns the number of attributes for this node.

Node:getName()

Returns the name of this node.

Node:getValue() Node:getValue(type)

Returns the value of this node.