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 |
|
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. |
| clone | Clones a whole XML hierarcy starting from this node. |
| data | Set and/or return the content of this node. |
| depth | Calculates the depth of this node. |
| deserialize | Stores an XML node on a stream. |
| firstChild | Return the first child of a node. |
| getAttribs | Gets the all the XML attributes of this node. |
| getAttribute | Gets the value of an XML attribute of this node. |
| getChildren | Gets the all the children nodes of this node. |
| insertAfter | Inserts a node after this one. |
| insertBefore | Inserts a node before this one. |
| insertBelow | Inserts a node below this one. |
| lastChild | Return the last child of a node. |
| name | Set and/or return the name of this node. |
| nextSibling | Return the next node child of the same parent. |
| nodeType | Returns the type of this node. |
| parent | Return the parent node of this node. |
| path | Returns the path from the root to this node. |
| prevSibling | Return the previous node child of the same parent. |
| removeChild | Removes a child from its parent tree. |
| serialize | Stores an XML node on a stream. |
| setAttribute | Sets an XML attribute of this node to a given value. |
| unlink | Removes a node from its parent tree. |
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.
Clones a whole XML hierarcy starting from this node.
MXMLNode.clone()
| Return | A copy of this node, with all its children copied. |
Set and/or return the content of this node.
MXMLNode.data( [data] )
| data | If provided, the new data of this node. |
| Return | If 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.
Calculates the depth of this node.
MXMLNode.depth()
| Return | The 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.
Stores an XML node on a stream.
MXMLNode.deserialize()
| Raise |
|
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.
Return the first child of a node.
MXMLNode.firstChild()
| Return | The 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
Gets the all the XML attributes of this node.
MXMLNode.getAttribs()
| Return | A 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.
Gets the value of an XML attribute of this node.
MXMLNode.getAttribute( attribute )
| attribute | The XML attribute to be read. |
| Return | The 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.
Gets the all the children nodes of this node.
MXMLNode.getChildren()
| Return | An 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.
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.
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.
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.
Return the last child of a node.
MXMLNode.lastChild()
| Return | The 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
Set and/or return the name of this node.
MXMLNode.name( [name] )
| name | If provided, the new name of this node. |
| Return | If 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.
Return the next node child of the same parent.
MXMLNode.nextSibling()
| Return | The 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.
Returns the type of this node.
MXMLNode.nodeType()
| Return | A value in MXMLType enumeration. |
Return the parent node of this node.
MXMLNode.parent()
| Return | The 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.
Returns the path from the root to this node.
MXMLNode.path()
| Return | The 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.
Return the previous node child of the same parent.
MXMLNode.prevSibling()
| Return | The 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.
Removes a child from its parent tree.
MXMLNode.removeChild( child )
| child | The child node to be removed. |
| Return | True 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.
Stores an XML node on a stream.
MXMLNode.serialize()
| Raise |
|
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.
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.
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.