Main index  |  Module description  |  Classes  |  Enums

ClassMXMLNode

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

Minimal entity of the XML document. more...


Member list

Constructor
init Creates a new node of a certain type.
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.

Detailed description

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.


Class methods

init()

Creates a new node of a certain type.

MXMLNode.init( 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..

Raises:
ParamError

if the type is invalid.

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.

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

A 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.

Returns:

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.

depth()

Calculates the depth of this node.

MXMLNode.depth( )
Returns:

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.

deserialize()

Stores an XML node on a stream.

MXMLNode.deserialize( )
Raises:
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( )
Returns:

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

getAttribs()

Gets the all the XML attributes of this node.

MXMLNode.getAttribs( )
Returns:

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.

getAttribute()

Gets the value of an XML attribute of this node.

MXMLNode.getAttribute( attribute )
attribute

The XML attribute to be read.

Returns:

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.

getChildren()

Gets the all the children nodes of this node.

MXMLNode.getChildren( )
Returns:

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.

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

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

name()

Set and/or return the name of this node.

MXMLNode.name( [name] )
name

If provided, the new name of this node.

Returns:

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.

nextSibling()

Return the next node child of the same parent.

MXMLNode.nextSibling( )
Returns:

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.firstChild.

nodeType()

Returns the type of this node.

MXMLNode.nodeType( )
Returns:

A value in MXMLType enumeration.

parent()

Return the parent node of this node.

MXMLNode.parent( )
Returns:

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.

path()

Returns the path from the root to this node.

MXMLNode.path( )
Returns:

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.findPath.

prevSibling()

Return the previous node child of the same parent.

MXMLNode.prevSibling( )
Returns:

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.lastChild.

removeChild()

Removes a child from its parent tree.

MXMLNode.removeChild( child )
child

The child node to be removed.

Returns:

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.

serialize()

Stores an XML node on a stream.

MXMLNode.serialize( )
Raises:
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.


Main index  |  Module description  |  Classes  |  Enums
Made with Faldoc 1.0.0