Encapsulates a complete XML document.
Class MXMLDocument( [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. |
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.
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 parameter 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.
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. |
| 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. |
Loads an XML document from a stream.
MXMLDocument.deserialize( istream )
| istream | A Falcon Stream instance opened for input. | ||
| Raise |
|
Loads a document from a Falcon Stream. After a succesful call, the document is ready for inspection and can be modified.
See also: MXMLDocument.
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. |
| Return | 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.
Finds the next (tag) node matching a certain criterion.
MXMLDocument.findNext()
| Return | 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.
Finds the first (tag) node matching a certain XML path.
MXMLDocument.findPath( path )
| path | The XML path to be searched. |
| Return | 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.
Finds the next (tag) node matching a certain XML path.
MXMLDocument.findPathNext()
| Return | 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.
Returns the encoding for stream operations.
MXMLDocument.getEncoding()
| Return | 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.
Loads a document to an XML file on a filesystem.
MXMLDocument.read( filename )
| filename | Name of the source XML file. | ||
| Raise |
|
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.
Retrieves the root tag node in the document.
MXMLDocument.root()
| Return | 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, MXMLDocument.
Stores the document as an XML file.
MXMLDocument.serialize( ostream )
| ostream | A Falcon Stream opened for output. | ||
| Raise |
|
This method stores an XML document created using the three in this instance on the stream passed as parameter.
See also: MXMLDocument.
Changes the document encoding for stream operations.
MXMLDocument.setEncoding( encoding )
| encoding | A valid falcon encoding name | ||
| Raise |
|
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.
Reads or changes the style applied to this XML document.
MXMLDocument.style( [setting] )
| setting | If given, changes the style. |
| Return | 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.
Retrieves the topmost node in the document.
MXMLDocument.top()
| Return | 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, MXMLDocument.
Stores a document to an XML file on a filesystem.
MXMLDocument.write( filename )
| filename | Name of the destination XML file. | ||
| Raise |
|
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.