Main index  |  Module description  |  Classes  |  Enums

ClassMXMLDocument

class MXMLDocument( [encoding], [style] )

Encapsulates a complete XML document. more...


Member list

Constructor
init Creates the document object.
Methods
deserialize Loads an XML document from a stream.
find Finds the first (tag) node matching a certain criterion.
findNext Finds the next (tag) node matching a certain criterion.
findPath Finds the first (tag) node matching a certain XML path.
findPathNext Finds the next (tag) node matching a certain XML path.
getEncoding Returns the encoding for stream operations.
read Loads a document to an XML file on a filesystem.
root Retrieves the root tag node in the document.
serialize Stores the document as an XML file.
setEncoding Changes the document encoding for stream operations.
style Reads or changes the style applied to this XML document.
top Retrieves the topmost node in the document.
write Stores a document to an XML file on a filesystem.

Detailed description

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.

MXML document structure.

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.


Class methods

init()

Creates the document object.

MXMLDocument.init( [encoding], [style] )
encoding

Encoding suggested for document load or required for document write.

style

Style required in document write. Class containing a logical XML file representation.

It is possible to specify a encoding parameter which must be one of the encoding names know by Falcon (see the TranscoderFactory function in the RTL documentation). In this version, this parameter is ignored if the object is used to deserialize an XML document, but it's used as output encoding (and set in the "encoding" field of the XML heading) when writing the document.

The style parameter requires that a particular formatting is used when writing the document. It can be overridden in the MXMLDocument.write method, and if not provided there, the default set in the constructor will be used.

The style paramter must be in MXMLStyle enumeration.

Note: It is not necessary to create and serialize a whole XML document to create just XML compliant data representations. Single nodes can be serialized with the MXMLNode.serialize method; in this way it is possible to create small xml valid fragments for storage, network streaming, template filling etc. At the same time, it is possible to de-serialize a single XML node through the MXMLNode.deserialize method, which tries to decode an XML document fragment configuring the node and eventually re-creating its subtree.

See also MXMLDocument.deserialize.

deserialize()

Loads an XML document from a stream.

MXMLDocument.deserialize( istream )
istream

A Falcon Stream instance opened for input.

Raises:
MXMLError

on load error.

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

See also MXMLDocument.read.

find()

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

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

Tag name of the searched node.

attrib

Name of one of the attributes of the searched node.

value

Value for one of the attributes in the node.

data

Part of the data stored in the searched tag node.

Returns:

The node matching the given criterion or nil if not found.

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.

See also MXMLDocument.findNext.

findNext()

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

MXMLDocument.findNext( )
Returns:

The next node matching the given criterion or nil if not found.

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.

See also MXMLDocument.find.

findPath()

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

MXMLDocument.findPath( path )
path

The XML path to be searched.

Returns:

The next node matching the given criterion or nil if not found.

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

See also MXMLDocument.findPathNext.

findPathNext()

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

MXMLDocument.findPathNext( )
Returns:

The next node matching the given criterion or nil if not found.

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

See also MXMLDocument.findPath.

getEncoding()

Returns the encoding for stream operations.

MXMLDocument.getEncoding( )
Returns:

Previously set or read XML encoding.

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.

See also MXMLDocument.setEncoding.

read()

Loads a document to an XML file on a filesystem.

MXMLDocument.read( filename )
filename

Name of the source XML file.

Raises:
MXMLError

on error during the deserialization.

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.

See also MXMLDocument.setEncoding.

root()

Retrieves the root tag node in the document.

MXMLDocument.root( )
Returns:

The root tag node of the XML document.

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.

See also MXMLDocument.top, MXMLDocument.

serialize()

Stores the document as an XML file.

MXMLDocument.serialize( ostream )
ostream

A Falcon Stream opened for output.

Raises:
MXMLError

on write error.

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

See also MXMLDocument.write.

setEncoding()

Changes the document encoding for stream operations.

MXMLDocument.setEncoding( encoding )
encoding

A valid falcon encoding name

Raises:
ParamError

if the encoding name is unknown.

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.

See also MXMLDocument.getEncoding.

style()

Reads or changes the style applied to this XML document.

MXMLDocument.style( [setting] )
setting

If given, changes the style.

Returns:

The current style settings.

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.

See also MXMLDocument.init.

top()

Retrieves the topmost node in the document.

MXMLDocument.top( )
Returns:

The overall topmost node of the XML document.

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.

See also MXMLDocument.root, MXMLDocument.

write()

Stores a document to an XML file on a filesystem.

MXMLDocument.write( filename )
filename

Name of the destination XML file.

Raises:
MXMLError

on error during the serialization.

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.

See also MXMLDocument.setEncoding.


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