<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Pxp_types.html">
<link rel="next" href="Pxp_dtd.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Pxp_types" rel="Chapter" href="Pxp_types.html">
<link title="Pxp_document" rel="Chapter" href="Pxp_document.html">
<link title="Pxp_dtd" rel="Chapter" href="Pxp_dtd.html">
<link title="Pxp_tree_parser" rel="Chapter" href="Pxp_tree_parser.html">
<link title="Pxp_core_types" rel="Chapter" href="Pxp_core_types.html">
<link title="Pxp_ev_parser" rel="Chapter" href="Pxp_ev_parser.html">
<link title="Pxp_event" rel="Chapter" href="Pxp_event.html">
<link title="Pxp_dtd_parser" rel="Chapter" href="Pxp_dtd_parser.html">
<link title="Pxp_codewriter" rel="Chapter" href="Pxp_codewriter.html">
<link title="Pxp_marshal" rel="Chapter" href="Pxp_marshal.html">
<link title="Pxp_yacc" rel="Chapter" href="Pxp_yacc.html">
<link title="Pxp_reader" rel="Chapter" href="Pxp_reader.html">
<link title="Intro_trees" rel="Chapter" href="Intro_trees.html">
<link title="Intro_extensions" rel="Chapter" href="Intro_extensions.html">
<link title="Intro_namespaces" rel="Chapter" href="Intro_namespaces.html">
<link title="Intro_events" rel="Chapter" href="Intro_events.html">
<link title="Intro_resolution" rel="Chapter" href="Intro_resolution.html">
<link title="Intro_getting_started" rel="Chapter" href="Intro_getting_started.html">
<link title="Intro_advanced" rel="Chapter" href="Intro_advanced.html">
<link title="Intro_preprocessor" rel="Chapter" href="Intro_preprocessor.html">
<link title="Example_readme" rel="Chapter" href="Example_readme.html"><link title="The structure of document trees" rel="Section" href="#1_Thestructureofdocumenttrees">
<link title="Interface" rel="Section" href="#1_Interface">
<link title="The node type" rel="Subsection" href="#2_Thenodetype">
<link title="Implementations of nodes" rel="Subsection" href="#2_Implementationsofnodes">
<link title="Useful accessor functions" rel="Subsection" href="#2_Usefulaccessorfunctions">
<link title="Document model specifications" rel="Subsection" href="#2_Documentmodelspecifications">
<link title="Creating nodes from specifications" rel="Subsection" href="#2_Creatingnodesfromspecifications">
<link title="Document order" rel="Subsection" href="#docorder">
<link title="Document iterators" rel="Subsection" href="#iterators">
<link title="Whitespace" rel="Subsection" href="#2_Whitespace">
<link title="Normalization" rel="Subsection" href="#2_Normalization">
<link title="Validation" rel="Subsection" href="#2_Validation">
<link title="The document container" rel="Subsection" href="#2_Thedocumentcontainer">
<link title="Printers for the toploop" rel="Subsection" href="#2_Printersforthetoploop">
<link title="Conversion between trees and event streams" rel="Subsection" href="#2_Conversionbetweentreesandeventstreams">
<title>PXP Reference : Pxp_document</title>
</head>
<body>
<div class="navbar"><a href="Pxp_types.html">Previous</a>
<a href="index.html">Up</a>
<a href="Pxp_dtd.html">Next</a>
</div>
<center><h1>Module <a href="type_Pxp_document.html">Pxp_document</a></h1></center>
<br>
<pre><span class="keyword">module</span> Pxp_document: <code class="code"><span class="keyword">sig</span></code> <a href="Pxp_document.html">..</a> <code class="code"><span class="keyword">end</span></code></pre>Tree representation of XML documents<br>
<hr width="100%">
<br>
<a name="1_Thestructureofdocumenttrees"></a>
<h1>The structure of document trees</h1><br>
<br>
Please have a look at the separate text <a href="Intro_trees.html"><code class="code"><span class="constructor">Intro_trees</span></code></a>.<br>
<br>
<a name="1_Interface"></a>
<h1>Interface</h1><br>
<br>
<br>
<br>
<a name="2_Thenodetype"></a>
<h2>The node type</h2><br>
<br><code><span class="keyword">type</span> <a name="TYPEnode_type"></a><code class="type"></code>node_type = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_element</span> <span class="keyword">of</span> <code class="type">string</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >An element node with this element type</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_data</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >A data node</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_super_root</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >The super root node</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_pinstr</span> <span class="keyword">of</span> <code class="type">string</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >A processing instruction with this target</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_comment</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >A comment</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_none</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Sometimes used if the nodes are non-standard</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_attribute</span> <span class="keyword">of</span> <code class="type">string</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >An attribute node for this attribute name</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">T_namespace</span> <span class="keyword">of</span> <code class="type">string</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >A namespace node for this normalized prefix</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<div class="info">
This type enumerates the possible node types:<ul>
<li><code class="code"><span class="constructor">T_element</span> name</code>: The node is an element and has element type <code class="code">name</code></li>
<li><code class="code"><span class="constructor">T_data</span></code>: The node is a data node</li>
<li><code class="code"><span class="constructor">T_super_root</span></code>: The node is a super root node</li>
<li><code class="code"><span class="constructor">T_pinstr</span> name</code>: The node contains a processing instruction with
target <code class="code">name</code></li>
<li><code class="code"><span class="constructor">T_comment</span></code>: The node is a comment</li>
<li><code class="code"><span class="constructor">T_attribute</span> name</code>: The node contains an attribute called <code class="code">name</code></li>
<li><code class="code"><span class="constructor">T_namespace</span> prefix</code>: The node identifies a namespace for the
normalized <code class="code">prefix</code></li>
<li><code class="code"><span class="constructor">T_none</span></code>: This is a "bottom value" used if there is no reasonable
type.</li>
</ul>
Note that attribute and namespace nodes can only live outside the
regular tree, and are only returned by special methods.<br>
</div>
<br><code><span class="keyword">type</span> <a name="TYPEdata_node_classification"></a><code class="type"></code>data_node_classification = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">CD_normal</span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">CD_other</span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">CD_empty</span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">CD_ignorable</span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">CD_error</span> <span class="keyword">of</span> <code class="type">exn</code></code></td>
</tr></table>
<div class="info">
This type enumerates the result values of the method
<code class="code">classify_data_node</code>:<ul>
<li><code class="code"><span class="constructor">CD_normal</span></code>: Adding <code class="code">n</code> does not violate any validation
constraint</li>
<li><code class="code"><span class="constructor">CD_other</span></code>: <code class="code">n</code> is not a data node</li>
<li><code class="code"><span class="constructor">CD_empty</span></code>: The element <code class="code">obj</code> is declared as <code class="code"><span class="constructor">EMTPY</span></code>, and
<code class="code">n</code> contains the empty string. It is allowed to append
<code class="code">n</code> but it does not make sense</li>
<li><code class="code"><span class="constructor">CD_ignorable</span></code>: The element <code class="code">obj</code> is declared such that
it is forbidden to put character data into it. However,
the node <code class="code">n</code> only contains white space which is allowed
as an exception to this rule. This means that it is allowed
to append <code class="code">n</code> but <code class="code">n</code> would not contain any information
except formatting hints.</li>
<li><code class="code"><span class="constructor">CD_error</span> e</code>: It is an error to append <code class="code">n</code>. The exception
<code class="code">e</code>, usually a <code class="code"><span class="constructor">Validation_error</span></code>, contains details about
the problem.</li>
</ul>
<br>
</div>
<pre><span class="keyword">class type</span> <a name="TYPEextension"></a><code class="type">['a]</code> <a href="Pxp_document.extension.html">extension</a> = <code class="code"><span class="keyword">object</span></code> <a href="Pxp_document.extension.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
The <code class="code">extension</code> is, as the name says, the extensible part of the
nodes.
</div>
<pre><span class="keyword">class type</span> <a name="TYPEnode"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.node.html">node</a> = <code class="code"><span class="keyword">object</span></code> <a href="Pxp_document.node.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
The class type <code class="code">node</code> defines the interface of the nodes that are part
of XML document trees.
</div>
<br>
<a name="2_Implementationsofnodes"></a>
<h2>Implementations of nodes</h2><br>
<pre><span class="keyword">class</span> <a name="TYPEdata_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.data_impl.html">data_impl</a> : <code class="type">'a -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
This class is an implementation of <code class="code">node</code> which
realizes data nodes.
</div>
<pre><span class="keyword">class</span> <a name="TYPEelement_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.element_impl.html">element_impl</a> : <code class="type">'a -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
This class is an implementation of <code class="code">node</code> which
realizes element nodes.
</div>
<pre><span class="keyword">class</span> <a name="TYPEcomment_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.comment_impl.html">comment_impl</a> : <code class="type">'a -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
This class is an implementation of <code class="code">node</code> which
realizes comment nodes.
</div>
<pre><span class="keyword">class</span> <a name="TYPEpinstr_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.pinstr_impl.html">pinstr_impl</a> : <code class="type">'a -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
This class is an implementation of <code class="code">node</code> which
realizes processing instruction nodes.
</div>
<pre><span class="keyword">class</span> <a name="TYPEsuper_root_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.super_root_impl.html">super_root_impl</a> : <code class="type">'a -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
This class is an implementation of <code class="code">node</code> which
realizes super root nodes.
</div>
<pre><span class="keyword">class</span> <a name="TYPEattribute_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.attribute_impl.html">attribute_impl</a> : <code class="type">element:string -> name:string -> <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a> -> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
This class is an implementation of <code class="code">node</code> which
realizes attribute nodes.
</div>
<pre><span class="keyword">class</span> <a name="TYPEnamespace_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.namespace_impl.html">namespace_impl</a> : <code class="type">string -> string -> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
Namespace objects are only used to represent the namespace declarations
occurring in the attribute lists of elements.
</div>
<pre><span class="keyword">class</span> <a name="TYPEnamespace_element_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.namespace_element_impl.html">namespace_element_impl</a> : <code class="type">'a -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
This class is an implementation of <code class="code">node</code> which
realizes element nodes.
</div>
<pre><span class="keyword">class</span> <a name="TYPEnamespace_attribute_impl"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.namespace_attribute_impl.html">namespace_attribute_impl</a> : <code class="type">element:string -> name:string -> <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a> -> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> </code><code class="type">['a]</code> <code class="type"><a href="Pxp_document.node.html">node</a></code></pre><div class="info">
the namespace-aware implementation of attribute nodes.
</div>
<br>
<a name="2_Usefulaccessorfunctions"></a>
<h2>Useful accessor functions</h2><br>
<pre><span class="keyword">val</span> <a name="VALpinstr"></a>pinstr : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> <a href="Pxp_dtd.proc_instruction.html">Pxp_dtd.proc_instruction</a></code></pre><div class="info">
<code class="code">pinstr n</code>:
Returns the processing instruction contained in a
processing instruction node.
This function raises <code class="code"><span class="constructor">Invalid_argument</span></code> if invoked for a different node
type than <code class="code"><span class="constructor">T_pinstr</span></code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALattribute_name"></a>attribute_name : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> string</code></pre><div class="info">
<code class="code">attribute_name n</code>
Returns the name of the attribute contained in an attribute
node. Raises <code class="code"><span class="constructor">Invalid_argument</span></code> if <code class="code">n</code> does not have node type
<code class="code"><span class="constructor">T_attribute</span></code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALattribute_value"></a>attribute_value : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a></code></pre><div class="info">
<code class="code">attribute_value n</code>:
Returns the value of the attribute contained in an attribute
node. Raises <code class="code"><span class="constructor">Invalid_argument</span></code> if <code class="code">n</code> does not have node type
<code class="code"><span class="constructor">T_attribute</span></code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALattribute_string_value"></a>attribute_string_value : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> string</code></pre><div class="info">
<code class="code">attribute_string_value n</code>:
Returns the string value of the attribute contained in an attribute
node. Raises <code class="code"><span class="constructor">Invalid_argument</span></code> if <code class="code">n</code> does not have node type
<code class="code"><span class="constructor">T_attribute</span></code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALnamespace_normprefix"></a>namespace_normprefix : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> string</code></pre><div class="info">
Returns the normprefix of a namespace node.
Raises <code class="code"><span class="constructor">Invalid_argument</span></code> if <code class="code">n</code> does not have node type
<code class="code"><span class="constructor">T_namespace</span></code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALnamespace_display_prefix"></a>namespace_display_prefix : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> string</code></pre><div class="info">
Returns the display prefix of a namespace node .
Raises <code class="code"><span class="constructor">Invalid_argument</span></code> if <code class="code">n</code> does not have node type
<code class="code"><span class="constructor">T_namespace</span></code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALnamespace_uri"></a>namespace_uri : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> string</code></pre><div class="info">
Retruns the namespace URI of a namespace node .
Raises <code class="code"><span class="constructor">Invalid_argument</span></code> if <code class="code">n</code> does not have node type
<code class="code"><span class="constructor">T_namespace</span></code>.<br>
</div>
<br>
<a name="2_Documentmodelspecifications"></a>
<h2>Document model specifications</h2><br>
<pre><span class="keyword">type</span> <a name="TYPEspec"></a><code class="type">'a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a</code> spec </pre>
<div class="info">
The abstract data type of the document model specification.
These values define objects of which classes are actually created
for the various types of nodes.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALmake_spec_from_mapping"></a>make_spec_from_mapping : <code class="type">?super_root_exemplar:('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a)<br> <a href="Pxp_document.node.html">node</a> -><br> ?comment_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> ?default_pinstr_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> ?pinstr_mapping:(string, 'a <a href="Pxp_document.node.html">node</a>) Hashtbl.t -><br> data_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> default_element_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> element_mapping:(string, 'a <a href="Pxp_document.node.html">node</a>) Hashtbl.t -><br> unit -> 'a <a href="Pxp_document.html#TYPEspec">spec</a></code></pre><div class="info">
<code class="code">make_spec_from_mapping
~super_root_exemplar ~comment_exemplar ~default_pinstr_exemplar
~pinstr_mapping ~data_exemplar ~default_element_exemplar
~element_mapping
()</code>:
Creates a <code class="code">spec</code> from the arguments. Some arguments are optional,
some arguments are mandatory.<ul>
<li><code class="code">super_root_exemplar</code>: Specifies the exemplar to be used for
new super root nodes. This exemplar is optional.</li>
<li><code class="code">comment_exemplar</code>: Specifies the exemplar to be used for
new comment nodes. This exemplar is optional.</li>
<li><code class="code">pinstr_exemplar</code>: Specifies the exemplar to be used for
new processing instruction nodes by a hashtable mapping target
names to exemplars. This hashtable is optional.</li>
<li><code class="code">default_pinstr_exemplar</code>: Specifies the exemplar to be used for
new processing instruction nodes. This exemplar will be used
for targets that are not contained in the <code class="code">~pinstr_exemplar</code>
hashtable. This exemplar is optional.</li>
<li><code class="code">data_exemplar</code>: Specifies the exemplar to be used for
new data nodes. This exemplar is mandatory.</li>
<li><code class="code">element_mapping</code>: Specifies the exemplar to be used for
new element nodes by a hashtable mapping element types to
exemplars. This hashtable is mandatory (but may be empty).</li>
<li><code class="code">default_element_exemplar</code>: Specifies the exemplar to be used for
new element nodes. This exemplar will be used
for element types that are not contained in the <code class="code">~element_mapping</code>
hashtable. This exemplar is mandatory.</li>
</ul>
<br>
</div>
<pre><span class="keyword">val</span> <a name="VALmake_spec_from_alist"></a>make_spec_from_alist : <code class="type">?super_root_exemplar:('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a)<br> <a href="Pxp_document.node.html">node</a> -><br> ?comment_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> ?default_pinstr_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> ?pinstr_alist:(string * 'a <a href="Pxp_document.node.html">node</a>) list -><br> data_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> default_element_exemplar:'a <a href="Pxp_document.node.html">node</a> -><br> element_alist:(string * 'a <a href="Pxp_document.node.html">node</a>) list -><br> unit -> 'a <a href="Pxp_document.html#TYPEspec">spec</a></code></pre><div class="info">
<code class="code">make_spec_from_alist
~super_root_exemplar ~comment_exemplar ~default_pinstr_exemplar
~pinstr_alist ~data_exemplar ~default_element_exemplar
~element_alist
()</code>:
Creates a <code class="code">spec</code> from the arguments. This is a convenience
function for <code class="code">make_spec_from_mapping</code>; instead of requiring hashtables
the function allows it to pass associative lists.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALget_data_exemplar"></a>get_data_exemplar : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> 'a <a href="Pxp_document.node.html">node</a></code></pre><pre><span class="keyword">val</span> <a name="VALget_element_exemplar"></a>get_element_exemplar : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> string -> (string * string) list -> 'a <a href="Pxp_document.node.html">node</a></code></pre><pre><span class="keyword">val</span> <a name="VALget_super_root_exemplar"></a>get_super_root_exemplar : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> 'a <a href="Pxp_document.node.html">node</a></code></pre><pre><span class="keyword">val</span> <a name="VALget_comment_exemplar"></a>get_comment_exemplar : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> 'a <a href="Pxp_document.node.html">node</a></code></pre><pre><span class="keyword">val</span> <a name="VALget_pinstr_exemplar"></a>get_pinstr_exemplar : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> <a href="Pxp_dtd.proc_instruction.html">Pxp_dtd.proc_instruction</a> -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
These functions just return the exemplars (or raise <code class="code"><span class="constructor">Not_found</span></code>).<br>
</div>
<br>
<a name="2_Creatingnodesfromspecifications"></a>
<h2>Creating nodes from specifications</h2><br>
<pre><span class="keyword">val</span> <a name="VALcreate_data_node"></a>create_data_node : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> string -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">create_data_node spec dtd datastring</code>:
Creates a new data node from the exemplar contained in <code class="code">spec</code>.
The new node contains <code class="code">datastring</code> and is connected with the <code class="code">dtd</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_element_node"></a>create_element_node : <code class="type">?name_pool_for_attribute_values:<a href="Pxp_types.html#TYPEpool">Pxp_types.pool</a> -><br> ?entity_id:<a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> ?position:string * int * int -><br> ?valcheck:bool -><br> ?att_values:(string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> string -> (string * string) list -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">create_element_node ~name_pool_for_attribute_values
~position ~valcheck ~att_values spec dtd eltype
att_list</code>:
Creates a new element node from the exemplar(s) contained in
<code class="code">spec</code>:<ul>
<li>The new node will be connected to the passed <code class="code">dtd</code>.</li>
<li>The new node will have the element type <code class="code">eltype</code>.</li>
<li>The attributes of the new node will be the concatenation of
<code class="code">att_list</code> and <code class="code">att_values</code>; <code class="code">att_list</code> passes attribute values
as strings while <code class="code">att_values</code> passes attribute values as
type <code class="code">att_value</code></li>
<li>The source position is set to <code class="code">~position</code> (if passed)</li>
<li>The <code class="code">~name_pool_for_attribute_values</code> will be used, if passed.</li>
<li>If <code class="code">~valcheck = <span class="keyword">true</span></code> (the default), the attribute list is
immediately validated. If <code class="code">~valcheck = <span class="keyword">false</span></code>, the validation
is left out; in this case you can pass any element type and
and any attributes, and it does not matter whether and how
they are declared.</li>
</ul>
Even in well-formedness mode, it is ok to pass <code class="code">valcheck=<span class="keyword">true</span></code>
as this mode is implemented by weakening the validation
constraints in the DTD object. See
<a href="Intro_getting_started.html#wfmode"><i>Parsing in well-formedness mode</i></a> for explanations.
<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_super_root_node"></a>create_super_root_node : <code class="type">?entity_id:<a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> ?position:string * int * int -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">create_super_root_node ~position spec dtd</code>:
Creates a new super root node from the exemplar contained in
<code class="code">spec</code>. The new node is connected to <code class="code">dtd</code>, and the position
triple is set to <code class="code">~position</code>.
<p>
The function fails if there is no super root exemplar in <code class="code">spec</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_comment_node"></a>create_comment_node : <code class="type">?entity_id:<a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> ?position:string * int * int -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> string -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">create_comment_node ~position spec dtd commentstring</code>:
Creates a new comment node from the exemplar contained in
<code class="code">spec</code>. The new node is connected to <code class="code">dtd</code>, and the position
triple is set to <code class="code">~position</code>. The contents of the node are set
to <code class="code">commentstring</code>.
<p>
The function fails if there is no comment exemplar in <code class="code">spec</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_pinstr_node"></a>create_pinstr_node : <code class="type">?entity_id:<a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> ?position:string * int * int -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> <a href="Pxp_dtd.proc_instruction.html">Pxp_dtd.proc_instruction</a> -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">create_pinstr_node ~position spec dtd pi</code>:
Creates a new processing instruction node from the exemplar
contained in <code class="code">spec</code>. The new node is connected to <code class="code">dtd</code>, and the
position triple is set to <code class="code">~position</code>. The contents of the node are set
to <code class="code">pi</code>.
<p>
The function fails if there is no processing instruction exemplar in
<code class="code">spec</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_no_node"></a>create_no_node : <code class="type">?entity_id:<a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> ?position:string * int * int -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
Creates a T_none node with limited functionality.
<b>Important:</b> This function is conceptually broken and may be dropped in the
future.<br>
</div>
<br>
<a name="docorder"></a>
<h2>Document order</h2><br>
<br>
The functions <code class="code">compare</code> and <code class="code">ord_compare</code> implement the so-called
"document order". The basic principle is that the nodes are linearly
ordered by their occurence in the textual XML representation of the
tree. While this is clear for element nodes, data nodes, comments, and
processing instructions, a more detailed definition is necessary for the
other node types. In particular, attribute nodes of an element node
occur before any regular subnode of the element, and namespace nodes
of that element occur even before the attribute nodes. So the order
of nodes of
<pre></pre><code class="code"> <sample a1=<span class="string">"5"</span> a2=<span class="string">"6"</span>><subnode/></sample> </code><pre></pre>
is
<OL>
<li>element "sample"</li>
<li>attribute "a1"</li>
<li>attribute "a2"</li>
<li>element "subnode"</li>
</OL>
Note that the order of the attributes of the same element is unspecified,
so "a2" may alternatively be ordered before "a1". If there were namespace
nodes, they would occur between 1 and 2.
<p>
If there is a super root node, it will be handled as the very first
node.<br>
<pre><span class="keyword">val</span> <a name="VALcompare"></a>compare : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> 'a <a href="Pxp_document.node.html">node</a> -> int</code></pre><div class="info">
<code class="code">compare n1 n2</code>:
Returns -1 if <code class="code">n1</code> occurs before <code class="code">n2</code>, or +1 if <code class="code">n1</code> occurs
after <code class="code">n2</code>, or 0 if both nodes are identical.
If the nodes are unrelated (do not have a common ancestor), the result
is undefined (Note: this case is different from <code class="code">ord_compare</code>).
This test is rather slow, but it works even if the XML tree changes
dynamically (in contrast to <code class="code">ord_compare</code> below).<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEord_index"></a><code class="type">'a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a</code> ord_index </pre>
<div class="info">
The type of ordinal indexes.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_ord_index"></a>create_ord_index : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> 'a <a href="Pxp_document.html#TYPEord_index">ord_index</a></code></pre><div class="info">
<code class="code">create_ord_index startnode</code>:
Creates an ordinal index for the subtree starting at <code class="code">startnode</code>.
This index assigns to every node an ordinal number (beginning with 0) such
that nodes are numbered upon the order of the first character in the XML
representation (document order).
Note that the index is not automatically updated when the tree is
modified.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALord_number"></a>ord_number : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEord_index">ord_index</a> -><br> 'a <a href="Pxp_document.node.html">node</a> -> int</code></pre><div class="info">
Returns the ordinal number of the node, or raises <code class="code"><span class="constructor">Not_found</span></code>.
Note that attribute nodes and namespace nodes are treated specially:
All attribute nodes for a certain element node have the _same_
ordinal index. All namespace nodes for a certain element node
have the _same_ ordinal index.
<p>
(So ord_number x = ord_number y does not imply x == y for these
nodes. However, this is true for the other node types.)
It is not recommended to work with the ordinal number directly but
to call ord_compare which already handles the special cases.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALord_compare"></a>ord_compare : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEord_index">ord_index</a> -><br> 'a <a href="Pxp_document.node.html">node</a> -> 'a <a href="Pxp_document.node.html">node</a> -> int</code></pre><div class="info">
<code class="code">ord_compare idx n1 n2</code>:
Compares two nodes like <code class="code">compare</code>:
Returns -1 if <code class="code">n1</code> occurs before <code class="code">n2</code>, or +1 if <code class="code">n1</code> occurs
after <code class="code">n2</code>, or 0 if both nodes are identical.
If one of the nodes does not occur in the ordinal index, <code class="code"><span class="constructor">Not_found</span></code>
is raised. (Note that this is a different behaviour than what <code class="code">compare</code>
would do.)
<p>
This test is much faster than <code class="code">compare</code>.<br>
</div>
<br>
<a name="iterators"></a>
<h2>Document iterators</h2><br>
<br>
General note: The iterators ignore attribute and namespace nodes<br>
<pre><span class="keyword">val</span> <a name="VALfind"></a>find : <code class="type">?deeply:bool -><br> (('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> bool) -><br> 'a <a href="Pxp_document.node.html">node</a> -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">find ~deeply f startnode</code>
Searches the first node in the tree below <code class="code">startnode</code> for which
the predicate f is true, and returns it. Raises <code class="code"><span class="constructor">Not_found</span></code>
if there is no such node.
<p>
By default, <code class="code">~deeply=<span class="keyword">false</span></code>. In this case, only the children of
<code class="code">startnode</code> are searched.
<p>
If passing <code class="code">~deeply=<span class="keyword">true</span></code>, the children are searched recursively
(depth-first search). Note that even in this case <code class="code">startnode</code> itself
is not checked.
<p>
Attribute and namespace nodes are ignored.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfind_all"></a>find_all : <code class="type">?deeply:bool -><br> (('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> bool) -><br> 'a <a href="Pxp_document.node.html">node</a> -> 'a <a href="Pxp_document.node.html">node</a> list</code></pre><div class="info">
<code class="code">find_all ~deeply f startnode</code>:
Searches all nodes in the tree below <code class="code">startnode</code> for which
the predicate f is true, and returns them.
<p>
By default, <code class="code">~deeply=<span class="keyword">false</span></code>. In this case, only the children of
<code class="code">startnode</code> are searched.
<p>
If passing <code class="code">~deeply=<span class="keyword">true</span></code>, the children are searched recursively
(depth-first search). Note that even in this case <code class="code">startnode</code> itself
is not checked.
<p>
Attribute and namespace nodes are ignored.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfind_element"></a>find_element : <code class="type">?deeply:bool -><br> string -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">find_element ~deeply eltype startnode</code>:
Searches the first element in the tree below <code class="code">startnode</code>
that has the element type <code class="code">eltype</code>, and returns it. Raises <code class="code"><span class="constructor">Not_found</span></code>
if there is no such node.
<p>
By default, <code class="code">~deeply=<span class="keyword">false</span></code>. In this case, only the children of
<code class="code">startnode</code> are searched.
<p>
If passing <code class="code">~deeply=<span class="keyword">true</span></code>, the children are searched recursively
(depth-first search). Note that even in this case <code class="code">startnode</code> itself
is not checked.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfind_all_elements"></a>find_all_elements : <code class="type">?deeply:bool -><br> string -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> 'a <a href="Pxp_document.node.html">node</a> list</code></pre><div class="info">
<code class="code">find_all_elements ~deeply eltype startnode</code>:
Searches all elements in the tree below <code class="code">startnode</code>
having the element type <code class="code">eltype</code>, and returns them.
<p>
By default, <code class="code">~deeply=<span class="keyword">false</span></code>. In this case, only the children of
<code class="code">startnode</code> are searched.
<p>
If passing <code class="code">~deeply=<span class="keyword">true</span></code>, the children are searched recursively
(depth-first search). Note that even in this case <code class="code">startnode</code> itself
is not checked.<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONSkip"></a>Skip</pre>
<div class="info">
This exception can be used in the functions passed to
<code class="code">map_tree</code>, <code class="code">map_tree_sibl</code>, <code class="code">iter_tree</code>, and <code class="code">iter_tree_sibl</code>
to skip the current node, and to proceed with the next node.
See these function for details.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALmap_tree"></a>map_tree : <code class="type">pre:(('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> ('b <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'b) <a href="Pxp_document.node.html">node</a>) -><br> ?post:('b <a href="Pxp_document.node.html">node</a> -> 'b <a href="Pxp_document.node.html">node</a>) -><br> 'a <a href="Pxp_document.node.html">node</a> -> 'b <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">map_tree ~pre ~post startnode</code>
Maps the tree beginning at <code class="code">startnode</code> to a second tree
using the following algorithm.
<p>
<code class="code">startnode</code> and the whole tree below it are recursively traversed.
After entering a node, the function ~pre is called. The result of
this function must be a new node; it must not have children nor a
parent. For example, you can pass
<pre></pre><code class="code">~pre:(<span class="keyword">fun</span> n <span class="keywordsign">-></span> n <span class="keywordsign">#</span> orphaned_flat_clone)</code><pre></pre>
to copy the original node. After that, the children are processed
in the same way (from left to right) resulting in a list of
mapped children. These are added to the mapped node as its
children.
<p>
Now, the ~post function is invoked with the mapped node as argument, and
the result is the result of the function (~post should return a root
node, too; if not specified, the identity is the ~post function).
<p>
Both ~pre and ~post may raise <code class="code"><span class="constructor">Skip</span></code> which causes that the node is
left out (i.e. the mapped tree does neither contain the node nor
any children of the node).
If the top node is skipped, the exception <code class="code"><span class="constructor">Not_found</span></code> is
raised.
<p>
For example, the following piece of code duplicates a tree, but
removes all comment nodes:
<p>
<pre></pre><code class="code"> map_tree ~pre:(<span class="keyword">fun</span> n <span class="keywordsign">-></span> <span class="keyword">if</span> n <span class="keywordsign">#</span> node_type = <span class="constructor">T_comment</span> <span class="keyword">then</span> raise <span class="constructor">Skip</span> <span class="keyword">else</span> n <span class="keywordsign">#</span> orphaned_flat_clone) startnode </code><pre></pre>
<p>
Attribute and namespace nodes are ignored.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALmap_tree_sibl"></a>map_tree_sibl : <code class="type">pre:(('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a><br> option -><br> 'a <a href="Pxp_document.node.html">node</a> -><br> 'a <a href="Pxp_document.node.html">node</a> option -><br> ('b <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'b) <a href="Pxp_document.node.html">node</a>) -><br> ?post:('b <a href="Pxp_document.node.html">node</a> option -><br> 'b <a href="Pxp_document.node.html">node</a> -><br> 'b <a href="Pxp_document.node.html">node</a> option -> 'b <a href="Pxp_document.node.html">node</a>) -><br> 'a <a href="Pxp_document.node.html">node</a> -> 'b <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">map_tree_sibl ~pre ~post startnode</code>:
Maps the tree beginning at <code class="code">startnode</code> to a second tree
using the following algorithm.
<p>
<code class="code">startnode</code> and the whole tree below it are recursively traversed.
After entering a node, the function ~pre is called with three
arguments: some previous node, the current node, and some next node.
The previous and the next node may not exist because the current
node is the first or the last in the current list of nodes.
In this case, <code class="code"><span class="constructor">None</span></code> is passed as previous or next node, resp.
The result of this function invocation must be a new node;
it must not have children nor a parent. For example, you can pass
<pre></pre><code class="code">~pre:(<span class="keyword">fun</span> prev n next <span class="keywordsign">-></span> n <span class="keywordsign">#</span> orphaned_flat_clone)</code><pre></pre>
to copy the original node. After that, the children are processed
in the same way (from left to right) resulting in a list of
mapped children.
<p>
Now, the ~post function is applied to the list of mapped children
resulting in a list of postprocessed children. (Note: this part
works rather differently than <code class="code">map_tree</code>.) ~post has three arguments:
some previous child, the current child, and some next child.
The previous and the next child are <code class="code"><span class="constructor">None</span></code> if non-existing.
The postprocessed children are appended to the mapped node resulting
in the mapped tree.
<p>
Both ~pre and ~post may raise <code class="code"><span class="constructor">Skip</span></code> which causes that the node is
left out (i.e. the mapped tree does neither contain the node nor
any children of the node).
If the top node is skipped, the exception <code class="code"><span class="constructor">Not_found</span></code> is
raised.
<p>
Attribute and namespace nodes are ignored.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALiter_tree"></a>iter_tree : <code class="type">?pre:(('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> unit) -><br> ?post:('a <a href="Pxp_document.node.html">node</a> -> unit) -> 'a <a href="Pxp_document.node.html">node</a> -> unit</code></pre><div class="info">
<code class="code">iter_tree ~pre ~post startnode</code>:
Iterates over the tree beginning at <code class="code">startnode</code>
using the following algorithm.
<p>
<code class="code">startnode</code> and the whole tree below it are recursively traversed.
After entering a node, the function ~pre is called. Now, the children
are processed recursively. Finally, the ~post function is invoked.
<p>
The ~pre function may raise <code class="code"><span class="constructor">Skip</span></code> causing that the children
and the invocation of the ~post function are skipped.
If the ~post function raises <code class="code"><span class="constructor">Skip</span></code> nothing special happens.
<p>
Attribute and namespace nodes are ignored.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALiter_tree_sibl"></a>iter_tree_sibl : <code class="type">?pre:(('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a><br> option -> 'a <a href="Pxp_document.node.html">node</a> -> 'a <a href="Pxp_document.node.html">node</a> option -> unit) -><br> ?post:('a <a href="Pxp_document.node.html">node</a> option -><br> 'a <a href="Pxp_document.node.html">node</a> -> 'a <a href="Pxp_document.node.html">node</a> option -> unit) -><br> 'a <a href="Pxp_document.node.html">node</a> -> unit</code></pre><div class="info">
<code class="code">iter_tree_sibl ~pre ~post startnode</code>:
Iterates over the tree beginning at <code class="code">startnode</code>
using the following algorithm.
<p>
<code class="code">startnode</code> and the whole tree below it are recursively traversed.
After entering a node, the function ~pre is called with three
arguments: some previous node, the current node, and some next node.
The previous and the next node may be <code class="code"><span class="constructor">None</span></code> if non-existing.
Now, the children are processed recursively.
Finally, the ~post function is invoked with the same three
arguments.
<p>
The ~pre function may raise <code class="code"><span class="constructor">Skip</span></code> causing that the children
and the invocation of the ~post function are skipped.
If the ~post function raises <code class="code"><span class="constructor">Skip</span></code> nothing special happens.
<p>
Attribute and namespace nodes are ignored.<br>
</div>
<br>
<a name="2_Whitespace"></a>
<h2>Whitespace</h2><br>
<pre><span class="keyword">type</span> <a name="TYPEstripping_mode"></a><code class="type"></code>stripping_mode = <code class="type">[ `Disabled | `Strip_one | `Strip_one_lf | `Strip_seq ]</code> </pre>
<div class="info">
The different ways how to strip whitespace from a single
data node:<ul>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Strip_one_lf</span></code>: If there is a linefeed character at the beginning/at
the end, it will be removed. If there are more linefeed characters,
only the first/the last is removed.
(This is the SGML rule to strip whitespace.)</li>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Strip_one</span></code>: If there is a whitespace character at the beginning/at
the end, it will be removed. If there are more whitespace characters,
only the first/the last is removed. Whitespace characters are space,
newline, carriage return, and tab.</li>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Strip_seq</span></code>: All whitespace characters at the beginning/at the end are
removed.</li>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Disabled</span></code>: Do not strip whitespace.</li>
</ul>
<br>
</div>
<pre><span class="keyword">val</span> <a name="VALstrip_whitespace"></a>strip_whitespace : <code class="type">?force:bool -><br> ?left:<a href="Pxp_document.html#TYPEstripping_mode">stripping_mode</a> -><br> ?right:<a href="Pxp_document.html#TYPEstripping_mode">stripping_mode</a> -><br> ?delete_empty_nodes:bool -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> unit</code></pre><div class="info">
<code class="code">strip_whitespace ~force ~left ~right ~delete_empty_nodes startnode</code>:
Modifies the passed tree in-place by the following rules:<ul>
<li>In general, whitespace stripping is not applied to nodes inside
an <code class="code">xml:space=<span class="string">"preserve"</span></code> region, unless <code class="code">~force:<span class="keyword">true</span></code> is passed
to the function (default is <code class="code">~force:<span class="keyword">false</span></code>). Only if whitespace
stripping is allowed, the following rules are carried out.
Note that the detection of regions with preserved whitespace takes
the parent nodes of the passed <code class="code">startnode</code> into account.</li>
<li>If applied to a data node, whitespace at the beginning of the node
is removed according to <code class="code">~left</code>, and whitespace at the end of the node
is removed according to <code class="code">~right</code>.</li>
<li>If applied to an element, whitespace at the beginning of the first
data subnode is removed according to <code class="code">~left</code>, and whitespace at the end
of the last data subnode is removed according to <code class="code">~right</code>. Furthermore,
these rules are recursively applied to all subelements (but not to
other node types).</li>
<li>If applied to the super root node, this node is treated as if it
were an element.</li>
<li>Whitespace of other node types is left as-is, as whitespace occuring
in attributes.</li>
<li>Option <code class="code">~delete_empty_nodes</code> (default true):
If data nodes become empty after removal of whitespace, they are
deleted from the XML tree. </li>
</ul>
Defaults:<ul>
<li><code class="code">~force:<span class="keyword">false</span></code></li>
<li><code class="code">~left:<span class="keywordsign">`</span><span class="constructor">Disabled</span></code></li>
<li><code class="code">~right:<span class="keywordsign">`</span><span class="constructor">Disabled</span></code></li>
</ul>
<br>
</div>
<br>
<a name="2_Normalization"></a>
<h2>Normalization</h2><br>
<pre><span class="keyword">val</span> <a name="VALnormalize"></a>normalize : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> unit</code></pre><div class="info">
Normalizes the tree denoted by <code class="code">startnode</code> such that
neither empty data nodes nor adjacent data nodes exist. Normalization
works in-place.
<p>
The tree parsers always return normalized trees. This function may
still be useful to enforce normalized trees after modifying them.<br>
</div>
<br>
<a name="2_Validation"></a>
<h2>Validation</h2><br>
<pre><span class="keyword">val</span> <a name="VALvalidate"></a>validate : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> unit</code></pre><div class="info">
<code class="code">validate startnode</code>:
Validates the tree denoted by <code class="code">startnode</code>. In contrast to
<code class="code">startnode <span class="keywordsign">#</span> validate()</code> this function validates recursively.<br>
</div>
<br>
<a name="2_Thedocumentcontainer"></a>
<h2>The document container</h2><br>
<pre><span class="keyword">class</span> <a name="TYPEdocument"></a><code class="type">['a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a]</code> <a href="Pxp_document.document.html">document</a> : <code class="type">?swarner:<a href="Pxp_types.html#TYPEsymbolic_warnings">Pxp_types.symbolic_warnings</a> -> <a href="Pxp_types.html#TYPEcollect_warnings">Pxp_types.collect_warnings</a> -> <a href="Pxp_types.html#TYPErep_encoding">Pxp_types.rep_encoding</a> -> </code><code class="code"><span class="keyword">object</span></code> <a href="Pxp_document.document.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
Documents are used to represent closed documents that may
consist of an XML declaration, a DTD, and a node tree.
</div>
<br>
<a name="2_Printersforthetoploop"></a>
<h2>Printers for the toploop</h2><br>
<br>
These functions are intented to be used with the <code class="code"><span class="keywordsign">#</span>install_printer</code>
directive of the toploop<br>
<pre><span class="keyword">val</span> <a name="VALprint_node"></a>print_node : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.node.html">node</a> -><br> unit</code></pre><pre><span class="keyword">val</span> <a name="VALprint_doc"></a>print_doc : <code class="type">('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.document.html">document</a> -><br> unit</code></pre><br>
<a name="2_Conversionbetweentreesandeventstreams"></a>
<h2>Conversion between trees and event streams</h2><br>
<br>
We use the metaphor of "solid" XML for trees and other randomly accessible
data structures representing XML, and the metaphor of "liquid" XML
for event streams describing XML<br>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONError_event"></a>Error_event <span class="keyword">of</span> <code class="type">exn</code></pre>
<div class="info">
The event stream contains an <code class="code"><span class="constructor">E_error</span></code> event<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEsolid_xml"></a><code class="type">'a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a</code> solid_xml = <code class="type">[ `Document of 'a <a href="Pxp_document.document.html">document</a> | `Node of 'a <a href="Pxp_document.node.html">node</a> ]</code> </pre>
<div class="info">
Solid XML can be a (sub)tree <code class="code"><span class="keywordsign">`</span><span class="constructor">Node</span> n</code>, or a closed <code class="code"><span class="keywordsign">`</span><span class="constructor">Document</span></code><br>
</div>
<pre><span class="keyword">val</span> <a name="VALsolidify"></a>solidify : <code class="type">?dtd:<a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -><br> <a href="Pxp_types.html#TYPEconfig">Pxp_types.config</a> -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEspec">spec</a> -><br> (unit -> <a href="Pxp_types.html#TYPEevent">Pxp_types.event</a> option) -> 'a <a href="Pxp_document.html#TYPEsolid_xml">solid_xml</a></code></pre><div class="info">
Reads the event stream by calling the <code class="code">unit<span class="keywordsign">-></span>event</code> function, and
creates a node tree according to config, dtd, spec.
<p>
The event stream may be either:<ul>
<li>A document event stream (as generated by <code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_document</span></code>).
In this case <code class="code"><span class="keywordsign">`</span><span class="constructor">Document</span> d</code> is returned.</li>
<li>A content event stream with top-level element (as generated by
<code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_element_content</span></code>).
In this case <code class="code"><span class="keywordsign">`</span><span class="constructor">Node</span> n</code> is returned.</li>
</ul>
Note that there is no way to solidify a content event stream
that does not have a single top-level element (i.e. as parsed by
<code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_content</span></code>). An attempt will result in an exception.
<p>
Document streams contain a DTD. The found DTD is used for the
node tree. Content streams, on the contrary, do not contain DTDs.
In this case, an empty DTD is created (in well-formedness mode).
<p>
The <code class="code">dtd</code> argument overrides any DTD, no matter whether found
in the stream or freshly created.
<p>
If the DTD allows validation, the returned tree is validated.
<p>
The data nodes are not normalized unless the arriving data events
are already normalized. To get this effect, filter the stream
with <a href="Pxp_event.html#VALnorm_cdata_filter"><code class="code"><span class="constructor">Pxp_event</span>.norm_cdata_filter</code></a> before calling solidify.
<p>
Ignorable whitespace is not automatically removed. To get this
effect, filter the stream with
<a href="Pxp_event.html#VALdrop_ignorable_whitespace_filter"><code class="code"><span class="constructor">Pxp_event</span>.drop_ignorable_whitespace_filter</code></a> before calling solidify.
<p>
The uniqueness of ID attributes is not checked.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALliquefy"></a>liquefy : <code class="type">?omit_end:bool -><br> ?omit_positions:bool -><br> ('a <a href="Pxp_document.node.html">node</a> #<a href="Pxp_document.extension.html">extension</a> as 'a) <a href="Pxp_document.html#TYPEsolid_xml">solid_xml</a> -><br> 'b -> <a href="Pxp_types.html#TYPEevent">Pxp_types.event</a> option</code></pre><div class="info">
The converse of <code class="code">solidify</code>: The passed node or document is transformed
into an event stream.
<p>
<ul>
<li><code class="code">omit_end</code>: If true, the <code class="code"><span class="constructor">E_end_of_stream</span></code> event is omitted at the end.
Useful to concatenate several streams. Default: false.</li>
<li><code class="code">omit_positions</code>: If true, no <code class="code"><span class="constructor">E_position</span></code> events are generated.
Default:false.</li>
</ul>
<br>
</div>
<br>
<br>
</body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d9c1887ff364dc87e282490223567c41
>
files
>
145
