Class MXMLDocument[in MXLM]

Encapsulates a complete XML document.

class MXMLDocument( [encoding], [style] )

more...

Summary

Encapsulates a complete XML document.

To work with MXML, you need to instantiate at least one object from this class; this represents the logic of a document. It is derived for an element, as an XML document must still be valid as an XML element of another document, but it implements some data specific for handling documents.

The XML document, as seen by the MXML module, is a tree of nodes. Some nodes have meta-informative value, and are meant to be used by the XML parser programs to determine how the tree is expected to be built.

The tree itself has a topmost node (called top node), which is the parent for every other node, and a node called "root" which is actually the root of the "informative hierarchy" of the XML document, called 'tag nodes'.

Tag nodes can have some "attributes", zero or more children and a partent. It is also possible to access the previous node at the same level of the tree, or the next one, and it is possible to insert nodes in any position. Tag nodes can have other tag nodes, data nodes or comment nodes as children. Processing Instruction nodes can also be placed at any level of the XML tree.

A valid XML document can have only one root node, or in other words, it can declare only one tag node at top level. In example, the following is a valid XML document:

   <?xml encoding="utf-8" version="1.0" ?>
   <!-- The above was an XML special PI node, and this is a comment -->
   <!DOCTYPE greeting SYSTEM "hello.dtd">
   <!-- We see a doctype above -->
   <MyDocumentRootTag>
      ...
   </MyDocumentRootTag>

In the above document, the top node would hold a comment, a DOCTYPE node, another comment and then a tag node, which is also the "root" node.

The special XML instruction at the beginning is not translated into a node; instead, its attribute becomes readable properties of the MXMLDocument instance (or are written taking them from the instance properties, if the document is being written).

Falcon MXML node allows to create automatically simple data nodes attacched to tag nodes by specifying a "data" value for the node. In example,

   <some_tag>Some data</some_tag>

this node can be generated by creating a either a "some_tag" node and adding a data child to it, or setting its MXMLNode.data to "Some tag". Falcon will automatically import data for such nodes in the data field of the parent tag node.

On the other hand, it is possible to create combination of data and tag children as in the following sample:

   <p>A paragraph <b>with bold text</b>.</p>

In this case, it is necessary to create a "p" tag node with a child data node containing "A paragraph ", a tag "b" node having "with bold text" as single data and a data node containing a single "." character. The data in the "p" tag node will be empty.

Init Block

Encapsulates a complete XML document.

To work with MXML, you need to instantiate at least one object from this class; this represents the logic of a document. It is derived for an element, as an XML document must still be valid as an XML element of another document, but it implements some data specific for handling documents.

The XML document, as seen by the MXML module, is a tree of nodes. Some nodes have meta-informative value, and are meant to be used by the XML parser programs to determine how the tree is expected to be built.

The tree itself has a topmost node (called top node), which is the parent for every other node, and a node called "root" which is actually the root of the "informative hierarchy" of the XML document, called 'tag nodes'.

Tag nodes can have some "attributes", zero or more children and a partent. It is also possible to access the previous node at the same level of the tree, or the next one, and it is possible to insert nodes in any position. Tag nodes can have other tag nodes, data nodes or comment nodes as children. Processing Instruction nodes can also be placed at any level of the XML tree.

A valid XML document can have only one root node, or in other words, it can declare only one tag node at top level. In example, the following is a valid XML document:

   <?xml encoding="utf-8" version="1.0" ?>
   <!-- The above was an XML special PI node, and this is a comment -->
   <!DOCTYPE greeting SYSTEM "hello.dtd">
   <!-- We see a doctype above -->
   <MyDocumentRootTag>
      ...
   </MyDocumentRootTag>

In the above document, the top node would hold a comment, a DOCTYPE node, another comment and then a tag node, which is also the "root" node.

The special XML instruction at the beginning is not translated into a node; instead, its attribute becomes readable properties of the MXMLDocument instance (or are written taking them from the instance properties, if the document is being written).

Falcon MXML node allows to create automatically simple data nodes attacched to tag nodes by specifying a "data" value for the node. In example,

   <some_tag>Some data</some_tag>

this node can be generated by creating a either a "some_tag" node and adding a data child to it, or setting its MXMLNode.data to "Some tag". Falcon will automatically import data for such nodes in the data field of the parent tag node.

On the other hand, it is possible to create combination of data and tag children as in the following sample:

   <p>A paragraph <b>with bold text</b>.</p>

In this case, it is necessary to create a "p" tag node with a child data node containing "A paragraph ", a tag "b" node having "with bold text" as single data and a data node containing a single "." character. The data in the "p" tag node will be empty.

Methods

deserialize()

Loads an XML document from a stream.

MXMLDocument.deserialize( istream )

Loads a document from a Falcon Stream. After a succesful call, the document is ready for inspection and can be modified.

find()

Finds the first (tag) node matching a certain criterion.

MXMLDocument.find( name, [attrib], [value], [data] )

This method performs a search in the XML tree, starting from the root, from a tag node with the given name, attribute (eventually having a certain value) and specified data portion. All the paramters are optional, and can be substituted with a nil or not given to match "everything".

The MXMLDocument.findNext method will repeat the search starting from the last matching node; direction of the search is down towards the leaves of the tree, then forward towards the next siblings. When the nodes matching the criterion are exhausted, the two methods return nil.

In example, to search in a tree for all the nodes named "interesting", the following code can be used:

   // doc is a MXMLDocument
   node = doc.find( "interesting" )
   while node != nil
      > "Found an interesting node:", node.path()
      ...
      node = doc.findNext()
   end

To find a node which has an attribute named "cute" (at which value we're not interested), and which data node contains the word "suspect", the following code can be used:

   node = doc.find( nil, "cute", nil, "suspect" )
   while node != nil
      > "Found a suspect node:", node.path()
      ...
      node = doc.findNext()
   end

Note: Checks are case sensitive.

findNext()

Finds the next (tag) node matching a certain criterion.

MXMLDocument.findNext( )

This method is meant to be used after a MXMLDocument.find call has returned a valid node to iterate through all the matching nodes in a tree.

findPath()

Finds the first (tag) node matching a certain XML path.

MXMLDocument.findPath( path )

This method provides limited (at this time, very limited) support for xpath. A tag node can be found through a virtual "path" staring from the root node and leading to it; each element of the path is a tag parent node. In example, the path for the node "inner" in the following example:

   <root>
      <outer>
         <middle>
            <inner>Inner content</inner>
         </middle>
      </outer>
   </root>

would be "/root/outer/middle/inner".

Paths are not unique keys for the nodes; in the above example, more than one "inner" node may be stacked inside the "middle" node, and all of them would have the same path.

This method allows to use a "*" wildcard to substitute a level of the path with "anything". In example, the path "/root/\*\/middle/inner" would find the inner node in the above sample no matter what the second-topmost node name was.

If the path cannot match any node in the three, the method returns nil. It is possible to iterate through all the nodes having the same path (or matching wildcard paths) in a tree by using the MXMLDocument.findPathNext method. In example, the following code would find all the nodes which have exactly two parents:

   node = doc.findPath( "/*/*/*" )
   while node != nil
      > "Found a node at level 3:", node.path()
      ...
      node = doc.findPathNext()
   end

findPathNext()

Finds the next (tag) node matching a certain XML path.

MXMLDocument.findPathNext( )

This method is meant to be used together with MXMLDocument.findPath method to traverse a tree in search of nodes matching certain paths.

getEncoding()

Returns the encoding for stream operations.

MXMLDocument.getEncoding( )

This method returns the encoding that has been previously set either at document creation or through the MXMLDocument.setEncoding.

Also, after a succesful deserialization, this method will return the value of the "encoding" attribute of the ?xml PI heading directive, if provided.

If still unset, this method will return nil.

read()

Loads a document to an XML file on a filesystem.

MXMLDocument.read( filename )

This method loads the XML document from a file on a reachable filesystem. It takes care of opening a suitable stream, transcoding it using the chosen encoding and performing a complete deserialization through MXMLDocument.deserialize.

root()

Retrieves the root tag node in the document.

MXMLDocument.root( )

This method returns the "root" node, which is the unique topmost node of type "tag", and that defines the information contents of the XML document.

The default name for this node is "root"; the implementor should change the name to something more sensible before serializing a document generated from this instance.

As a valid XML document must have exactly one root node, an instance for this node is always generated when then document is created, so it is always available.

serialize()

Stores the document as an XML file.

MXMLDocument.serialize( ostream )

This method stores an XML document created using the three in this instance on the stream passed as parameter.

setEncoding()

Changes the document encoding for stream operations.

MXMLDocument.setEncoding( encoding )

This method sets the encoding used for I/O operations on this XML document. It also determines the value of the "encoding" attribute that will be set in the the special PI ?xml at document heading.

style()

Reads or changes the style applied to this XML document.

MXMLDocument.style( [setting] )

This method allows to read or change the style used for serialization and deserialization of this document, which is usually set in the constructor.

The setting paramter must be in MXMLStyle enumeration.

The method returns the current style as a combination of the bitfields from the MXMLStyle enumeration.

top()

Retrieves the topmost node in the document.

MXMLDocument.top( )

This method returns the topmost node of the document; this is actually an invisible node which is used as a "container" for the top nodes in the document: comments, directives as DOCTYPE and the "root" tag node.

write()

Stores a document to an XML file on a filesystem.

MXMLDocument.write( filename )

This method saves the XML document to a file on a reachable filesystem. It takes care of opening a suitable stream, transcoding it using the chosen encoding and performing a complete serialization through MXMLDocument.serialize.