Namespace and Class LrXml

Summary

Functions

LrXml.createXmlBuilder( omitDeclaration )

Creates an XML builder object (builderInstance) for constructing an XML document. Use the methods of the resulting object to create the document contents, and to serialize the resulting XML into a string.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. omitDeclaration

(Boolean). True to omit the XML declaration (<?xml version="1.0"?>) when this document is serialized to a string.

Return value

(builderInstance) A new XML builder object.

LrXml.parseXml( xmlString )

Parses a string containing valid XML to create and return a read-only XML DOM object (xmlDomInstance) which you can use to examine the XML content. The returned DOM object is the root of a tree of DOM objects for the XML nodes in the document. Use the xmlDomInstance functions to traverse the node tree.

The DOM object is an interface to a platform-specific XML parser. There can be variation in how whitespace, XML processing instructions, and other subtle aspects of XML are handled. Use caution when parsing XML. Do not assume elements are at a particular index. Instead, iterate child nodes and test by name and type to find a particular node. For example one parser might return a text node for the whitespace separating two elements, while another removes the whitespace; or one might skip comments while another includes them.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. xmlString

(string) A string containing XML.

Return value

(xmlDomInstance) A new XML DOM instance, the root node of the XML node tree.

builderInstance:append( otherXmlBuilder )

Appends all the XML in another builderInstance to this one at the current point.The other object must not have any unclosed blocks.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. otherXmlBuilder

(builderInstance) Another XML builder object.

builderInstance:beginBlock( name, attributes )

Adds an XML opening tag to this XML document. This must be closed later by a call to endBlock().

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. name

(string) The name of the tag.

2. attributes

(table, optional) A set of attribute names and values. The keys and values in this table are converted to strings using tostring().

builderInstance:comment( contents )

Appends an XML comment to this XML document.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. contents

(string) The text of the new XML comment.

builderInstance:endBlock()

Adds an XML closing tag to this XML document. This must be balance a preceding call to beginBlock().

First supported in version 1.3 of the Lightroom SDK.

builderInstance:serialize()

Retrieves the complete XML document as a string.

First supported in version 1.3 of the Lightroom SDK.

Return value

(string) The serialized XML document.

builderInstance:tag( name, value, attributes )

Adds a single tag to this XML document, with an optional text child node.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. name

(string) The name of the new XML element.

2. value

(string, optional) The text content of the new element.

3. attributes

(table, optional) A set of attribute names and values. The keys and values in this table are converted to strings using tostring().

builderInstance:text( value )

Adds a text node to this XML document.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. value

(string) The text content of the new element.

xmlDomInstance:attributes()

Retrieves the attributes of this element node.

First supported in version 1.3 of the Lightroom SDK.

Return value

(table) The attributes as a table, keyed by attribute name. Each entry is itself a table containing keys for "value", "namespace", and "name". If this is not an element node, returns nil.

xmlDomInstance:childAtIndex( index )

Retrieves a child of this element node by index.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. index

Return value

(xmlDomInstance)The child node, or nil if this is not an element node.

xmlDomInstance:childCount()

Reports the number of children of this element node.

First supported in version 1.3 of the Lightroom SDK.

Return value

(number) The number of children, or nil if this node is not an element node.

xmlDomInstance:name()

Retrieves the name of the xml node from this XML document.

First supported in version 1.3 of the Lightroom SDK.

Return values

1. (string) The name of the xml node.
2. (string) The namespace of the xml node.

xmlDomInstance:serialize()

Converts the XML encapsulated by this object into its string representation. The result does not include an XML declaration.

First supported in version 1.3 of the Lightroom SDK.

Return value

(string) The XML as a string.

xmlDomInstance:text()

Retrieves the text of the xml node from this XML document.

First supported in version 3.0 of the Lightroom SDK.

Return value

(string) The text of the xml node.

xmlDomInstance:transform( xsltString )

Transforms this XML into string output by applying an XSLT transformation.

Depending on the operating system, the result of the transform can contain different amounts and/or kinds of whitespace. To normalize the result, apply a substitution pattern such as this: string.gsub( result, "[\r\n ]+", " " ) This must be called on the root node.

Note: The error messages from this function can be misleading. If you see the message "out of memory", you may want to review the application or OS console for other messages that may be more helpful.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. xsltString

(string): A valid XSLT style sheet, as a string.

Return value

(string) The output of the XSLT transformation.

xmlDomInstance:type()

Retrieves the type of the xml node from this XML document.

First supported in version 1.3 of the Lightroom SDK.

Return value

(string) The node type, one of "element", "text", "comment", "processinginstruction"