Class MXMLNode[in MXLM]

Minimal entity of the XML document.

class MXMLNode( type, [name], [data] )

more...

Summary

class MXMLNode( type, [name], [data] )

Minimal entity of the XML document.

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

addBelow()

Adds a node below this one.

MXMLNode.addBelow( node )

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( )

data()

Set and/or return the content of this node.

MXMLNode.data( [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( )

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( )

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( )

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( )

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 )

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( )

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 )

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 )

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 )

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( )

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] )

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( )

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.

nodeType()

Returns the type of this node.

MXMLNode.nodeType( )

parent()

Return the parent node of this node.

MXMLNode.parent( )

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( )

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"

prevSibling()

Return the previous node child of the same parent.

MXMLNode.prevSibling( )

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.

removeChild()

Removes a child from its parent tree.

MXMLNode.removeChild( child )

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( )

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 )

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.