The CARA/Lua API Reference

Cours the CARA/Lua API Reference, tutoriel & guide de travaux pratiques en pdf.

Class DomDocument

This class represents XML files loaded into memory. It is created by xml.createDocument or xml.openDocument. Use it to load, process and write XML data. DomDocument, DomElement and DomText partly follow the Document Object Model (DOM) standardized by the W3C (www.w3c.org). The following diagramm shows the objects with their relations to each other.
DomNode is a virtual object which is only necessary to show the polymorphic nature of DomElement and DomText (DomElement is a DomNode and DomText is a DomNode). The DomElement is owner of zero or more subordinate DomText and DomElement, represented by the relation to DomNode.
doc = xml.openDocument( dlg.getOpenFileName() )
print( doc:getXml() )
root = doc:getDocumentElement()
e = root:getFirstChild()
while e ~= nil do
print( e:getName() )
e = e:getNextSibling()
end
getDocumentElement
Params: none.
Returns: DomElement
Each DomDocument has exactly one root element which you have to access using this function.
When a new DomDocument is created, this element is automatically created.

getXml
Params: none
Returns: string
This function returns a string containing the whole XML text of this DomDocument. Use it for building your own saving function or for debugging purpose.

saveToFile
Params: string (file path)
Returns: none.
This function tries to save the DomDocument as an XML file to the given path. The function is aborted with an error, if the file cannot be opened for writing. Note that an existing file with the same path will be overwritten.

Class DomElement
A DomDocument consists of a tree of DomElements. DomElements are recursively contained by itself and thus span a tree structure.
According to the W3C standard DomElements can contain CDATA sections, which are supposed to be separate element types in principle. In CARA/Lua the CDATA sections are automatically converted to text elements and do not appear as separate classes.
DomElements consist of attributes and child elements, the latter beeing DomElements and DomTexts polymorphically. The attribute names are unique within a DomElement, where’as the child DomElements can have an arbitrary name (because their order is relevant).

createElement
Params: string (tag name)
Returns: DomElement
This function creates a new element with the given name and appends it to the end of the list of children of the element this function is called with.

createText
Params: string (optional, the text)
Returns: DomText
This function creates a new text and appends it to the end of the list of children of the element this function is called with. If the parameter is omitted, an empty text element is created. You can combine all successing text elements to one text using the function normalize.
getAttribute
Params: string (name)
Returns: string or nil
Use this function to access an attribute of this element.
getAttributes
Params: none.
Returns: Table[ string (name), string (value) ]
This function returns the list of all attributes of this element.
getChildren
Params: none.
Returns: Table[ number (index), DomElement or DomText ]
This function returns all the children of this element in an array (in the original order). Note that an element can have either texts or other elements as children.
getFirstChild
Params: none.
Returns: DomElement or DomText or nil
This function returns the first child of this element (equivalent to DomElement:getChildren()[1]).
getLastChild
Params: none.
Returns: DomElement or DomText or nil
This function returns the last child of this element (equivalent to DomElement:getChildren()[n], where n is the number of children).
getName
Params: none
Returns: string (the tag name of this element)
getNextSibling
Params: none.
Returns: DomElement or DomText or nil
This function returns the next element in the list of children of the parent element. Use it to iterate over all children of the parent.
getPrevSibling
Params: none.
Returns: DomElement or DomText or nil
This function returns the previous element in the list of children of the parent element. Use it to iterate over all children of the parent.

hasAttribute
Params: string (attribute name)
Returns: boolean
This function returns true, if an attribute with the given name is defined in this element.
isElement
Params: none
Returns: boolean
This function returns always true for DomElements. Use it to differ between DomElement and DomText members, because the list of children of an element is polymorphic.
isText
Params: none
Returns: boolean
This function returns always false for DomElements. Use it to differ between DomElement and DomText members, because the list of children of an element is polymorphic.
normalize
Params: none
Returns: none
Use this function to combine all succesive DomText elements of the children list of this element into one DomText.
removeAttribute
Params: string (attribute name)
Returns: none.
Use this function to remove the attribute with the given name from this element. Nothing happens if the attribute didn’t exist.

removeThis
Params: none.
Returns: none.
Use this function to remove this element from its parents list of children. The element still exists after removal, but is useless. If you call this function for the root element, the DomDocument becomes useless.
setAttribute
Params: string (attribute name), string (attribute value)
Returns: none.
This function sets the attribute of the given name to the given value. Only text values can be set (Lua tries to automatically convert other value types to text). If the attribute didn’t exist, it is automatically created.

setName
Params: string (name)
Returns: none
Sets the tag name of this element. This is the name visible in the XML file, i.e. as <name/>.

Class DomText
DomText represents a text between to XML tags (see example). A DomElement (see above) can contain more than one DomText. The second example shows element2 containing
<element1>This is a text between two tags</element1>
<element2>This is part A<subelement/>This is part B</element2>
two DomText and a DomElement. The following diagram shows the corresponding instance relationship.

Introduction
A brief Lua overview
The CARA Object Model (CARM)
The CARA/Lua API Reference
Global Variable cara
Class Atom
Class AtomGroup
Class Buffer
Class Button
Class ButtonGroup
Class Canvas
Class CheckBox
Class ComboBox
Class ContourPlot
Class Dialog
Class DomDocument
Class DomElement
Class Experiment
Class Frame
Class Grid
Class GroupBox
Class HBox
Class Image
Class Label
Class LineEdit
Class ListItem
Class ListView
Class MainWindow
Class MenuBar
Class ProtonList
Class ScrollView
Class SpectrumType
Class SpinSystem
openDocument
parseDocument