XML Interface

Introduction

When working with XML documents, Creo Elements/Direct Modeling maintains an representation of the documents on the C++ level. The functions below provide an interface to read and manipulate these documents.

Note that the objects are not automatically garbage-collected. It is recommended to call the function sd-xml-clear-cache after processing of the XML document is done.

Example

Detailed example Lisp code about reading, writing and processing XML can be found here.

Functions

Read / Write XML files

• sd-xml-read-file
• sd-xml-write-file
• sd-xml-get-root-name
• sd-xml-serialize
• sd-xml-deserialize

Processing XML documents

• sd-xml-create-document
• sd-xml-document-get-root
• sd-xml-document-set-root
• sd-xml-document-select-element

Processing XML elements

• sd-xml-create-element
• sd-xml-element-get-name
• sd-xml-element-get-children
• sd-xml-element-get-named-children
• sd-xml-element-get-named-child
• sd-xml-element-add-child
• sd-xml-element-get-text
• sd-xml-element-set-text
• sd-xml-element-get-attributes
• sd-xml-element-get-attribute
• sd-xml-element-set-attribute
• sd-xml-element-get-parent
• sd-xml-element-get-document

Miscelleanous

• sd-xml-transform-file
• sd-xml-clear-cache

SD-XML-READ-FILE  [function]

(sd-xml-read-file filename)

Description:

Reads an XML document from a file.

Parameters:

filename {STRING} - the name of the file to read

Return Value:

document {XML DOCUMENT} - reference to the XML document

nil - failure

Example:

(setf my-xml-document (sd-xml-read-file "d:/temp/document.xml"))
  

SD-XML-WRITE-FILE  [function]

(sd-xml-write-file document filename :pretty-print pretty-print :encoding encoding)

Description:

Writes an XML document to a file.

Parameters:

document {XML DOCUMENT} - reference to the XML document

filename {STRING} - name of the file to write

:pretty-print {BOOLEAN [t]} - optional parameter to write formatted output with line breaks and indentation

:encoding {STRING ["UTF-8"]} - optional parameter to specify the encoding

legal values are "UTF-8" and "UTF-16"

Return Value:

t - success

nil - failure

Example:

(setf result (sd-xml-write-file my-xml-document "d:/temp/document.xml"))
  

SD-XML-GET-ROOT-NAME  [function]

(sd-xml-get-root-name filename)

Description:

Reads only the root name of an XML document in a file. Reading only the root name is much more efficient than reading whole document and inquiring then the name of the root element. This function might be very useful if specific handlers are registered for xml files with certain root name.

Parameters:

filename {STRING} - the name of the file to read

Return Value:

name {STRING} - the root name

Example:

(setf root-name (sd-xml-get-root-name "d:/temp/document.xml"))
=> "root"
  

SD-XML-SERIALIZE  [function]

(sd-xml-serialize document)

Description:

Serializes an XML document into a string.

Parameters:

document {XML DOCUMENT} - reference to the XML document

Return Value:

content {STRING} - the document content as a string

Example:

(setf content (sd-xml-serialize my-xml-document))
=> "<root><element1/></root>"
  

SD-XML-DESERIALIZE  [function]

(sd-xml-deserialize content)

Description:

Creates an XML document from a string.

Parameters:

content {STRING} - the document content as a string

Return Value:

document {XML DOCUMENT} - an XML document

Example:

(setf my-xml-document (sd-xml-deserialize "<root><element1/></root>"))
  

SD-XML-CREATE-DOCUMENT  [function]

(sd-xml-create-document)

Description:

Creates a new document object in memory.

Return Value:

document {XML DOCUMENT} - pointer to the XML document

Example:

(setf my-xml-document (sd-xml-create-document))
  

SD-XML-DOCUMENT-GET-ROOT  [function]

(sd-xml-document-get-root document)

Description:

Gets the root element of the document.

Parameters:

document {XML DOCUMENT} - reference to the XML document

Return Value:

element {XML ELEMENT} - the root XML element

Example:

(setf root-element (sd-xml-document-get-root my-xml-document))
  

SD-XML-DOCUMENT-SET-ROOT  [function]

(sd-xml-document-set-root document element)

Description:

Sets the root element of the document.

Parameters:

document {XML DOCUMENT} - reference to the XML document

element {XML ELEMENT} - the new root XML element

Return Value:

element {XML ELEMENT} - the root element

Example:

(setf root-element (sd-xml-document-set-root my-xml-document element))
  

SD-XML-DOCUMENT-SELECT-ELEMENT  [function]

(sd-xml-document-select-element document xpath)

Description:

Gets a document element by its XPath.

Parameters:

document {XML DOCUMENT} - reference to the XML document

xpath {STRING} - the XPath of the element, might be single element path or element which has a certain attribute of specific value

Return Value:

element {XML ELEMENT} - the selected element

Example:

(setf element (sd-xml-document-select-element my-xml-document "/root/element1"))
(setf element (sd-xml-document-select-element my-xml-document "/root/element1[@key1='value1']"))
  

SD-XML-CREATE-ELEMENT  [function]

(sd-xml-create-element document name)

Description:

Creates a new XML element with specified name.

Parameters:

document {XML DOCUMENT} - reference to the XML document

name {STRING} - name of the element

Return Value:

element {XML ELEMENT} - the created XML element

Example:

(setf my-xml-element (sd-xml-create-element my-xml-document "element1"))
  

SD-XML-ELEMENT-GET-NAME  [function]

(sd-xml-element-get-name element)

Description:

Gets the name of an XML element.

Parameters:

element {XML ELEMENT} - the element to inquire the name from

Return Value:

name {STRING} - the element name

Example:

(setf element-name (sd-xml-element-get-name my-xml-element))
=> "element1"
  

SD-XML-ELEMENT-GET-CHILDREN  [function]

(sd-xml-element-get-children element)

Description:

Gets all children of the element.

Parameters:

element {XML ELEMENT} - the element to inquire

Return Value:

children {List of XML ELEMENTs} - a list of child elements

Example:

(setf element-children (sd-xml-element-get-children my-xml-element))
  

SD-XML-ELEMENT-GET-NAMED-CHILDREN  [function]

(sd-xml-element-get-named-children element name)

Description:

Gets all children of the element with a given name.

Parameters:

element {XML ELEMENT} - the element to inquire

name {STRING} - the name of the children to inquire

Return Value:

children {List of XML ELEMENTs} - a list of child elements with specified name

Example:

(setf element-children (sd-xml-element-get-named-children my-xml-element "element2"))
  

SD-XML-ELEMENT-GET-NAMED-CHILD  [function]

(sd-xml-element-get-named-child element name)

Description:

Gets the first child of the element with a given name. It is basically the same function like sd-xml-element-get-named-children. Only the first child element is returned.

Parameters:

element {XML ELEMENT} - the element to inquire

name {STRING} - the name of the child to inquire

Return Value:

element {XML ELEMENT} - the first child element with this name

Example:

(setf element-child (sd-xml-element-get-named-child my-xml-element "element2"))
  

SD-XML-ELEMENT-ADD-CHILD  [function]

(sd-xml-element-add-child parent-element child-element)

Description:

Adds a child XML element to a given parent XML element.

Parameters:

parent-element {XML ELEMENT}

child-element {XML ELEMENT}

Return Value:

t - success

nil - failure

Example:

(setf result (sd-xml-element-add-child my-xml-element child-element))
  

SD-XML-ELEMENT-GET-TEXT  [function]

(sd-xml-element-get-text element)

Description:

Gets the text content of an XML element.

Parameters:

element {XML ELEMENT} - the element to inquire

Return Value:

content {STRING} - the text content

Example:

(setf text (sd-xml-element-get-text my-xml-element))
=> "XML element value"
  

SD-XML-ELEMENT-SET-TEXT  [function]

(sd-xml-element-set-text element text)

Description:

Sets the text content of an XML element.

Parameters:

element {XML ELEMENT} - the element to change the content

text {STRING} - the new text content

Return Value:

t - success

nil - failure

Example:

(setf result (sd-xml-element-set-text my-xml-element "XML element value"))
  

SD-XML-ELEMENT-GET-ATTRIBUTES  [function]

(sd-xml-element-get-attributes element)

Description:

Gets the keys of all attributes of an XML element.

Parameters:

element {XML ELEMENT} - the element to inquire

Return Value:

attributes {List of STRINGs} - a list of attribute keys

nil - element does not have any attribute

Example:

(setf attribute-keys (sd-xml-element-get-attributes my-xml-element))
=> ("key1" "key2")
  

SD-XML-ELEMENT-GET-ATTRIBUTE  [function]

(sd-xml-element-get-attribute element attribute-key)

Description:

Gets the attribute value of an XML element.

Parameters:

element {XML ELEMENT} - the element to inquire

attribute-key {STRING} - the attribute key to inquire

Return Value:

value {STRING} - the attribute value

nil - the attribute is not set

Example:

(setf attribute-value (sd-xml-element-get-attribute my-xml-element "key1"))
=> "value1"
  

SD-XML-ELEMENT-SET-ATTRIBUTE  [function]

(sd-xml-element-set-attribute element attribute-key attribute-value)

Description:

Sets the attribute value of an XML element for a specified attribute key.

Parameters:

element {XML ELEMENT} - the element to change

attribute-key {STRING} - the attribute key to change the value

attribute-value {STRING} - the new attribute value

Return Value:

t - success

nil - failure

Example:

(setf result (sd-xml-element-set-attribute my-xml-element "key1" "value_modified"))
  

SD-XML-ELEMENT-GET-PARENT  [function]

(sd-xml-element-get-parent element)

Description:

Gets the parent of an XML element.

Parameters:

element {XML ELEMENT} - the element to inquire

Return Value:

element {XML ELEMENT} - the parent element

Example:

(setf element-parent (sd-xml-element-get-parent my-xml-element))
  

SD-XML-ELEMENT-GET-DOCUMENT  [function]

(sd-xml-element-get-document element)

Description:

Gets the owner document of an XML element.

Parameters:

element {XML ELEMENT} - the element to inquire

Return Value:

document {XML DOCUMENT} - the owner document

Example:

(setf my-xml-document (sd-xml-element-get-document my-xml-element))
  

SD-XML-TRANSFORM-FILE  [function]

(sd-xml-transform-file document stylesheet outputFile)

Description:

Applies an XSLT transformation to an XML document.

Parameters:

document {XML DOCUMENT} - reference to the XML document

stylesheet {STRING} - path to a stylesheet file

outputFile {STRING} - path to a output XML file

Return Value:

t - success

nil - failure

On success XML file containing transformed document mentioned by outputFile parameter is created.

Example:

(sd-xml-transform-file my-xml-document "d:/temp/stylesheet.xsl" "d:/temp/outputfile.xml")
  

SD-XML-CLEAR-CACHE  [function]

(sd-xml-clear-cache)

Description:

Disposes all XML documents and elements created through the LISP interface. LISP references to any of the objects obtained by the LISP API will become invalid.

Example:

(sd-xml-clear-cache)