<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class MXMLDocument - Class MXMLDocument</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class MXMLDocument<span class="faldoc_belong"><a href="./module_feather_mxml.html">[in MXLM]</a></p></h1>
<p class="faldoc_brief">Encapsulates a complete XML document. </p>
<p class="faldoc_funcdecl">
<b>class</b> MXMLDocument( [encoding], [style] )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#deserialize">deserialize()</a></td><td>Loads an XML document from a stream. </td></tr>
<tr><td><a href="#find">find()</a></td><td>Finds the first (tag) node matching a certain criterion. </td></tr>
<tr><td><a href="#findNext">findNext()</a></td><td>Finds the next (tag) node matching a certain criterion. </td></tr>
<tr><td><a href="#findPath">findPath()</a></td><td>Finds the first (tag) node matching a certain XML path. </td></tr>
<tr><td><a href="#findPathNext">findPathNext()</a></td><td>Finds the next (tag) node matching a certain XML path. </td></tr>
<tr><td><a href="#getEncoding">getEncoding()</a></td><td>Returns the encoding for stream operations. </td></tr>
<tr><td><a href="#read">read()</a></td><td>Loads a document to an XML file on a filesystem. </td></tr>
<tr><td><a href="#root">root()</a></td><td>Retrieves the root tag node in the document. </td></tr>
<tr><td><a href="#serialize">serialize()</a></td><td>Stores the document as an XML file. </td></tr>
<tr><td><a href="#setEncoding">setEncoding()</a></td><td>Changes the document encoding for stream operations. </td></tr>
<tr><td><a href="#style">style()</a></td><td>Reads or changes the style applied to this XML document. </td></tr>
<tr><td><a href="#top">top()</a></td><td>Retrieves the topmost node in the document. </td></tr>
<tr><td><a href="#write">write()</a></td><td>Stores a document to an XML file on a filesystem. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> MXMLDocument( [encoding], [style] )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">encoding</td><td class="faldoc_optparamdesc">Encoding suggested for document load or required for document write. </td></tr><tr><td class="faldoc_optparam">style</td><td class="faldoc_optparamdesc">Style required in document write. Class containing a logical XML file representation. </td></tr>
</table>
<br/>
<p class="item_brief">Encapsulates a complete XML document. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text"> It is possible to specify a <b>encoding</b> parameter which must be one of the encoding names know by Falcon (see the <b>TranscoderFactory</b> 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. </p>
<p class="faldoc_text"> The <b>style</b> parameter requires that a particular formatting is used when writing the document. It can be overridden in the <a href="./class_MXMLDocument.html#write">MXMLDocument.write</a> method, and if not provided there, the default set in the constructor will be used. </p>
<p class="faldoc_text"> The <b>style</b> parameter must be in <a href="./enum_MXMLStyle.html">MXMLStyle</a> enumeration. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> 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 <a href="./class_MXMLNode.html#serialize">MXMLNode.serialize</a> 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 <a href="./class_MXMLNode.html#deserialize">MXMLNode.deserialize</a> method, which tries to decode an XML document fragment configuring the node and eventually re-creating its subtree. </p>
<a name="mxml_doc_struct"><h2 class="faldoc_section">MXML document structure. </h2></a>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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'. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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: </p>
<pre class="faldoc_code">
<?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>
</pre>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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). </p>
<p class="faldoc_text">Falcon MXML node allows to create automatically simple data nodes attacched to tag nodes by specifying a "data" value for the node. In example, </p>
<pre class="faldoc_code">
<some_tag>Some data</some_tag>
</pre>
<p class="faldoc_text"> this node can be generated by creating a either a "some_tag" node and adding a data child to it, or setting its <a href="./class_MXMLNode.html#data">MXMLNode.data</a> to "Some tag". Falcon will automatically import data for such nodes in the data field of the parent tag node. </p>
<p class="faldoc_text">On the other hand, it is possible to create combination of data and tag children as in the following sample: </p>
<pre class="faldoc_code">
<p>A paragraph <b>with bold text</b>.</p>
</pre>
<p class="faldoc_text">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. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="deserialize">deserialize()</a></h3>
<p class="item_brief">Loads an XML document from a stream. </p>
<p class="faldoc_funcdecl">MXMLDocument.deserialize( istream )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">istream</td><td class="faldoc_paramdesc">A Falcon Stream instance opened for input. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_MXMLError.html">MXMLError</a></td><td class="faldoc_raisedesc">on load error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Loads a document from a Falcon Stream. After a succesful call, the document is ready for inspection and can be modified. </p>
</p>
<h3 class="faldoc_funcname"><a name="find">find()</a></h3>
<p class="item_brief">Finds the first (tag) node matching a certain criterion. </p>
<p class="faldoc_funcdecl">MXMLDocument.find( name, [attrib], [value], [data] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">name</td><td class="faldoc_paramdesc">Tag name of the searched node. </td></tr>
<tr><td class="faldoc_optparam">attrib</td><td class="faldoc_optparamdesc">Name of one of the attributes of the searched node. </td></tr><tr><td class="faldoc_optparam">value</td><td class="faldoc_optparamdesc">Value for one of the attributes in the node. </td></tr><tr><td class="faldoc_optparam">data</td><td class="faldoc_optparamdesc">Part of the data stored in the searched tag node. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The node matching the given criterion or nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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". </p>
<p class="faldoc_text"> The <a href="./class_MXMLDocument.html#findNext">MXMLDocument.findNext</a> 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. </p>
<p class="faldoc_text">In example, to search in a tree for all the nodes named "interesting", the following code can be used: </p>
<pre class="faldoc_code">
// doc is a MXMLDocument
node = doc.find( "interesting" )
while node != nil
> "Found an interesting node:", node.path()
...
node = doc.findNext()
end
</pre>
<p class="faldoc_text">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: </p>
<pre class="faldoc_code">
node = doc.find( nil, "cute", nil, "suspect" )
while node != nil
> "Found a suspect node:", node.path()
...
node = doc.findNext()
end
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Checks are case sensitive. </p>
</p>
<h3 class="faldoc_funcname"><a name="findNext">findNext()</a></h3>
<p class="item_brief">Finds the next (tag) node matching a certain criterion. </p>
<p class="faldoc_funcdecl">MXMLDocument.findNext( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The next node matching the given criterion or nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is meant to be used after a <a href="./class_MXMLDocument.html#find">MXMLDocument.find</a> call has returned a valid node to iterate through all the matching nodes in a tree. </p>
</p>
<h3 class="faldoc_funcname"><a name="findPath">findPath()</a></h3>
<p class="item_brief">Finds the first (tag) node matching a certain XML path. </p>
<p class="faldoc_funcdecl">MXMLDocument.findPath( path )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">The XML path to be searched. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The next node matching the given criterion or nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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: </p>
<pre class="faldoc_code">
<root>
<outer>
<middle>
<inner>Inner content</inner>
</middle>
</outer>
</root>
</pre>
<p class="faldoc_text">would be "/root/outer/middle/inner". </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text"> 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 <a href="./class_MXMLDocument.html#findPathNext">MXMLDocument.findPathNext</a> method. In example, the following code would find all the nodes which have exactly two parents: </p>
<pre class="faldoc_code">
node = doc.findPath( "/\*\/\*\/\*" )
while node != nil
> "Found a node at level 3:", node.path()
...
node = doc.findPathNext()
end
</pre>
</p>
<h3 class="faldoc_funcname"><a name="findPathNext">findPathNext()</a></h3>
<p class="item_brief">Finds the next (tag) node matching a certain XML path. </p>
<p class="faldoc_funcdecl">MXMLDocument.findPathNext( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The next node matching the given criterion or nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is meant to be used together with <a href="./class_MXMLDocument.html#findPath">MXMLDocument.findPath</a> method to traverse a tree in search of nodes matching certain paths. </p>
</p>
<h3 class="faldoc_funcname"><a name="getEncoding">getEncoding()</a></h3>
<p class="item_brief">Returns the encoding for stream operations. </p>
<p class="faldoc_funcdecl">MXMLDocument.getEncoding( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Previously set or read XML encoding. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method returns the encoding that has been previously set either at document creation or through the <a href="./class_MXMLDocument.html#setEncoding">MXMLDocument.setEncoding</a>. </p>
<p class="faldoc_text">Also, after a succesful deserialization, this method will return the value of the "encoding" attribute of the ?xml PI heading directive, if provided. </p>
<p class="faldoc_text">If still unset, this method will return nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="read">read()</a></h3>
<p class="item_brief">Loads a document to an XML file on a filesystem. </p>
<p class="faldoc_funcdecl">MXMLDocument.read( filename )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">Name of the source XML file. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_MXMLError.html">MXMLError</a></td><td class="faldoc_raisedesc">on error during the deserialization. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> 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 <a href="./class_MXMLDocument.html#deserialize">MXMLDocument.deserialize</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="root">root()</a></h3>
<p class="item_brief">Retrieves the root tag node in the document. </p>
<p class="faldoc_funcdecl">MXMLDocument.root( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The root tag node of the XML document. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="serialize">serialize()</a></h3>
<p class="item_brief">Stores the document as an XML file. </p>
<p class="faldoc_funcdecl">MXMLDocument.serialize( ostream )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">ostream</td><td class="faldoc_paramdesc">A Falcon Stream opened for output. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_MXMLError.html">MXMLError</a></td><td class="faldoc_raisedesc">on write error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method stores an XML document created using the three in this instance on the stream passed as parameter. </p>
</p>
<h3 class="faldoc_funcname"><a name="setEncoding">setEncoding()</a></h3>
<p class="item_brief">Changes the document encoding for stream operations. </p>
<p class="faldoc_funcdecl">MXMLDocument.setEncoding( encoding )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">encoding</td><td class="faldoc_paramdesc">A valid falcon encoding name </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>ParamError</i></b></td><td class="faldoc_raisedesc">if the encoding name is unknown. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="style">style()</a></h3>
<p class="item_brief">Reads or changes the style applied to this XML document. </p>
<p class="faldoc_funcdecl">MXMLDocument.style( [setting] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">setting</td><td class="faldoc_optparamdesc">If given, changes the style. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The current style settings. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method allows to read or change the style used for serialization and deserialization of this document, which is usually set in the constructor. </p>
<p class="faldoc_text"> The <b>setting</b> paramter must be in <a href="./enum_MXMLStyle.html">MXMLStyle</a> enumeration. </p>
<p class="faldoc_text"> The method returns the current style as a combination of the bitfields from the <a href="./enum_MXMLStyle.html">MXMLStyle</a> enumeration. </p>
</p>
<h3 class="faldoc_funcname"><a name="top">top()</a></h3>
<p class="item_brief">Retrieves the topmost node in the document. </p>
<p class="faldoc_funcdecl">MXMLDocument.top( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The overall topmost node of the XML document. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="write">write()</a></h3>
<p class="item_brief">Stores a document to an XML file on a filesystem. </p>
<p class="faldoc_funcdecl">MXMLDocument.write( filename )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">Name of the destination XML file. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_MXMLError.html">MXMLError</a></td><td class="faldoc_raisedesc">on error during the serialization. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> 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 <a href="./class_MXMLDocument.html#serialize">MXMLDocument.serialize</a>. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
