<!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_document.extension.html">
<link rel="Up" href="Pxp_document.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"><title>PXP Reference : Pxp_document.node</title>
</head>
<body>
<div class="navbar"><a href="Pxp_document.extension.html">Previous</a>
<a href="Pxp_document.html">Up</a>
</div>
<center><h1>Class type <a href="type_Pxp_document.node.html">Pxp_document.node</a></h1></center>
<br>
<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> node = <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>The class type <code class="code">node</code> defines the interface of the nodes that are part
of XML document trees. For an introduction into trees, see
<a href="Intro_trees.html"><code class="code"><span class="constructor">Intro_trees</span></code></a>.
<p>
The interface of the nodes as such cannot be extended by the user.
There is, however, the possibility of defining a so-called extension
which is reflected in the type parameter <code class="code"><span class="keywordsign">'</span>ext</code>, and which can be
any class type that is a subtype of <a href="Pxp_document.extension.html"><code class="code"><span class="constructor">Pxp_document</span>.extension</code></a>.
Note that also the extension has a type parameter pointing to the
node class. Closed node types look thus like
<p>
<pre></pre><code class="code"> <span class="keyword">type</span> my_node = my_node extension node </code><pre></pre>
<p>
which is a rare form of a recursive type.<br>
<hr width="100%">
<a name="2_Domain"></a>
<h2>Domain</h2>
<p>
Every node has a node type which is returned by the <code class="code">node_type</code>
method below. Depending on the node type, not all methods are
defined. If a method is undefined for certain node types, this
is documented below, and also any unusual reaction when the
methods are called nevertheless. The standard rection is to raise
either the exception
<a href="Pxp_types.html#EXCEPTIONMethod_not_applicable"><code class="code"><span class="constructor">Pxp_types</span>.<span class="constructor">Method_not_applicable</span></code></a> or
<a href="Pxp_types.html#EXCEPTIONNamespace_method_not_applicable"><code class="code"><span class="constructor">Pxp_types</span>.<span class="constructor">Namespace_method_not_applicable</span></code></a> for namespace-specific
methods.<a name="2_Validation"></a>
<h2>Validation</h2>
<p>
Some methods modify the tree. This may violate the DTD. Because of this,
it is documented for every mutating method which validation checks are
performed.<a name="2_GeneralInterface"></a>
<h2>General Interface</h2><pre><span class="keyword">method</span> <a name="METHODextension"></a>extension : <code class="type">'a</code></pre><div class="info">
Returns the extension object of this node.
<p>
<b>Domain.</b>
Applicable to element, data, comment, processing instruction,
and super root nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnode_type"></a>node_type : <code class="type"><a href="Pxp_document.html#TYPEnode_type">node_type</a></code></pre><div class="info">
Returns the type of the node:<ul>
<li><code class="code"><span class="constructor">T_element</span> t</code>: The node is an element with name <code class="code">t</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_comment</span></code>: The node is a comment node</li>
<li><code class="code"><span class="constructor">T_pinstr</span> n</code>: The node is a processing instruction with
target <code class="code">n</code></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_attribute</span> n</code>: The node is an attribute with name <code class="code">n</code></li>
<li><code class="code"><span class="constructor">T_namespace</span> p</code>: The node is a namespace with normalized prefix <code class="code">p</code></li>
</ul>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODdtd"></a>dtd : <code class="type"><a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a></code></pre><div class="info">
Returns the DTD. Note that the DTD object is the same for all
nodes of the same tree, and that the DTD object even exists when
validation is turned off (well-formedness mode).
<p>
<b>Domein.</b> All node types. However, exemplars need not to have
an associated DTD, in which case this method fails.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODencoding"></a>encoding : <code class="type"><a href="Pxp_types.html#TYPErep_encoding">Pxp_types.rep_encoding</a></code></pre><div class="info">
Get the encoding which is always the same as the encoding of
the DTD. See also method <code class="code">dtd</code>. (Note: This method fails, too, if
no DTD is present.)
<p>
<b>Domain.</b> All node types. Note that exemplars need not to have
an associated DTD, in which case this method fails.<br>
</div>
<a name="2_NavigationInterface"></a>
<h2>Navigation Interface</h2><pre><span class="keyword">method</span> <a name="METHODparent"></a>parent : <code class="type">'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
Get the parent node, or raise <code class="code"><span class="constructor">Not_found</span></code> if this node is
a root node. For attribute and namespace nodes, the parent is
artificially defined as the element to which these nodes apply.
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODroot"></a>root : <code class="type">'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
Gets the root node of the tree.
Every node is contained in a tree with a root, so this method always
succeeds. Note that this method searches for the root,
which costs time proportional to the length of the path to the root.
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnode_position"></a>node_position : <code class="type">int</code></pre><div class="info">
Returns the position of this node in the list of all children of
the parent
node. Positions are counted from 0 on. There are several cases:<ul>
<li>The regular nodes get positions from <code class="code">0</code> to <code class="code">l-1</code> where <code class="code">l</code> is the
length of the list of regular children.</li>
<li>Attribute nodes and namespace nodes are irregular nodes,
which means here that their positions are counted seperately.
All attribute nodes have positions from <code class="code">0</code> to <code class="code">m-1</code>; all namespace
nodes have positions from <code class="code">0</code> to <code class="code">n-1</code>.</li>
<li>If this node is a root, this method raises <code class="code"><span class="constructor">Not_found</span></code>.</li>
</ul>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnode_path"></a>node_path : <code class="type">int list</code></pre><div class="info">
Returns the list of node positions describing
the location of this node in the whole tree. The list describes
the path from the root node down to this node; the first path
element is the index of the child of the root, the second path
element is the index of the child of the child, and so on, and
the last path element is the index of this node. The method returns
the empty list if this node is the root node.
<p>
Attribute and namespace nodes are not part of the regular tree, so
there is a special rule for them. Attribute nodes of an element
node <code class="code">x</code> have the node path <code class="code">x <span class="keywordsign">#</span> node_path @ [-1; p]</code> where
<code class="code">p</code> is the position of the attribute node. Namespace nodes of an
element node <code class="code">x</code> have the node path <code class="code">x <span class="keywordsign">#</span> node_path @ [-2; p]</code>
where <code class="code">p</code> is the position of the namespace node.
Note that this definition respects the document order.
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODsub_nodes"></a>sub_nodes : <code class="type">'a <a href="Pxp_document.node.html">node</a> list</code></pre><div class="info">
Returns the regular children of the node as list. Only
elements, data nodes, comments, and processing instructions can
occur in this list; attributes and namespace nodes are not
considered as regular nodes, and super root nodes can only
be root nodes and will never be children of another node.
The returned list is always empty if this node is a data node,
comment, processing instruction, attribute, or namespace.
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODiter_nodes"></a>iter_nodes : <code class="type">('a <a href="Pxp_document.node.html">node</a> -> unit) -> unit</code></pre><div class="info">
<code class="code">obj<span class="keywordsign">#</span>iter_nodes f</code> iterates over the regular children of <code class="code">obj</code>, and
calls the function <code class="code">f</code> for every child <code class="code">ch</code> as <code class="code">f ch</code>. The
regular children are the nodes returned by <code class="code">sub_nodes</code>, see
there for an explanation.
<p>
See also <a href="Pxp_document.html#iterators"><i>Document iterators</i></a> for more functions iterating over
trees.
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODiter_nodes_sibl"></a>iter_nodes_sibl : <code class="type">('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> unit</code></pre><div class="info">
<code class="code">obj<span class="keywordsign">#</span>iter_nodes f</code> iterates over the regular children of <code class="code">obj</code>, and
calls the function <code class="code">f</code> for every child as <code class="code">f pred ch succ</code>:<ul>
<li><code class="code">ch</code> is the child</li>
<li><code class="code">pred</code> is <code class="code"><span class="constructor">None</span></code> if the child is the first in the list,
and <code class="code"><span class="constructor">Some</span> p</code> otherwise; <code class="code">p</code> is the predecessor of <code class="code">ch</code></li>
<li><code class="code">succ</code> is <code class="code"><span class="constructor">None</span></code> if the child is the last in the list,
and <code class="code"><span class="constructor">Some</span> s</code> otherwise; <code class="code">s</code> is the successor of <code class="code">ch</code></li>
</ul>
The
regular children are the nodes returned by <code class="code">sub_nodes</code>, see
there for an explanation.
<p>
See also <a href="Pxp_document.html#iterators"><i>Document iterators</i></a> for more functions iterating over
trees.
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnth_node"></a>nth_node : <code class="type">int -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">nth_node n</code> returns the n-th regular child, <code class="code">n >= 0</code>.
Raises <code class="code"><span class="constructor">Not_found</span></code> if the index <code class="code">n</code> is out of the valid range.
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODprevious_node"></a>previous_node : <code class="type">'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
Returns the predecessor of this node
in the list of regular children of the parent, or raise <code class="code"><span class="constructor">Not_found</span></code>
if this node is the first child. This is equivalent to
<code class="code">obj <span class="keywordsign">#</span> parent <span class="keywordsign">#</span> nth_node (obj <span class="keywordsign">#</span> node_position - 1)</code> (when <code class="code">obj</code>
is this node).
<p>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnext_node"></a>next_node : <code class="type">'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
Returns the successor of this node
in the list of regular children of the parent, or raise <code class="code"><span class="constructor">Not_found</span></code>
if this node is the last child. This is equivalent to
<code class="code">obj <span class="keywordsign">#</span> parent <span class="keywordsign">#</span> nth_node (obj <span class="keywordsign">#</span> node_position + 1)</code> (when <code class="code">obj</code>
is this node).
<p>
<b>Domain.</b> All node types.<br>
</div>
<a name="2_Gettingcontentsandattributes"></a>
<h2>Getting contents and attributes</h2>
<p>
Also see the <a href="Pxp_document.node.html#METHODnode_type"><code class="code"><span class="constructor">Pxp_document</span>.node.node_type</code></a> method which returns
the type of the node, and for elements their names.<pre><span class="keyword">method</span> <a name="METHODdata"></a>data : <code class="type">string</code></pre><div class="info">
This method returns what is considered as
the data of the node which depends on the node type:<ul>
<li>Data nodes: the method returns the character string the node
represents</li>
<li>Element nodes, super root nodes: the method returns the
concatenated character strings of all (direct or indirect)
data nodes below this node</li>
<li>Comment nodes: the method returns the
comment string (without delimiters), or it raises <code class="code"><span class="constructor">Not_found</span></code>
if the comment string is not set (see also the <code class="code">comment</code> method
below for an alternate way of getting the comment string)</li>
<li>Processing instructions: the
method returns the data part of the instruction, or <code class="code"><span class="string">""</span></code>
if the data part is missing (see also the <code class="code">pinstr</code> method
below for an alternay way of accessing processing instructions)</li>
<li>Attribute nodes: the method returns the attribute
value as string, or it raises <code class="code"><span class="constructor">Not_found</span></code> if the attribute
is implied.</li>
<li>Namespace nodes: the method returns the namespace
URI</li>
</ul>
<b>Domain.</b> All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODattribute"></a>attribute : <code class="type">string -> <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a></code></pre><div class="info">
<code class="code">attribute name</code> returns the value of the attribute <code class="code">name</code>.
<p>
If the parser is in validating mode, the method returns
values for declared attributes, and it raises <code class="code"><span class="constructor">Not_found</span></code> for any
undeclared attribute. Note that it even returns a value if the
attribute is actually missing but is declared as <code class="code"><span class="keywordsign">#</span><span class="constructor">IMPLIED</span></code> or
has a default value.
<p>
If the parser (more precisely, the DTD object) is in
well-formedness mode, the method returns only values for
defined attributes that occur literally in the XML text, and it
raises <code class="code"><span class="constructor">Not_found</span></code> for any
unknown attribute name.
<p>
Possible return values are:
<ul>
<li> <code class="code"><span class="constructor">Implied_value</span></code>: The attribute has been declared with the
keyword <code class="code"><span class="keywordsign">#</span><span class="constructor">IMPLIED</span></code>, and the attribute definition is missing
in the attribute list of the element.</li>
<li> <code class="code"><span class="constructor">Value</span> s</code>: The attribute has been declared as type <code class="code"><span class="constructor">CDATA</span></code>,
as <code class="code"><span class="constructor">ID</span></code>, as <code class="code"><span class="constructor">IDREF</span></code>, as <code class="code"><span class="constructor">ENTITY</span></code>, or as <code class="code"><span class="constructor">NMTOKEN</span></code>, or as
enumeration or notation, and one of the two conditions holds:
(1) The attribute value is defined in the attribute list in
which case this value is returned in the string <code class="code">s</code>. (2) The
attribute has been omitted, and the DTD declares the attribute
with a default value. The default value is returned in <code class="code">s</code>.
<p>
Summarized, <code class="code"><span class="constructor">Value</span> s</code> is returned for non-implied, non-list
attribute values.
<p>
Furthermore, <code class="code"><span class="constructor">Value</span> s</code> is returned for non-declared attributes
if the DTD object allows this, for instance, if the DTD
object specifies well-formedness mode.</li>
<li> <code class="code"><span class="constructor">Valuelist</span> l</code>: The attribute has been declared as type
<code class="code"><span class="constructor">IDREFS</span></code>, as <code class="code"><span class="constructor">ENTITIES</span></code>, or <code class="code"><span class="constructor">NMTOKENS</span></code>, and one of the two
conditions holds: (1) The attribute value is defined in the
attribute list in which case the space-separated tokens of
the value are returned in the string list <code class="code">l</code>. (2) The
attribute has been omitted, and the DTD declares the attribute
with a default value. The default value is returned in <code class="code">l</code>.
<p>
Summarized, <code class="code"><span class="constructor">Valuelist</span> l</code> is returned for all list-type
attribute values.</li>
</ul>
<p>
Note that before the attribute value is returned, the value is
normalized. This means that newlines are converted to spaces, and
that references to character entities (i.e. <code class="code"><span class="keywordsign">&</span><span class="keywordsign">#</span>n;</code>) and
general entities (i.e. <code class="code"><span class="keywordsign">&</span>name;</code>) are expanded; if necessary,
the expansion is performed recursively.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return values, all other node types always raise <code class="code"><span class="constructor">Not_found</span></code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODattribute_names"></a>attribute_names : <code class="type">string list</code></pre><div class="info">
Returns the list of all attribute names of this element.
In validating mode, this list is simply the list of declared
attributes. In well-formedness mode, this list is the list of
defined attributes that occur literally in the XML text.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return a non-empty list, all other node types always return
the empty list.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODattribute_type"></a>attribute_type : <code class="type">string -> <a href="Pxp_types.html#TYPEatt_type">Pxp_types.att_type</a></code></pre><div class="info">
<code class="code">attribute_type name</code>: returns the type of the attribute <code class="code">name</code>.
If the attribute
is declared, the declared type is returned. If the attribute is
defined but undeclared, the type <code class="code"><span class="constructor">A_cdata</span></code> will be returned.
(The module <code class="code"><span class="constructor">Pxp_types</span></code> contains the Caml type of attribute types.)
This method raises <code class="code"><span class="constructor">Not_found</span></code> if the attribute is unknown.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return values, all other node types always raise <code class="code"><span class="constructor">Not_found</span></code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODattributes"></a>attributes : <code class="type">(string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list</code></pre><div class="info">
Returns the list of <code class="code">(name,value)</code> pairs describing
all attributes (declared attributes plus defined attributes).
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return non-empty values, all other node types always
return the empty list.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODrequired_string_attribute"></a>required_string_attribute : <code class="type">string -> string</code></pre><div class="info">
<code class="code">required_string_attribute name</code>:
Returns the value of the attribute <code class="code">name</code> as string,
i.e. if the value of the attribute is <code class="code"><span class="constructor">Value</span> s</code>, this method
will return simply <code class="code">s</code>, and if the value is <code class="code"><span class="constructor">Valuelist</span> l</code>,
this method will return the elements of <code class="code">l</code> separated by
spaces. If the attribute value is <code class="code"><span class="constructor">Implied_value</span></code>, the method
will fail.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return values, all other node types always fail.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODrequired_list_attribute"></a>required_list_attribute : <code class="type">string -> string list</code></pre><div class="info">
<code class="code">required_list_attribute name</code>:
Returns the value of the attribute <code class="code">name</code> as string list,
i.e. if the value of the attribute is <code class="code"><span class="constructor">Valuelist</span> l</code>, this method
will return simply <code class="code">l</code>, and if the value is <code class="code"><span class="constructor">Value</span> s</code>,
this method will return the one-element list <code class="code">[[s]]</code>.
If the attribute value is <code class="code"><span class="constructor">Implied_value</span></code>, the method
will fail.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return values, all other node types always fail.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODoptional_string_attribute"></a>optional_string_attribute : <code class="type">string -> string option</code></pre><div class="info">
<code class="code">optional_string_attribute name</code>:
Returns the value of the attribute <code class="code">name</code> as optional string,
i.e. if the value of the attribute is <code class="code"><span class="constructor">Value</span> s</code>, this method
will return <code class="code"><span class="constructor">Some</span> s</code>, and if the value is <code class="code"><span class="constructor">Valuelist</span> l</code>,
this method will return <code class="code"><span class="constructor">Some</span> s</code> where <code class="code">s</code> consists of the
concatenated elements of <code class="code">l</code> separated by spaces. If the
attribute value is <code class="code"><span class="constructor">Implied_value</span></code>, the method will return <code class="code"><span class="constructor">None</span></code>.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return <code class="code"><span class="constructor">Some</span></code> values, all other node types always return <code class="code"><span class="constructor">None</span></code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODoptional_list_attribute"></a>optional_list_attribute : <code class="type">string -> string list</code></pre><div class="info">
<code class="code">optional_list_attribute name</code>:
Returns the value of the attribute <code class="code">name</code> as string list,
i.e. if the value of the attribute is <code class="code"><span class="constructor">Valuelist</span> l</code>, this method
will return simply <code class="code">l</code>, and if the value is <code class="code"><span class="constructor">Value</span> s</code>,
this method will return the one-element list <code class="code">[[s]]</code>.
If the attribute value is <code class="code"><span class="constructor">Implied_value</span></code>, the method
will return the empty list.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return non-empty values, all other node types always
return the empty list.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODid_attribute_name"></a>id_attribute_name : <code class="type">string</code></pre><div class="info">
Returns the name of the (at most one) attribute being
declared as type <code class="code"><span class="constructor">ID</span></code>. The method raises <code class="code"><span class="constructor">Not_found</span></code> if there
is no declared <code class="code"><span class="constructor">ID</span></code> attribute for the element type.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return names, all other node types always raise <code class="code"><span class="constructor">Not_found</span></code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODid_attribute_value"></a>id_attribute_value : <code class="type">string</code></pre><div class="info">
Returns the string value of the (at most one) attribute being
declared as type <code class="code"><span class="constructor">ID</span></code>. The method raises <code class="code"><span class="constructor">Not_found</span></code> if there
is no declared <code class="code"><span class="constructor">ID</span></code> attribute for the element type.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return names, all other node types always raise <code class="code"><span class="constructor">Not_found</span></code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODidref_attribute_names"></a>idref_attribute_names : <code class="type">string list</code></pre><div class="info">
Returns the names of the attributes being
declared as type <code class="code"><span class="constructor">IDREF</span></code> or <code class="code"><span class="constructor">IDREFS</span></code>.
<p>
<b>Domain.</b> All node types. However, only elements and attribute nodes
will return names, all other node types always return the empty
list.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODattributes_as_nodes"></a>attributes_as_nodes : <code class="type">'a <a href="Pxp_document.node.html">node</a> list</code></pre><div class="info">
Returns all attributes (i.e. declared plus defined
attributes) as a list of attribute nodes with node type
<code class="code"><span class="constructor">T_attribute</span> name</code>.
<p>
This method can be used if it is required for typing reasons
that the attributes have also type <code class="code">node</code>. A common example
are sets that may both contain elements and attributes, as they
are used in the XPath language.
<p>
The attribute nodes are read-only; any call to a method
modifying their contents will raise <code class="code"><span class="constructor">Method_not_applicable</span></code>.
In order to get the value of such an attribute node <code class="code">anode</code>,
one can invoke the method <code class="code">attribute</code>:
<p>
<pre></pre><code class="code">anode <span class="keywordsign">#</span> attribute name</code><pre></pre>
<p>
where <code class="code">name</code> is the name of the attribute represented by
<code class="code">anode</code>. This will return the attribute value as <code class="code">att_value</code>. Of
course, the other attribute accessors can be called as well.
Furthermore, the method <code class="code">data</code> will return the attribute value as
string. Of course, every attribute node only contains the value of the
one attribute it represents, and so it does not make sense to pass
names of other attributes to the access methods.
<p>
The attribute nodes live outside of the regular XML tree, and
they are not considered as children of the element node. However,
the element node is the parent node of the attribute nodes
(i.e. the children/parent relationship is asymmetric).
<p>
The method <code class="code">attributes_as_nodes</code> computes the list of attribute
nodes when it is first invoked after object creation or any
modification of the attribute list, and it will return the same list
again in subsequent invocations.
<p>
See also <a href="Intro_advanced.html#irrnodes"><i>Irregular nodes: namespace nodes and attribute nodes</i></a>.
<p>
<b>Domain.</b> This method is only applicable to elements.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODpinstr"></a>pinstr : <code class="type">string -> <a href="Pxp_dtd.proc_instruction.html">Pxp_dtd.proc_instruction</a> list</code></pre><div class="info">
<code class="code">pinstr n</code> returns all processing instructions that are
attached to this object and that have a target
specification of <code class="code">n</code>.
<p>
<b>Domain.</b> All node types. However, it is only reasonable to
call this method
for processing instruction nodes, and for elements; for all
other node types the method will return the empty list.
<p>
It depends on the parser configuration whether the processing
instructions are gathered in special processing instruction nodes
or in their containing elements. The former case is enabled when
the <code class="code">enable_pinstr_nodes</code> config option is in effect. When a
processing instruction is parsed, a new processing instruction
node is added to the tree, and the <code class="code">proc_instruction</code> object
is added to this node, and can be queried by calling this method.
<p>
If the mentioned config option is not active (which is the default),
the <code class="code">proc_instruction</code> object is attached to the containing
element, but does not become a regular child of the element.
Especially, the exact position of the instruction among the
children is not reflected in the tree.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODpinstr_names"></a>pinstr_names : <code class="type">string list</code></pre><div class="info">
Returns the targets of all processing instructions that are
attached to this object. The target is the first word
in the processing instruction. Use the <code class="code">pinstr</code> method to get
the full data of a processing instruction.
<p>
<b>Domain.</b> All node types. However, as for <code class="code">pinstr</code> only a few
types of nodes can be filled with processing instruction. See
the description at <a href="Pxp_document.node.html#METHODpinstr"><code class="code"><span class="constructor">Pxp_document</span>.node.pinstr</code></a> for details.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODcomment"></a>comment : <code class="type">string option</code></pre><div class="info">
Returns <code class="code"><span class="constructor">Some</span> text</code> if the node is a comment node and if
<code class="code">text</code> is the comment string (without the delimiters <code class="code"><!--</code> and
<code class="code">--></code>). Otherwise, <code class="code"><span class="constructor">None</span></code> is passed back.
<p>
Note: The <code class="code">data</code> method also returns the comment string, but it
raises <code class="code"><span class="constructor">Not_found</span></code> if the string is not available. This is the
only difference between these methods when called on comment
nodes.
<p>
<b>Domain.</b> All node types. Note that the method will always return
<code class="code"><span class="constructor">None</span></code> for non-comment nodes.<br>
</div>
<a name="2_Metadata"></a>
<h2>Meta data</h2><pre><span class="keyword">method</span> <a name="METHODentity_id"></a>entity_id : <code class="type"><a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a></code></pre><div class="info">
Returns the <code class="code">entity_id</code> object. This object identifies the entity
the node originates from. See <a href="Pxp_dtd.Entity.html"><code class="code"><span class="constructor">Pxp_dtd</span>.<span class="constructor">Entity</span></code></a> for functions
finding and accessing the entity.
<p>
<b>Domain.</b> All node types. Note that it is possible that one
gets an <code class="code">entity_id</code> that is not connected with a real entity,
e.g. because the node is programmatically constructed, and
does not result from parsing. But even the parser does not set
the <code class="code">entity_id</code> for all node kinds. Generally, the <code class="code">entity_id</code>
corresponds to a real entity only for element, attribute,
and processing instruction nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODposition"></a>position : <code class="type">string * int * int</code></pre><div class="info">
Returns a triple <code class="code">(entity,line,pos)</code> describing the
location of the element in the original XML text. This triple is
only available for elements, and only if the parser has been
configured to store positions (see parser option
<code class="code">store_element_positions</code>). If available, <code class="code">entity</code> describes
the entity where the element occurred, <code class="code">line</code> is the line number
<code class="code">>= 1</code>, and <code class="code">pos</code> is the byte position of the first character
of the element in the line.
<p>
If unavailable, the method will return the triple <code class="code">(<span class="string">"?"</span>,0,0)</code>.
<p>
<b>Domain.</b> All node types. Note that the method will always return
<code class="code">(<span class="string">"?"</span>,0,0)</code> for non-element nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODclassify_data_node"></a>classify_data_node : <code class="type">'a <a href="Pxp_document.node.html">node</a> -> <a href="Pxp_document.html#TYPEdata_node_classification">data_node_classification</a></code></pre><div class="info">
<code class="code">classify_data_node n</code>:
Classifies the passed data node <code class="code">n</code>, and returns whether it
is reasonable to append the data node to the list of subnodes
(using <code class="code">append_node</code>). The following return values are possible:<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>
Note that the method always returns and never raises an exception.
<p>
<b>Domain.</b> Elements.<br>
</div>
<a name="2_Modifyingthetreestructure"></a>
<h2>Modifying the tree structure</h2><pre><span class="keyword">method</span> <a name="METHODappend_node"></a>append_node : <code class="type">'a <a href="Pxp_document.node.html">node</a> -> unit</code></pre><div class="info">
<code class="code">append_node n</code>:
Adds the node <code class="code">n</code> at the end of the list of children. The
method expects that <code class="code">n</code> is a root, and it requires that <code class="code">n</code> and
this node share the same DTD.
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements, comments, processing instructions, data nodes,
super root nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODadd_node"></a>add_node : <code class="type">?force:bool -> 'a <a href="Pxp_document.node.html">node</a> -> unit</code></pre><div class="info">
<b>Deprecated</b>! Use <code class="code">append_node</code> instead.
<p>
<code class="code">add_node n</code>:
Append new sub nodes -- mainly used by the parser itself, but
of course open for everybody. If an element is added, it must be
an orphan (i.e. does not have a parent node)
<p>
<b>Validation.</b>
The method performs some basic validation checks if the current node
has a regular expression as content model, or is EMPTY. You can
turn these checks off by passing <code class="code">~force:<span class="keyword">true</span></code> to the method.
<p>
<b>Domain.</b> Elements, comments, processing instructions, data nodes,
super root nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODinsert_nodes"></a>insert_nodes : <code class="type">?pos:int -> 'a <a href="Pxp_document.node.html">node</a> list -> unit</code></pre><div class="info">
<code class="code">insert_nodes ~pos nl</code>:
Inserts the list of nodes <code class="code">nl</code> in-place into the list of
children. The insertion is performed at position <code class="code">pos</code>,
i.e. in the modified list of children, the first element of
<code class="code">nl</code> will have position <code class="code">pos</code>. If the optional argument <code class="code">pos</code>
is not passed to the method, the list <code class="code">nl</code> is appended
to the list of children.
<p>
The method requires that all elements of
the list <code class="code">nl</code> are roots, and that all elements and <code class="code">obj</code>
share the same DTD.
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements, comments, processing instructions, data nodes,
super root nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODremove"></a>remove : <code class="type">unit -> unit</code></pre><div class="info">
Removes this node from the tree. After this
operation, this node is no longer the child of the former father node,
i.e. it does neither occur in the former parent's list of children
nor is the former parent still the parent of this node. This node
becomes orphaned, and is a singleton tree of its own.
<p>
If this node does not have a parent, <code class="code">remove</code> does nothing.
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements, comments, processing instructions, data nodes,
super root nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODdelete"></a>delete : <code class="type">unit</code></pre><div class="info">
<b>Deprecated</b> alias for <code class="code">remove</code><br>
</div>
<pre><span class="keyword">method</span> <a name="METHODremove_nodes"></a>remove_nodes : <code class="type">?pos:int -> ?len:int -> unit -> unit</code></pre><div class="info">
<code class="code">remove_nodes ~pos ~len ()</code>:
Removes the specified nodes from the list of children.
The method deletes the nodes from position <code class="code">pos</code> to
<code class="code">pos+len-1</code>. The optional argument <code class="code">pos</code> defaults to 0. The
optional argument <code class="code">len</code> defaults to the length of the children
list.
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_nodes"></a>set_nodes : <code class="type">'a <a href="Pxp_document.node.html">node</a> list -> unit</code></pre><div class="info">
<code class="code">set_nodes l</code>:
Sets the list of children to <code class="code">l</code>. It is required that
every member of <code class="code">l</code> is either a root or was already a children
of this node before the method call, and it is required that
all members and the current object share the same DTD.
<p>
Former children which are not members of <code class="code">l</code> are removed from
the tree and get orphaned (see method <code class="code">remove</code>).
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements.<br>
</div>
<a name="2_Modifyingcontent"></a>
<h2>Modifying content</h2><pre><span class="keyword">method</span> <a name="METHODset_data"></a>set_data : <code class="type">string -> unit</code></pre><div class="info">
<code class="code">set_data s</code>:
This method sets the character string contained in
data nodes.
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Data nodes<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_attributes"></a>set_attributes : <code class="type">(string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list -> unit</code></pre><div class="info">
<code class="code">set_attributes al</code>:
Sets the attributes of this element to <code class="code">al</code>.
<p>
<b>Validation.</b>
This method does not add missing attributes that are
declared in the DTD. It also never rejects undeclared attributes.
The passed values are not checked; they are simply taken as-are.
<p>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_attribute"></a>set_attribute : <code class="type">?force:bool -> string -> <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a> -> unit</code></pre><div class="info">
<code class="code">set_attribute ~force n v</code>:
Sets the attribute <code class="code">n</code> of this element to the value <code class="code">v</code>.
The attribute <code class="code">n</code> must already exist, and gets a new value.
If you pass <code class="code">~force:<span class="keyword">true</span></code>, however, the attribute is added
to the attribute list if it is missing.
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODreset_attribute"></a>reset_attribute : <code class="type">string -> unit</code></pre><div class="info">
<code class="code">reset_attribute n</code>:
If the attribute <code class="code">n</code> is a declared attribute, it is set
to its default value, or to <code class="code"><span class="constructor">Implied_value</span></code> if there is no default
(the latter is performed even if the attribute is <code class="code"><span class="keywordsign">#</span><span class="constructor">REQUIRED</span></code>).
If the attribute is an undeclared attribute, it is removed
from the attribute list.
<p>
The idea of this method is to simulate what had happened if <code class="code">n</code>
had not been defined literally in the attribute list of the XML element.
In validating mode, the parser would have chosen the default
value if possible, or <code class="code"><span class="constructor">Implied_value</span></code> otherwise, and in
well-formedness mode, the attribute would be simply missing
in the attribute list.
<p>
It is intentionally not possible to remove a declared
attribute with <code class="code">reset_attribute</code>.
<p>
<b>Validation.</b>
This method does not check whether the modified XML tree
is still valid.
<p>
<b>Domain.</b> Elements.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODquick_set_attributes"></a>quick_set_attributes : <code class="type">(string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list -> unit</code></pre><div class="info">
<b>Deprecrated</b> alias for <code class="code">set_attributes</code><br>
</div>
<pre><span class="keyword">method</span> <a name="METHODadd_pinstr"></a>add_pinstr : <code class="type"><a href="Pxp_dtd.proc_instruction.html">Pxp_dtd.proc_instruction</a> -> unit</code></pre><div class="info">
<code class="code">add_pinstr pi</code>:
Adds the processing instruction <code class="code">pi</code> to the set of
processing instructions attached to this node. If this is an
element node, you can add any number of processing instructions.
If it is a processing instruction node, you can put at most
one processing instruction into this node.
<p>
<b>Validation.</b>
Processing instructions are outside the scope of validation.
<p>
<b>Domain.</b> Elements, processing instruction nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_comment"></a>set_comment : <code class="type">string option -> unit</code></pre><div class="info">
<code class="code">set_comment c</code>:
Sets the comment string contained in comment nodes if
<code class="code">c = <span class="constructor">Some</span> s</code>. Otherwise, this method removes the comment string
(<code class="code">c = <span class="constructor">None</span></code>).
<p>
Note that the comment string must not include the delimiters
<code class="code"><!--</code> and <code class="code">--></code>. Furthermore, it must not contain any character
or character sequence that are forbidden in comments, such
as <code class="code"><span class="string">"--"</span></code>. However, this method does not check this condition.
<p>
<b>Validation.</b>
Comments are outside the scope of validation.
<p>
<b>Domain.</b> Comment nodes.<br>
</div>
<a name="2_Validation"></a>
<h2>Validation</h2><pre><span class="keyword">method</span> <a name="METHODvalidate"></a>validate : <code class="type">unit -> unit</code></pre><div class="info">
<code class="code">validate ()</code>:
Calls <code class="code">validate_contents</code> and <code class="code">validate_attlist</code>, and
ensures that this element is locally valid. The method
returns <code class="code">()</code> if the element is valid, and raises an exception
otherwise.
<p>
<b>Domain.</b> All node types. However, for non-element nodes this
check is a no-op.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODvalidate_contents"></a>validate_contents : <code class="type">?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit</code></pre><div class="info">
<code class="code">validate_contents ?use_dfa ?check_data_nodes ()</code>:
Checks that the subnodes of this element match the declared
content model of this element. The method returns <code class="code">()</code> if
the element is okay, and it raises an exception if an error
is found (in most cases <code class="code"><span class="constructor">Validation_error</span></code>).
<p>
This check is always performed by the parser, such that
software that only reads parsed XML trees needs not call
this method. However, if software modifies the tree itself,
an invocation of this method ensures that the validation
constraints about content models are fulfilled.
<p>
Note that the check is not performed recursively, but only
on this node.
<p>
<ul>
<li>Option <code class="code">use_dfa</code>: If true, the deterministic finite automaton of
regexp content models is used for validation, if available.
Defaults to false.</li>
<li>Option <code class="code">check_data_nodes</code>: If true, it is checked whether data
nodes in the list of children only occur at valid positions.
If false, these checks
are left out. Defaults to true. (Usually, the parser turns
this feature off because the parser already performs a similar
check.)
<p>
See <code class="code">classify_data_node</code> for details about what is checked.
Some elements do not allow that there are inner data nodes,
or restrict data nodes to whitespace.
</li>
</ul>
<p>
<b>Domain.</b> All node types. However, there are only real checks for
elements; for other nodes, this method is a no-op.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODlocal_validate"></a>local_validate : <code class="type">?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit</code></pre><div class="info">
<b>Deprecated</b> alias for <code class="code">validate_contents</code><br>
</div>
<pre><span class="keyword">method</span> <a name="METHODcomplement_attlist"></a>complement_attlist : <code class="type">unit -> unit</code></pre><div class="info">
<code class="code">complement_attlist ()</code>:
Adds attributes that are declared in the DTD but are
currently missing: <code class="code"><span class="keywordsign">#</span><span class="constructor">IMPLIED</span></code> attributes are added with
<code class="code"><span class="constructor">Implied_value</span></code>, and if there is a default value for an attribute,
this value is added. <code class="code"><span class="keywordsign">#</span><span class="constructor">REQUIRED</span></code> attributes are set to
<code class="code"><span class="constructor">Implied_value</span></code>, too.
<p>
It is only necessary to call this method if the element is created
with <code class="code">~valcheck:<span class="keyword">false</span></code>, or the attribute list has been modified,
and the element must be again validated.
<p>
<b>Domain.</b> Elements.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODvalidate_attlist"></a>validate_attlist : <code class="type">unit -> unit</code></pre><div class="info">
<code class="code">validate_attlist ()</code>:
Checks whether the attribute list of this element
matches the declared attribute list. The method returns <code class="code">()</code>
if the attribute list is formed correctly, and it raises an
exception (usually a <code class="code"><span class="constructor">Validation_error</span></code>) if there is an error.
<p>
This check is implicitly performed by <code class="code">create_element</code> unless
the option <code class="code">~valcheck:<span class="keyword">false</span></code> has been passed. This means that it
is usually not necessary to call this method; however, if the
attribute list has been changed by <code class="code">set_attributes</code> or if
<code class="code">~valcheck:<span class="keyword">false</span></code> is in effect, the invocation of this method
ensures the validity of the attribute list.
<p>
Note that the method complains about missing attributes even
if these attributes have been declared with a default value or as
being <code class="code"><span class="keywordsign">#</span><span class="constructor">IMPLIED</span></code>; this method only checks the attributes but does
not modify the attribute list. If you know that attributes are
missing and you want to add them automatically just as
<code class="code">create_element</code> does, you can call <code class="code">complement_attlist</code> before
doing this check.
<p>
<b>Domain.</b> All node types. However, for non-element nodes this
check is a no-op.<br>
</div>
<a name="2_Clones"></a>
<h2>Clones</h2><pre><span class="keyword">method</span> <a name="METHODorphaned_clone"></a>orphaned_clone : <code class="type">< add_node : ?force:bool -> 'a <a href="Pxp_document.node.html">node</a> -> unit;<br> add_pinstr : <a href="Pxp_dtd.proc_instruction.html">Pxp_dtd.proc_instruction</a> -> unit;<br> append_node : 'a <a href="Pxp_document.node.html">node</a> -> unit;<br> attribute : string -> <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>; attribute_names : string list;<br> attribute_type : string -> <a href="Pxp_types.html#TYPEatt_type">Pxp_types.att_type</a>;<br> attributes : (string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list;<br> attributes_as_nodes : 'a <a href="Pxp_document.node.html">node</a> list;<br> classify_data_node : 'a <a href="Pxp_document.node.html">node</a> -><br> <a href="Pxp_document.html#TYPEdata_node_classification">data_node_classification</a>;<br> comment : string option; complement_attlist : unit -> unit;<br> create_data : <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> string -> 'a <a href="Pxp_document.node.html">node</a>;<br> create_element : ?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 href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -><br> <a href="Pxp_document.html#TYPEnode_type">node_type</a> -><br> (string * string) list -> 'a <a href="Pxp_document.node.html">node</a>;<br> create_other : ?entity_id:<a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> ?position:string * int * int -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -><br> <a href="Pxp_document.html#TYPEnode_type">node_type</a> -> 'a <a href="Pxp_document.node.html">node</a>;<br> data : string; delete : unit;<br> display : ?prefixes:string Pxp_types.StringMap.t -><br> ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] -><br> <a href="Pxp_types.html#TYPEoutput_stream">Pxp_types.output_stream</a> -> <a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> unit;<br> display_prefix : string; dtd : <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a>;<br> dump : Format.formatter -> unit; encoding : <a href="Pxp_types.html#TYPErep_encoding">Pxp_types.rep_encoding</a>;<br> entity_id : <a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a>; extension : 'a;<br> id_attribute_name : string; id_attribute_value : string;<br> idref_attribute_names : string list;<br> insert_nodes : ?pos:int -> 'a <a href="Pxp_document.node.html">node</a> list -> unit;<br> internal_adopt : 'a <a href="Pxp_document.node.html">node</a> option -> int -> unit;<br> internal_delete : 'a <a href="Pxp_document.node.html">node</a> -> unit;<br> internal_init : <a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> string * int * int -><br> <a href="Pxp_types.html#TYPEpool">Pxp_types.pool</a> option -><br> bool -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -><br> string -><br> (string * string) list -><br> (string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list -> unit;<br> internal_init_other : <a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> string * int * int -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> <a href="Pxp_document.html#TYPEnode_type">node_type</a> -> unit;<br> internal_set_pos : int -> unit;<br> iter_nodes : ('a <a href="Pxp_document.node.html">node</a> -> unit) -> unit;<br> iter_nodes_sibl : ('a <a href="Pxp_document.node.html">node</a> option -><br> 'a <a href="Pxp_document.node.html">node</a> -><br> 'a <a href="Pxp_document.node.html">node</a> option -> unit) -><br> unit;<br> local_validate : ?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit;<br> localname : string; namespace_manager : <a href="Pxp_dtd.namespace_manager.html">Pxp_dtd.namespace_manager</a>;<br> namespace_scope : <a href="Pxp_dtd.namespace_scope.html">Pxp_dtd.namespace_scope</a>; namespace_uri : string;<br> namespaces_as_nodes : 'a <a href="Pxp_document.node.html">node</a> list;<br> next_node : 'a <a href="Pxp_document.node.html">node</a>; node_path : int list;<br> node_position : int; node_type : <a href="Pxp_document.html#TYPEnode_type">node_type</a>;<br> normprefix : string; nth_node : int -> 'a <a href="Pxp_document.node.html">node</a>;<br> optional_list_attribute : string -> string list;<br> optional_string_attribute : string -> string option; orphaned_clone : 'b;<br> orphaned_flat_clone : 'b; parent : 'a <a href="Pxp_document.node.html">node</a>;<br> pinstr : string -> <a href="Pxp_dtd.proc_instruction.html">Pxp_dtd.proc_instruction</a> list;<br> pinstr_names : string list; position : string * int * int;<br> previous_node : 'a <a href="Pxp_document.node.html">node</a>;<br> quick_set_attributes : (string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list -> unit;<br> remove : unit -> unit; remove_nodes : ?pos:int -> ?len:int -> unit -> unit;<br> required_list_attribute : string -> string list;<br> required_string_attribute : string -> string;<br> reset_attribute : string -> unit; root : 'a <a href="Pxp_document.node.html">node</a>;<br> set_attribute : ?force:bool -> string -> <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a> -> unit;<br> set_attributes : (string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list -> unit;<br> set_comment : string option -> unit; set_data : string -> unit;<br> set_namespace_scope : <a href="Pxp_dtd.namespace_scope.html">Pxp_dtd.namespace_scope</a> -> unit;<br> set_nodes : 'a <a href="Pxp_document.node.html">node</a> list -> unit;<br> sub_nodes : 'a <a href="Pxp_document.node.html">node</a> list; validate : unit -> unit;<br> validate_attlist : unit -> unit;<br> validate_contents : ?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit;<br> write : ?prefixes:string list -><br> ?default:string -><br> ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] -><br> <a href="Pxp_types.html#TYPEoutput_stream">Pxp_types.output_stream</a> -> <a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> unit;<br> .. ><br> as 'b</code></pre><div class="info">
Returns a clone of the node and the complete tree below
this node (deep clone). The clone does not have a parent (i.e. the
reference to the parent node is not cloned). While copying the
subtree strings are skipped; normally the original tree and the
copy tree share strings. Extension objects are cloned by invoking
the <code class="code">clone</code> method on the original objects; how much of
the extension objects is cloned depends on the implemention of
this method.
<p>
All node types.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODorphaned_flat_clone"></a>orphaned_flat_clone : <code class="type">'b</code></pre><div class="info">
return a clone of this element where all subnodes are omitted.
The type of the node, and the attributes are the same as in the
original node. The clone has no parent.
<p>
<b>Domain.</b> All node types.<br>
</div>
<a name="2_Creatingnewnodesbycloningexemplars"></a>
<h2>Creating new nodes by cloning exemplars</h2><pre><span class="keyword">method</span> <a name="METHODcreate_element"></a>create_element : <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 href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -><br> <a href="Pxp_document.html#TYPEnode_type">node_type</a> -> (string * string) list -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">create_element ~name_pool_for_attribute_values ~position ~valcheck ~att_values dtd ntype att_list</code>:
This method is usually only called on exemplars to create
fresh nodes of the same class as the examplars. This is done
by copying the exemplars, and setting the properties of the
(flat) copies as follows:
<p>
<ul>
<li>The DTD is set to <code class="code">dtd</code></li>
<li>The node type is set to <code class="code">ntype</code> (which must be <code class="code"><span class="constructor">T_element</span> name</code>)</li>
<li>The attribute list is set to 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 copy does not have children nor a parent</li>
<li>The copy does not contain processing instructions.</li>
<li>The position triple is set to <code class="code">position</code></li>
<li>The entity ID is set to <code class="code">entity_id</code></li>
</ul>
Note that the extension object is copied, too.
<p>
If <code class="code">valcheck=<span class="keyword">true</span></code> (the default), it is checked whether the
element type exists and whether the passed attributes match the
declared attribute list. Missing attributes are automatically
added, if possible. If <code class="code">valcheck=<span class="keyword">false</span></code>, any element type
and any attributes are accepted.
<p>
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.
<p>
If a <code class="code">name_pool_for_attribute_values</code> is passed, the attribute
values in <code class="code">att_list</code> are put into this pool.
<p>
The optional arguments have the following defaults:<ul>
<li><code class="code">~name_pool_for_attribute_values</code>: No pool is used</li>
<li><code class="code">~position</code>: The position is not available in the copy</li>
<li><code class="code">~valcheck</code>: true</li>
<li><code class="code">~att_values</code>: empty</li>
<li><code class="code">~entity_id</code>: a new ID is used that is connected to a real entity</li>
</ul>
<b>Domain.</b> Elements.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODcreate_data"></a>create_data : <code class="type"><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 dtd cdata</code>:
This method is usually only called on exemplars to create
fresh nodes of the same class as the examplars. This is done
by copying the exemplars, and setting the properties of the
(flat) copies as follows:<ul>
<li>The DTD is set to <code class="code">dtd</code></li>
<li>The character string is set to <code class="code">cdata</code></li>
</ul>
Note that the extension object is copied, too.
<p>
<b>Domain.</b> Data nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODcreate_other"></a>create_other : <code class="type">?entity_id:<a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> ?position:string * int * int -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> <a href="Pxp_document.html#TYPEnode_type">node_type</a> -> 'a <a href="Pxp_document.node.html">node</a></code></pre><div class="info">
<code class="code">create_other ~position dtd ntype</code>:
This method is usually only called on exemplars to create
fresh nodes of the same class as the examplars. This is done
by copying the exemplars, and setting the properties of the
(flat) copies as follows:<ul>
<li>The DTD is set to <code class="code">dtd</code></li>
<li>The position triple is set to <code class="code">position</code></li>
<li>The entity ID is set to <code class="code">entity_id</code></li>
</ul>
Note that the extension object is copied, too.
<p>
The passed node type <code class="code">ntype</code> must match the node type
of this node.
<p>
<b>Domain.</b> Super root nodes, processing instruction nodes,
comment nodes<br>
</div>
<a name="2_Namespaces"></a>
<h2>Namespaces</h2>
<p>
Namespace methods are only available in namespace-aware implementations
of <code class="code">node</code>. For other implementations, the exception
<a href="Pxp_types.html#EXCEPTIONNamespace_method_not_applicable"><code class="code"><span class="constructor">Pxp_types</span>.<span class="constructor">Namespace_method_not_applicable</span></code></a> is raised.
<p>
Keep in mind that PXP applies prefix normalization. For an
introduction see <a href="Intro_namespaces.html"><code class="code"><span class="constructor">Intro_namespaces</span></code></a>.<pre><span class="keyword">method</span> <a name="METHODnormprefix"></a>normprefix : <code class="type">string</code></pre><div class="info">
For namespace-aware implementations of the node class, this
method returns the normalized prefix of the element or attribute.
If the object does not have a prefix, "" will be passed back.
<p>
The normalized prefix is the part of the name before the
colon after prefix normalization has been applied to the node.
<p>
<b>Domain.</b> Elements and attributes supporting namespaces.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODdisplay_prefix"></a>display_prefix : <code class="type">string</code></pre><div class="info">
For namespace-aware implementations of the node class, this
method returns the display prefix of the element or attribute.
If the object does not have a prefix, "" will be passed back.
<p>
The display prefix is supposed to be the prefix as it occurs
literally in the XML text.
<p>
Actually, this method does not return the real display prefix
that was found in the XML text but the most recently declared
display prefix bound to the namespace URI of this element or
attribute, i.e. this method infers the display prefix. The
result can be a different prefix than the original prefix
if the same namespace URI is bound several times in the
current namespace scope.
<p>
This method is quite slow.
<p>
<b>Domain.</b> Elements and attributes supporting namespaces.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODlocalname"></a>localname : <code class="type">string</code></pre><div class="info">
For namespace-aware implementations of the node class, this
method returns the local part of the name of the element or
attribute.
<p>
The local name is the part of the name after the colon, or
the whole name if there is no colon.
<p>
<b>Domain.</b> Elements and attributes supporting namespaces.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnamespace_uri"></a>namespace_uri : <code class="type">string</code></pre><div class="info">
For namespace-aware implementations of the node class, this
method returns the namespace URI of the element, attribute or
namespace.
<p>
If the node does not have a namespace prefix, and there is no
default namespace, this method returns "".
<p>
The namespace URI is the unique name of the namespace.
<p>
<b>Domain.</b> Elements and attributes supporting namespaces; furthermore
namespace nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnamespace_manager"></a>namespace_manager : <code class="type"><a href="Pxp_dtd.namespace_manager.html">Pxp_dtd.namespace_manager</a></code></pre><div class="info">
For namespace-aware implementations of the node class,
this method returns the namespace manager. If the namespace
manager has not yet been set, the exception <code class="code"><span class="constructor">Not_found</span></code> is raised.
<p>
The namespace manager is an object that holds the mapping
from namespace prefixes to namespace URIs, and vice versa.
It is contained in the DTD, and must be configured there.
<p>
<b>Domain.</b> Elements and attributes supporting namespaces; furthermore
namespace nodes.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnamespace_scope"></a>namespace_scope : <code class="type"><a href="Pxp_dtd.namespace_scope.html">Pxp_dtd.namespace_scope</a></code></pre><div class="info">
Returns additional information about the namespace
structure in the parsed XML text. In particular, the namespace
scope describes the literal (unprocessed) namespace prefixes
in the XML text, and how they are mapped to the namespace URIs.
<p>
When printing XML text, the namespace scope may be used
to give the printer hints where to introduce namespaces, and
which namespace prefixes are preferred.
<p>
<b>Domain.</b> Elements and attributes supporting namespaces<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_namespace_scope"></a>set_namespace_scope : <code class="type"><a href="Pxp_dtd.namespace_scope.html">Pxp_dtd.namespace_scope</a> -> unit</code></pre><div class="info">
<code class="code">set_namespace_scope scope</code>:
Sets the namespace scope object. It is required that
this object is connected to the same namespace manager as
the rest of the document tree.
<p>
<b>Domain.</b> Elements and attributes supporting namespaces<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODnamespaces_as_nodes"></a>namespaces_as_nodes : <code class="type">'a <a href="Pxp_document.node.html">node</a> list</code></pre><div class="info">
Returns the namespaces found in the <code class="code">namespace_scope</code>
object and all parent scope objects (except declarations that
are hidden by more recent declarations). The namespaces are
returned as node objects with type <code class="code"><span class="constructor">T_namespace</span> name</code> where
<code class="code">name</code> is the normalized prefix.
<p>
This method should be used if it is required for typing reasons
that the namespaces have also type <code class="code">node</code>. A common example
are sets that may both contain elements and namespaces, as they
are used in the XPath language.
<p>
The namespace nodes are read-only; any call to a method
modifying their contents will raise <code class="code"><span class="constructor">Method_not_applicable</span></code>.
See the class <code class="code">namespace_impl</code> below for more information
about the returned nodes.
<p>
The namespace nodes live outside of the regular XML tree, and
they are not considered as children of the element node. However,
the element node is the parent node of the namespace nodes
(i.e. the children/parent relationship is asymmetric).
<p>
The method <code class="code">namespaces_as_nodes</code> computes the list of namespace
nodes when it is first invoked, and it will return the same list
again in subsequent invocations.
<p>
See also <a href="Intro_advanced.html#irrnodes"><i>Irregular nodes: namespace nodes and attribute nodes</i></a>.
<p>
<b>Domain.</b> This method is only applicable to elements that
support namespaces.<br>
</div>
<a name="2_WritingtreesasXMLtext"></a>
<h2>Writing trees as XML text</h2>
<p>
The <code class="code">write</code> and <code class="code">display</code> methods are very similar. The main difference
is how namespaces are handled. When generating XML text, the
namespaces need to be again represented as prefixes. The <code class="code">write</code>
method uses the normalized prefixes for this purpose. The <code class="code">display</code>
method uses the display prefixes, i.e. the prefixes as they orginally
have been in the parsed XML text. This means for parsed XML text
<code class="code">display</code> produces an more exact copy of the text, whereas
<code class="code">write</code> shows the prefixes as they are seen by the program.<pre><span class="keyword">method</span> <a name="METHODwrite"></a>write : <code class="type">?prefixes:string list -><br> ?default:string -><br> ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] -><br> <a href="Pxp_types.html#TYPEoutput_stream">Pxp_types.output_stream</a> -> <a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> unit</code></pre><div class="info">
<code class="code">write stream enc</code>:
Write the contents of this node and the subtrees to the passed
<code class="code">stream</code> encoded as <code class="code">enc</code>. The generated output is again XML.
The output style is rather compact and should not be considered
as "pretty printing".
<p>
The namespace-aware nodes use a notation with normalized
prefixes. The namespace scope is ignored.
<p>
Option <code class="code">~prefixes</code>: The class <code class="code">namespace_element_impl</code> interprets
this option and passes it recursively to subordinate invocations of
<code class="code">write</code>. The meaning is that the normprefixes enumerated by this list
have already been declared by surrounding elements. The option
defaults to [] forcing the method to output all necessary prefix
declarations.
<p>
Option <code class="code">~default</code>: Specifies the normprefix that becomes the
default namespace in the output.
<p>
Option <code class="code">~minimization</code>: How to write out empty elements. <code class="code"><span class="keywordsign">`</span><span class="constructor">AllEmpty</span></code>
means that all empty elements are minimized (using the <name/>
form). <code class="code"><span class="keywordsign">`</span><span class="constructor">DeclaredEmpty</span></code> minimizes only empty elements that are
declared as empty in the DTD. <code class="code"><span class="keywordsign">`</span><span class="constructor">None</span></code> does not minimize at all
and is the default.
<p>
<b>Domain.</b> All regular node types (elements, data nodes, comments,
processing instructions, super root nodes).<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODdisplay"></a>display : <code class="type">?prefixes:string Pxp_types.StringMap.t -><br> ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] -><br> <a href="Pxp_types.html#TYPEoutput_stream">Pxp_types.output_stream</a> -> <a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> unit</code></pre><div class="info">
<code class="code">display stream enc</code>:
Write the contents of this node and the subtrees to the passed
<code class="code">stream</code> encoded as <code class="code">enc</code>. The generated output is again XML.
The output style is rather compact and should not be considered
as "pretty printing".
<p>
The namespace-aware nodes try to follow the namespace scoping
found in the nodes. The generated namespace prefixes are
display prefixes. Missing prefixes are complemented, but this
is slow.
<p>
Option <code class="code">~prefixes</code>: The class <code class="code">namespace_element_impl</code> interprets
this option and passes it recursively to subordinate invocations of
<code class="code">display</code>. The mapping contains the declarations currently in
effect as pairs of <code class="code">(prefix,uri)</code>. The option
defaults to [] forcing the method to output all necessary prefix
declarations.
<p>
Option <code class="code">~minimization</code>: How to write out empty elements. <code class="code"><span class="keywordsign">`</span><span class="constructor">AllEmpty</span></code>
means that all empty elements are minimized (using the <name/>
form). <code class="code"><span class="keywordsign">`</span><span class="constructor">DeclaredEmpty</span></code> minimizes only empty elements that are
declared as empty in the DTD. <code class="code"><span class="keywordsign">`</span><span class="constructor">None</span></code> does not minimize at all
and is the default.
<p>
<b>Domain.</b> All regular node types (elements, data nodes, comments,
processing instructions, super root nodes).<br>
</div>
<a name="2_Internals"></a>
<h2>Internals</h2>
<p>
These methods are considered as private of the implementation.<pre><span class="keyword">method</span> <a name="METHODinternal_adopt"></a>internal_adopt : <code class="type">'a <a href="Pxp_document.node.html">node</a> option -> int -> unit</code></pre><pre><span class="keyword">method</span> <a name="METHODinternal_set_pos"></a>internal_set_pos : <code class="type">int -> unit</code></pre><pre><span class="keyword">method</span> <a name="METHODinternal_delete"></a>internal_delete : <code class="type">'a <a href="Pxp_document.node.html">node</a> -> unit</code></pre><pre><span class="keyword">method</span> <a name="METHODinternal_init"></a>internal_init : <code class="type"><a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> string * int * int -><br> <a href="Pxp_types.html#TYPEpool">Pxp_types.pool</a> option -><br> bool -><br> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -><br> string -><br> (string * string) list -> (string * <a href="Pxp_types.html#TYPEatt_value">Pxp_types.att_value</a>) list -> unit</code></pre><pre><span class="keyword">method</span> <a name="METHODinternal_init_other"></a>internal_init_other : <code class="type"><a href="Pxp_types.html#TYPEentity_id">Pxp_types.entity_id</a> -><br> string * int * int -> <a href="Pxp_dtd.dtd.html">Pxp_dtd.dtd</a> -> <a href="Pxp_document.html#TYPEnode_type">node_type</a> -> unit</code></pre><pre><span class="keyword">method</span> <a name="METHODdump"></a>dump : <code class="type">Format.formatter -> unit</code></pre></body></html>
