2.9.3Class MXMLNode

Minimal entity of the XML document.

Class MXMLNode( type, [name],[data] )
type One of the node type defined by the MXMLType enumeration.
name Name of the node, if this is a tag node.
data Optional data content attached to this node..
Raise
ParamError if the type is invalid.

This class encapsulates a minimal adressable entity in an XML document. Nodes can be of different types, some of which, like CDATA, tag and comment nodes can have a simple textual data attached to them (equivalent to a single data node being their only child).

Nodes can be attached and detached from trees or serialized on their own. The subtrees of child nodes stays attached to its parent also when the MXMLDocument they are attached to is changed. Also, serializing a node directly allows to write mini xml valid fragments which may be used for network transmissions, database storage, template filling etc., without the need to build a whole XML document and writing the ?xml heading declarator.

The type must be one of the MXMLType enumeration elements. The name of the node is relevant only for Processing Instruction nodes and tag node, while data can be specified for comment, tag and data nodes.

If the node is created just to be de-serialized, create it as an empty comment and then deserialize the node from a stream.

Methods
addBelowAdds a node below this one.
cloneClones a whole XML hierarcy starting from this node.
dataSet and/or return the content of this node.
depthCalculates the depth of this node.
deserializeStores an XML node on a stream.
firstChildReturn the first child of a node.
getAttribsGets the all the XML attributes of this node.
getAttributeGets the value of an XML attribute of this node.
getChildrenGets the all the children nodes of this node.
insertAfterInserts a node after this one.
insertBeforeInserts a node before this one.
insertBelowInserts a node below this one.
lastChildReturn the last child of a node.
nameSet and/or return the name of this node.
nextSiblingReturn the next node child of the same parent.
nodeTypeReturns the type of this node.
parentReturn the parent node of this node.
pathReturns the path from the root to this node.
prevSiblingReturn the previous node child of the same parent.
removeChildRemoves a child from its parent tree.
serializeStores an XML node on a stream.
setAttributeSets an XML attribute of this node to a given value.
unlinkRemoves a node from its parent tree.

Methods

addBelow

Adds a node below this one.

MXMLNode.addBelow( node )
node The node to be added below this one.

This method appends the given node as the last child of this node, eventually removing it from a prevuious tree structure to which it was linked if needed.

After this method returns, node can be retreived calling the MXMLNode.lastChild on this node, until another addBelow adds another node at the end of the children list.

clone

Clones a whole XML hierarcy starting from this node.

MXMLNode.clone()
ReturnA copy of this node, with all its children copied.

data

Set and/or return the content of this node.

MXMLNode.data( [data] )
data If provided, the new data of this node.
ReturnIf a new data is not given, the current node data.

A data can be assigned to any node, but it will be meaningful only for data, tag, comment and CDATA nodes. Moreover, tag nodes can have also other children; in this case, the data set with this method will be serialized as if it was a first child data node.

depth

Calculates the depth of this node.

MXMLNode.depth()
ReturnThe depth of this node.

This method returns the number of steps needed to find a node without parents in the parent hierarchy of this node.

The dept for a topmost tree node is 0, for a root node in a tree is 1 and for its direct child is 2.

deserialize

Stores an XML node on a stream.

MXMLNode.deserialize()
Raise
MXMLError If the serialization failed.

This method allows the storage of a single node and all its children in an XML compliant format. The resulting data is an valid XML fragment that may be included verbatim in an XML document.

firstChild

Return the first child of a node.

MXMLNode.firstChild()
ReturnThe first child of this node or nil if the node hasn't any child.

This method returns the first child of a node; it's the node that will be delivered for first in the rendering of the final XML document, and that will appare on the topmost postition between the nodes below the current one.

To iterate through all the child nodes of a node, it is possible to get the first child and the iteratively MXMLNode.nextSibling until it returns nil. In example:


      // node is an MXMLNode...
      child = node.firstChild()
      while child != nil
         > "Child of ", node.name(), ": ", child.name()
         child = child.nextSibling()
      end

getAttribs

Gets the all the XML attributes of this node.

MXMLNode.getAttribs()
ReturnA dictionary containing all the XML attributes and their values.

This method retreives all the attributes of the node, and stores them in a dictionary as a pair of key => value strings.

Attributes can be assigned to PI, Tag and DOCTYPE nodes.

If the node doesn't have any XML attribute, an empty dictionary is returned.

The dictionary is read-only; values in the dictionary can be changed, but this won't change the values of the original XML attributes in the source node.

Note: Don't confuse XML attributes with Falcon attributes.

getAttribute

Gets the value of an XML attribute of this node.

MXMLNode.getAttribute( attribute )
attribute The XML attribute to be read.
ReturnThe value for this XML attribute (as a string).

This method retreives the value for an XML attribute of the node. Attributes can be assigned to PI, Tag and DOCTYPE nodes.

If the attribute doesn't exist, nil is returned.

Note: Don't confuse XML attributes with Falcon attributes.

getChildren

Gets the all the children nodes of this node.

MXMLNode.getChildren()
ReturnAn array containing all the children node.

This method stores all the children of an XML node in an array.

If the node doesn't have any child, an empty array is returned.

The array is read-only; it is possible to change it but inserting or removing nodes from it won't change the children list of the source node.

insertAfter

Inserts a node after this one.

MXMLNode.insertAfter( node )
node The node to be added after this one.

This method prepends the given node after of this one in the list of sibling nodes, eventually removing it from a prevuious tree structure to which it was linked if needed. This is equivalent to inserting the node exactly after this one, at the same level, in the final XML document.

If this node was the last child of its parent, the inserted node becomes the new last child.

insertBefore

Inserts a node before this one.

MXMLNode.insertBefore( node )
node The node to be added before this one.

This method prepends the given node in front of this one in the list of sibling nodes, eventually removing it from a prevuious tree structure to which it was linked if needed. This is equivalent to inserting the node exactly before this one, at the same level, in the final XML document.

If this node was the first child of its parent, the inserted node becomes the new first child.

insertBelow

Inserts a node below this one.

MXMLNode.insertBelow( node )
node The node to be added below this one.

This method prepends the given node as the first child of this node, eventually removing it from a prevuious tree structure to which it was linked if needed.

After this method returns, node can be retreived calling the MXMLNode.firstChild on this node, until another insertBelow adds another node at the beginning of the children list.

lastChild

Return the last child of a node.

MXMLNode.lastChild()
ReturnThe last child of this node or nil if the node hasn't any child.

This method returns the last child of a node; it's the node that will be delivered for last in the rendering of the final XML document, and that will appare on the lowermost postition between the nodes below the current one.

To iterate through all the child nodes of a node in reverse order, it is possible to get the last child and the iteratively MXMLNode.prevSibling until it returns nil. In example:


      // node is an MXMLNode...
      child = node.lastChild()
      while child != nil
         > "Child of ", node.name(), " reverse: ", child.name()
         child = child.prevSibling()
      end

name

Set and/or return the name of this node.

MXMLNode.name( [name] )
name If provided, the new name of this node.
ReturnIf a new name is not given, the current node name.

A name can be assigned to any node, but it will be meaningful only for tag and PI nodes.

nextSibling

Return the next node child of the same parent.

MXMLNode.nextSibling()
ReturnThe next node at the same level, or nil.

This method returns the next node that would be found in the rendered XML document right after this one, at the same level. If such node doesn't exist, it returns nil.

See also: MXMLNode.

nodeType

Returns the type of this node.

MXMLNode.nodeType()
ReturnA value in MXMLType enumeration.

parent

Return the parent node of this node.

MXMLNode.parent()
ReturnThe parent node or nil if this node has no parents.

This method returns the node that is currently parent of this node in the XML tree.

The method returns nil if the node hasn't a parent; this may mean that this node is the topmost node in an XMLDocument (the node returned by MXMLDocument.top ) or if it has not still been added to a tree, or if it has been removed with MXMLNode.removeChild or MXMLNode.unlink.

path

Returns the path from the root to this node.

MXMLNode.path()
ReturnThe path of this node in its XML document tree.

The path of a node is the list of parent node names separated by a slash "/", starting from the root node (or from the first node of a separate tree) and terminating with the node itself.

In example, the path of the node "item" in the following XML document:


      <root>
         <content>
            <item/>
         </content>
      </root>

would be "/root/content/item"

See also: MXMLDocument.

prevSibling

Return the previous node child of the same parent.

MXMLNode.prevSibling()
ReturnThe previous node at the same level, or nil.

This method returns the previous node that would be found in the rendered XML document right after this one, at the same level. If such node doesn't exist, it returns nil.

See also: MXMLNode.

removeChild

Removes a child from its parent tree.

MXMLNode.removeChild( child )
child The child node to be removed.
ReturnTrue if the child node is actually a child of this node, false otherwise.

This method is equivalent to MXMLNode.unlink applied to the child node, but it checks if the removed node is really a child of this node before actually removing it.

If the child parameter is really a child of this node it is unlinked and the method returns true, otherwise the node is untouched and the method returns false.

serialize

Stores an XML node on a stream.

MXMLNode.serialize()
Raise
MXMLError If the serialization failed.

This method allows the storage of a single node and all its children in an XML compliant format. The resulting data is an valid XML fragment that may be included verbatim in an XML document.

setAttribute

Sets an XML attribute of this node to a given value.

MXMLNode.setAttribute( attribute, value )
attribute The XML attribute to be set.
value The value for this XML attribute.

This method sets the value for an XML attribute of the node. Attributes can be assigned to PI, Tag and DOCTYPE nodes.

The value parameter can be any Falcon type; if it's not a string, the FBOM.toString method will be applied to transform it into a string.

If the attribute doesn't exist, it is added, otherwise it's value is changed.

Note: Don't confuse XML attributes with Falcon attributes.

unlink

Removes a node from its parent tree.

MXMLNode.unlink()

This method removes a node from the list of node of its parent node. The node is removed together with all its children and their whole subtree.

After an unlink, it is possible to insert the node into another place of the same tree or of another tree.

Actually, all the insertion routines perform an unlink on the node that is going to be inserted, so it is not necessary to call unlink from the falcon script before adding it elsewhere. However, explicitly unlinked node may be kept elsewhere (i.e. in a script maintained dictionary) for later usage.

Made with http://www.falconpl.org