# Class type Pxp_document.node

    class type [< clone : 'a; node : 'a node;
           set_node : 'a node -> unit; .. >
         as 'a] node = object .. end

The class type `node` defines the interface of the nodes that are part of XML document trees. For an introduction into trees, see `Intro_trees`.

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 `'ext`, and which can be any class type that is a subtype of `Pxp_document.extension`. Note that also the extension has a type parameter pointing to the node class. Closed node types look thus like

`type my_node = my_node extension node`

which is a rare form of a recursive type.

## Domain

Every node has a node type which is returned by the `node_type` 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 `Pxp_types.Method_not_applicable` or `Pxp_types.Namespace_method_not_applicable` for namespace-specific methods.

## Validation

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.

## General Interface

    method extension : 'a

Returns the extension object of this node.

Domain. Applicable to element, data, comment, processing instruction, and super root nodes.

    method node_type : node_type

Returns the type of the node:

- `T_element t`: The node is an element with name `t`
- `T_data`: The node is a data node
- `T_comment`: The node is a comment node
- `T_pinstr n`: The node is a processing instruction with target `n`
- `T_super_root`: The node is a super root node
- `T_attribute n`: The node is an attribute with name `n`
- `T_namespace p`: The node is a namespace with normalized prefix `p`

Domain. All node types.

    method dtd : Pxp_dtd.dtd

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).

Domein. All node types. However, exemplars need not to have an associated DTD, in which case this method fails.

    method encoding : Pxp_types.rep_encoding

Get the encoding which is always the same as the encoding of the DTD. See also method `dtd`. (Note: This method fails, too, if no DTD is present.)

Domain. All node types. Note that exemplars need not to have an associated DTD, in which case this method fails.

## Navigation Interface

    method parent : 'a node

Get the parent node, or raise `Not_found` 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.

Domain. All node types.

    method root : 'a node

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.

Domain. All node types.

    method node_position : int

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:

- The regular nodes get positions from `0` to `l-1` where `l` is the length of the list of regular children.
- Attribute nodes and namespace nodes are irregular nodes, which means here that their positions are counted seperately. All attribute nodes have positions from `0` to `m-1`; all namespace nodes have positions from `0` to `n-1`.
- If this node is a root, this method raises `Not_found`.

Domain. All node types.

    method node_path : int list

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.

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 `x` have the node path `x # node_path @ [-1; p]` where `p` is the position of the attribute node. Namespace nodes of an element node `x` have the node path `x # node_path @ [-2; p]` where `p` is the position of the namespace node. Note that this definition respects the document order.

Domain. All node types.

    method sub_nodes : 'a node list

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.

Domain. All node types.

    method iter_nodes : ('a node -> unit) -> unit

`obj#iter_nodes f` iterates over the regular children of `obj`, and calls the function `f` for every child `ch` as `f ch`. The regular children are the nodes returned by `sub_nodes`, see there for an explanation.

See also Document iterators for more functions iterating over trees.

Domain. All node types.

    method iter_nodes_sibl : ('a node option ->
            'a node -> 'a node option -> unit) ->
           unit

`obj#iter_nodes f` iterates over the regular children of `obj`, and calls the function `f` for every child as `f pred ch succ`:

- `ch` is the child
- `pred` is `None` if the child is the first in the list, and `Some p` otherwise; `p` is the predecessor of `ch`
- `succ` is `None` if the child is the last in the list, and `Some s` otherwise; `s` is the successor of `ch`

The regular children are the nodes returned by `sub_nodes`, see there for an explanation.

See also Document iterators for more functions iterating over trees.

Domain. All node types.

    method nth_node : int -> 'a node

`nth_node n` returns the n-th regular child, `n >= 0`. Raises `Not_found` if the index `n` is out of the valid range.

Domain. All node types.

    method previous_node : 'a node

Returns the predecessor of this node in the list of regular children of the parent, or raise `Not_found` if this node is the first child. This is equivalent to `obj # parent # nth_node (obj # node_position - 1)` (when `obj` is this node).

Domain. All node types.

    method next_node : 'a node

Returns the successor of this node in the list of regular children of the parent, or raise `Not_found` if this node is the last child. This is equivalent to `obj # parent # nth_node (obj # node_position + 1)` (when `obj` is this node).

Domain. All node types.

## Getting contents and attributes

Also see the `Pxp_document.node.node_type` method which returns the type of the node, and for elements their names.

    method data : string

This method returns what is considered as the data of the node which depends on the node type:

- Data nodes: the method returns the character string the node represents
- Element nodes, super root nodes: the method returns the concatenated character strings of all (direct or indirect) data nodes below this node
- Comment nodes: the method returns the comment string (without delimiters), or it raises `Not_found` if the comment string is not set (see also the `comment` method below for an alternate way of getting the comment string)
- Processing instructions: the method returns the data part of the instruction, or `""` if the data part is missing (see also the `pinstr` method below for an alternay way of accessing processing instructions)
- Attribute nodes: the method returns the attribute value as string, or it raises `Not_found` if the attribute is implied.
- Namespace nodes: the method returns the namespace URI

Domain. All node types.

    method attribute : string -> Pxp_types.att_value

`attribute name` returns the value of the attribute `name`.

If the parser is in validating mode, the method returns values for declared attributes, and it raises `Not_found` for any undeclared attribute. Note that it even returns a value if the attribute is actually missing but is declared as `#IMPLIED` or has a default value.

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 `Not_found` for any unknown attribute name.

Possible return values are:

- `Implied_value`: The attribute has been declared with the keyword `#IMPLIED`, and the attribute definition is missing in the attribute list of the element.
- `Value s`: The attribute has been declared as type `CDATA`, as `ID`, as `IDREF`, as `ENTITY`, or as `NMTOKEN`, 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 `s`. (2) The attribute has been omitted, and the DTD declares the attribute with a default value. The default value is returned in `s`.

  Summarized, `Value s` is returned for non-implied, non-list attribute values.

  Furthermore, `Value s` is returned for non-declared attributes if the DTD object allows this, for instance, if the DTD object specifies well-formedness mode.

- `Valuelist l`: The attribute has been declared as type `IDREFS`, as `ENTITIES`, or `NMTOKENS`, 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 `l`. (2) The attribute has been omitted, and the DTD declares the attribute with a default value. The default value is returned in `l`.

  Summarized, `Valuelist l` is returned for all list-type attribute values.

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. `&#n;`) and general entities (i.e. `&name;`) are expanded; if necessary, the expansion is performed recursively.

Domain. All node types. However, only elements and attribute nodes will return values, all other node types always raise `Not_found`.

    method attribute_names : string list

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.

Domain. All node types. However, only elements and attribute nodes will return a non-empty list, all other node types always return the empty list.

    method attribute_type : string -> Pxp_types.att_type

`attribute_type name`: returns the type of the attribute `name`. If the attribute is declared, the declared type is returned. If the attribute is defined but undeclared, the type `A_cdata` will be returned. (The module `Pxp_types` contains the Caml type of attribute types.) This method raises `Not_found` if the attribute is unknown.

Domain. All node types. However, only elements and attribute nodes will return values, all other node types always raise `Not_found`.

    method attributes : (string * Pxp_types.att_value) list

Returns the list of `(name,value)` pairs describing all attributes (declared attributes plus defined attributes).

Domain. All node types. However, only elements and attribute nodes will return non-empty values, all other node types always return the empty list.

    method required_string_attribute : string -> string

`required_string_attribute name`: Returns the value of the attribute `name` as string, i.e. if the value of the attribute is `Value s`, this method will return simply `s`, and if the value is `Valuelist l`, this method will return the elements of `l` separated by spaces. If the attribute value is `Implied_value`, the method will fail.

Domain. All node types. However, only elements and attribute nodes will return values, all other node types always fail.

    method required_list_attribute : string -> string list

`required_list_attribute name`: Returns the value of the attribute `name` as string list, i.e. if the value of the attribute is `Valuelist l`, this method will return simply `l`, and if the value is `Value s`, this method will return the one-element list `[[s]]`. If the attribute value is `Implied_value`, the method will fail.

Domain. All node types. However, only elements and attribute nodes will return values, all other node types always fail.

    method optional_string_attribute : string -> string option

`optional_string_attribute name`: Returns the value of the attribute `name` as optional string, i.e. if the value of the attribute is `Value s`, this method will return `Some s`, and if the value is `Valuelist l`, this method will return `Some s` where `s` consists of the concatenated elements of `l` separated by spaces. If the attribute value is `Implied_value`, the method will return `None`.

Domain. All node types. However, only elements and attribute nodes will return `Some` values, all other node types always return `None`.

    method optional_list_attribute : string -> string list

`optional_list_attribute name`: Returns the value of the attribute `name` as string list, i.e. if the value of the attribute is `Valuelist l`, this method will return simply `l`, and if the value is `Value s`, this method will return the one-element list `[[s]]`. If the attribute value is `Implied_value`, the method will return the empty list.

Domain. All node types. However, only elements and attribute nodes will return non-empty values, all other node types always return the empty list.

    method id_attribute_name : string

Returns the name of the (at most one) attribute being declared as type `ID`. The method raises `Not_found` if there is no declared `ID` attribute for the element type.

Domain. All node types. However, only elements and attribute nodes will return names, all other node types always raise `Not_found`.

    method id_attribute_value : string

Returns the string value of the (at most one) attribute being declared as type `ID`. The method raises `Not_found` if there is no declared `ID` attribute for the element type.

Domain. All node types. However, only elements and attribute nodes will return names, all other node types always raise `Not_found`.

    method idref_attribute_names : string list

Returns the names of the attributes being declared as type `IDREF` or `IDREFS`.

Domain. All node types. However, only elements and attribute nodes will return names, all other node types always return the empty list.

    method attributes_as_nodes : 'a node list

Returns all attributes (i.e. declared plus defined attributes) as a list of attribute nodes with node type `T_attribute name`.

This method can be used if it is required for typing reasons that the attributes have also type `node`. A common example are sets that may both contain elements and attributes, as they are used in the XPath language.

The attribute nodes are read-only; any call to a method modifying their contents will raise `Method_not_applicable`. In order to get the value of such an attribute node `anode`, one can invoke the method `attribute`:

`anode # attribute name`

where `name` is the name of the attribute represented by `anode`. This will return the attribute value as `att_value`. Of course, the other attribute accessors can be called as well. Furthermore, the method `data` 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.

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).

The method `attributes_as_nodes` 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.

See also Irregular nodes: namespace nodes and attribute nodes.

Domain. This method is only applicable to elements.

    method pinstr : string -> Pxp_dtd.proc_instruction list

`pinstr n` returns all processing instructions that are attached to this object and that have a target specification of `n`.

Domain. 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.

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 `enable_pinstr_nodes` config option is in effect. When a processing instruction is parsed, a new processing instruction node is added to the tree, and the `proc_instruction` object is added to this node, and can be queried by calling this method.

If the mentioned config option is not active (which is the default), the `proc_instruction` 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.

    method pinstr_names : string list

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 `pinstr` method to get the full data of a processing instruction.

Domain. All node types. However, as for `pinstr` only a few types of nodes can be filled with processing instruction. See the description at `Pxp_document.node.pinstr` for details.

    method comment : string option

Returns `Some text` if the node is a comment node and if `text` is the comment string (without the delimiters `<!--` and `-->`). Otherwise, `None` is passed back.

Note: The `data` method also returns the comment string, but it raises `Not_found` if the string is not available. This is the only difference between these methods when called on comment nodes.

Domain. All node types. Note that the method will always return `None` for non-comment nodes.

## Meta data

    method entity_id : Pxp_types.entity_id

Returns the `entity_id` object. This object identifies the entity the node originates from. See `Pxp_dtd.Entity` for functions finding and accessing the entity.

Domain. All node types. Note that it is possible that one gets an `entity_id` 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 `entity_id` for all node kinds. Generally, the `entity_id` corresponds to a real entity only for element, attribute, and processing instruction nodes.

    method position : string * int * int

Returns a triple `(entity,line,pos)` 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 `store_element_positions`). If available, `entity` describes the entity where the element occurred, `line` is the line number `>= 1`, and `pos` is the byte position of the first character of the element in the line.

If unavailable, the method will return the triple `("?",0,0)`.

Domain. All node types. Note that the method will always return `("?",0,0)` for non-element nodes.

    method classify_data_node : 'a node -> data_node_classification

`classify_data_node n`: Classifies the passed data node `n`, and returns whether it is reasonable to append the data node to the list of subnodes (using `append_node`). The following return values are possible:

- `CD_normal`: Adding `n` does not violate any validation constraint
- `CD_other`: `n` is not a data node
- `CD_empty`: The element `obj` is declared as `EMTPY`, and `n` contains the empty string. It is allowed to append `n` but it does not make sense
- `CD_ignorable`: The element `obj` is declared such that it is forbidden to put character data into it. However, the node `n` only contains white space which is allowed as an exception to this rule. This means that it is allowed to append `n` but `n` would not contain any information except formatting hints.
- `CD_error e`: It is an error to append `n`. The exception `e`, usually a `Validation_error`, contains details about the problem.

Note that the method always returns and never raises an exception.

Domain. Elements.

## Modifying the tree structure

    method append_node : 'a node -> unit

`append_node n`: Adds the node `n` at the end of the list of children. The method expects that `n` is a root, and it requires that `n` and this node share the same DTD.

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Elements, comments, processing instructions, data nodes, super root nodes.

    method add_node : ?force:bool -> 'a node -> unit

Deprecated! Use `append_node` instead.

`add_node n`: 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)

Validation. 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 `~force:true` to the method.

Domain. Elements, comments, processing instructions, data nodes, super root nodes.

    method insert_nodes : ?pos:int -> 'a node list -> unit

`insert_nodes ~pos nl`: Inserts the list of nodes `nl` in-place into the list of children. The insertion is performed at position `pos`, i.e. in the modified list of children, the first element of `nl` will have position `pos`. If the optional argument `pos` is not passed to the method, the list `nl` is appended to the list of children.

The method requires that all elements of the list `nl` are roots, and that all elements and `obj` share the same DTD.

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Elements, comments, processing instructions, data nodes, super root nodes.

    method remove : unit -> unit

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.

If this node does not have a parent, `remove` does nothing.

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Elements, comments, processing instructions, data nodes, super root nodes.

    method delete : unit

Deprecated alias for `remove`

    method remove_nodes : ?pos:int -> ?len:int -> unit -> unit

`remove_nodes ~pos ~len ()`: Removes the specified nodes from the list of children. The method deletes the nodes from position `pos` to `pos+len-1`. The optional argument `pos` defaults to 0. The optional argument `len` defaults to the length of the children list.

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Elements.

    method set_nodes : 'a node list -> unit

`set_nodes l`: Sets the list of children to `l`. It is required that every member of `l` 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.

Former children which are not members of `l` are removed from the tree and get orphaned (see method `remove`).

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Elements.

## Modifying content

    method set_data : string -> unit

`set_data s`: This method sets the character string contained in data nodes.

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Data nodes

    method set_attributes : (string * Pxp_types.att_value) list -> unit

`set_attributes al`: Sets the attributes of this element to `al`.

Validation. 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.

This method does not check whether the modified XML tree is still valid.

Domain. Elements.

    method set_attribute : ?force:bool -> string -> Pxp_types.att_value -> unit

`set_attribute ~force n v`: Sets the attribute `n` of this element to the value `v`. The attribute `n` must already exist, and gets a new value. If you pass `~force:true`, however, the attribute is added to the attribute list if it is missing.

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Elements.

    method reset_attribute : string -> unit

`reset_attribute n`: If the attribute `n` is a declared attribute, it is set to its default value, or to `Implied_value` if there is no default (the latter is performed even if the attribute is `#REQUIRED`). If the attribute is an undeclared attribute, it is removed from the attribute list.

The idea of this method is to simulate what had happened if `n` 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 `Implied_value` otherwise, and in well-formedness mode, the attribute would be simply missing in the attribute list.

It is intentionally not possible to remove a declared attribute with `reset_attribute`.

Validation. This method does not check whether the modified XML tree is still valid.

Domain. Elements.

    method quick_set_attributes : (string * Pxp_types.att_value) list -> unit

Deprecrated alias for `set_attributes`

    method add_pinstr : Pxp_dtd.proc_instruction -> unit

`add_pinstr pi`: Adds the processing instruction `pi` 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.

Validation. Processing instructions are outside the scope of validation.

Domain. Elements, processing instruction nodes.

    method set_comment : string option -> unit

`set_comment c`: Sets the comment string contained in comment nodes if `c = Some s`. Otherwise, this method removes the comment string (`c = None`).

Note that the comment string must not include the delimiters `<!--` and `-->`. Furthermore, it must not contain any character or character sequence that are forbidden in comments, such as `"--"`. However, this method does not check this condition.

Validation. Comments are outside the scope of validation.

Domain. Comment nodes.

## Validation

    method validate : unit -> unit

`validate ()`: Calls `validate_contents` and `validate_attlist`, and ensures that this element is locally valid. The method returns `()` if the element is valid, and raises an exception otherwise.

Domain. All node types. However, for non-element nodes this check is a no-op.

    method validate_contents : ?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit

`validate_contents ?use_dfa ?check_data_nodes ()`: Checks that the subnodes of this element match the declared content model of this element. The method returns `()` if the element is okay, and it raises an exception if an error is found (in most cases `Validation_error`).

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.

Note that the check is not performed recursively, but only on this node.

- Option `use_dfa`: If true, the deterministic finite automaton of regexp content models is used for validation, if available. Defaults to false.
- Option `check_data_nodes`: 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.)

  See `classify_data_node` for details about what is checked. Some elements do not allow that there are inner data nodes, or restrict data nodes to whitespace.

Domain. All node types. However, there are only real checks for elements; for other nodes, this method is a no-op.

    method local_validate : ?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit

Deprecated alias for `validate_contents`

    method complement_attlist : unit -> unit

`complement_attlist ()`: Adds attributes that are declared in the DTD but are currently missing: `#IMPLIED` attributes are added with `Implied_value`, and if there is a default value for an attribute, this value is added. `#REQUIRED` attributes are set to `Implied_value`, too.

It is only necessary to call this method if the element is created with `~valcheck:false`, or the attribute list has been modified, and the element must be again validated.

Domain. Elements.

    method validate_attlist : unit -> unit

`validate_attlist ()`: Checks whether the attribute list of this element matches the declared attribute list. The method returns `()` if the attribute list is formed correctly, and it raises an exception (usually a `Validation_error`) if there is an error.

This check is implicitly performed by `create_element` unless the option `~valcheck:false` has been passed. This means that it is usually not necessary to call this method; however, if the attribute list has been changed by `set_attributes` or if `~valcheck:false` is in effect, the invocation of this method ensures the validity of the attribute list.

Note that the method complains about missing attributes even if these attributes have been declared with a default value or as being `#IMPLIED`; 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 `create_element` does, you can call `complement_attlist` before doing this check.

Domain. All node types. However, for non-element nodes this check is a no-op.

## Clones

    method orphaned_clone : < add_node : ?force:bool -> 'a node -> unit;
             add_pinstr : Pxp_dtd.proc_instruction -> unit;
             append_node : 'a node -> unit;
             attribute : string -> Pxp_types.att_value; attribute_names : string list;
             attribute_type : string -> Pxp_types.att_type;
             attributes : (string * Pxp_types.att_value) list;
             attributes_as_nodes : 'a node list;
             classify_data_node : 'a node ->
                                  data_node_classification;
             comment : string option; complement_attlist : unit -> unit;
             create_data : Pxp_dtd.dtd -> string -> 'a node;
             create_element : ?name_pool_for_attribute_values:Pxp_types.pool ->
                              ?entity_id:Pxp_types.entity_id ->
                              ?position:string * int * int ->
                              ?valcheck:bool ->
                              ?att_values:(string * Pxp_types.att_value) list ->
                              Pxp_dtd.dtd ->
                              node_type ->
                              (string * string) list -> 'a node;
             create_other : ?entity_id:Pxp_types.entity_id ->
                            ?position:string * int * int ->
                            Pxp_dtd.dtd ->
                            node_type -> 'a node;
             data : string; delete : unit;
             display : ?prefixes:string Pxp_types.StringMap.t ->
                       ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] ->
                       Pxp_types.output_stream -> Pxp_types.encoding -> unit;
             display_prefix : string; dtd : Pxp_dtd.dtd;
             dump : Format.formatter -> unit; encoding : Pxp_types.rep_encoding;
             entity_id : Pxp_types.entity_id; extension : 'a;
             id_attribute_name : string; id_attribute_value : string;
             idref_attribute_names : string list;
             insert_nodes : ?pos:int -> 'a node list -> unit;
             internal_adopt : 'a node option -> int -> unit;
             internal_delete : 'a node -> unit;
             internal_init : Pxp_types.entity_id ->
                             string * int * int ->
                             Pxp_types.pool option ->
                             bool ->
                             Pxp_dtd.dtd ->
                             string ->
                             (string * string) list ->
                             (string * Pxp_types.att_value) list -> unit;
             internal_init_other : Pxp_types.entity_id ->
                                   string * int * int ->
                                   Pxp_dtd.dtd -> node_type -> unit;
             internal_set_pos : int -> unit;
             iter_nodes : ('a node -> unit) -> unit;
             iter_nodes_sibl : ('a node option ->
                                'a node ->
                                'a node option -> unit) ->
                               unit;
             local_validate : ?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit;
             localname : string; namespace_manager : Pxp_dtd.namespace_manager;
             namespace_scope : Pxp_dtd.namespace_scope; namespace_uri : string;
             namespaces_as_nodes : 'a node list;
             next_node : 'a node; node_path : int list;
             node_position : int; node_type : node_type;
             normprefix : string; nth_node : int -> 'a node;
             optional_list_attribute : string -> string list;
             optional_string_attribute : string -> string option; orphaned_clone : 'b;
             orphaned_flat_clone : 'b; parent : 'a node;
             pinstr : string -> Pxp_dtd.proc_instruction list;
             pinstr_names : string list; position : string * int * int;
             previous_node : 'a node;
             quick_set_attributes : (string * Pxp_types.att_value) list -> unit;
             remove : unit -> unit; remove_nodes : ?pos:int -> ?len:int -> unit -> unit;
             required_list_attribute : string -> string list;
             required_string_attribute : string -> string;
             reset_attribute : string -> unit; root : 'a node;
             set_attribute : ?force:bool -> string -> Pxp_types.att_value -> unit;
             set_attributes : (string * Pxp_types.att_value) list -> unit;
             set_comment : string option -> unit; set_data : string -> unit;
             set_namespace_scope : Pxp_dtd.namespace_scope -> unit;
             set_nodes : 'a node list -> unit;
             sub_nodes : 'a node list; validate : unit -> unit;
             validate_attlist : unit -> unit;
             validate_contents : ?use_dfa:bool -> ?check_data_nodes:bool -> unit -> unit;
             write : ?prefixes:string list ->
                     ?default:string ->
                     ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] ->
                     Pxp_types.output_stream -> Pxp_types.encoding -> unit;
             .. >
           as 'b

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 `clone` method on the original objects; how much of the extension objects is cloned depends on the implemention of this method.

All node types.

    method orphaned_flat_clone : 'b

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.

Domain. All node types.

## Creating new nodes by cloning exemplars

    method create_element : ?name_pool_for_attribute_values:Pxp_types.pool ->
           ?entity_id:Pxp_types.entity_id ->
           ?position:string * int * int ->
           ?valcheck:bool ->
           ?att_values:(string * Pxp_types.att_value) list ->
           Pxp_dtd.dtd ->
           node_type -> (string * string) list -> 'a node

`create_element ~name_pool_for_attribute_values ~position ~valcheck ~att_values dtd ntype att_list`: 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:

- The DTD is set to `dtd`
- The node type is set to `ntype` (which must be `T_element name`)
- The attribute list is set to the concatenation of `att_list` and `att_values`; `att_list` passes attribute values as strings while `att_values` passes attribute values as type `att_value`
- The copy does not have children nor a parent
- The copy does not contain processing instructions.
- The position triple is set to `position`
- The entity ID is set to `entity_id`

Note that the extension object is copied, too.

If `valcheck=true` (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 `valcheck=false`, any element type and any attributes are accepted.

Even in well-formedness mode, it is ok to pass `valcheck=true` as this mode is implemented by weakening the validation constraints in the DTD object. See Parsing in well-formedness mode for explanations.

If a `name_pool_for_attribute_values` is passed, the attribute values in `att_list` are put into this pool.

The optional arguments have the following defaults:

- `~name_pool_for_attribute_values`: No pool is used
- `~position`: The position is not available in the copy
- `~valcheck`: true
- `~att_values`: empty
- `~entity_id`: a new ID is used that is connected to a real entity

Domain. Elements.

    method create_data : Pxp_dtd.dtd -> string -> 'a node

`create_data dtd cdata`: 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:

- The DTD is set to `dtd`
- The character string is set to `cdata`

Note that the extension object is copied, too.

Domain. Data nodes.

    method create_other : ?entity_id:Pxp_types.entity_id ->
           ?position:string * int * int ->
           Pxp_dtd.dtd -> node_type -> 'a node

`create_other ~position dtd ntype`: 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:

- The DTD is set to `dtd`
- The position triple is set to `position`
- The entity ID is set to `entity_id`

Note that the extension object is copied, too.

The passed node type `ntype` must match the node type of this node.

Domain. Super root nodes, processing instruction nodes, comment nodes

## Namespaces

Namespace methods are only available in namespace-aware implementations of `node`. For other implementations, the exception `Pxp_types.Namespace_method_not_applicable` is raised.

Keep in mind that PXP applies prefix normalization. For an introduction see `Intro_namespaces`.

    method normprefix : string

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.

The normalized prefix is the part of the name before the colon after prefix normalization has been applied to the node.

Domain. Elements and attributes supporting namespaces.

    method display_prefix : string

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.

The display prefix is supposed to be the prefix as it occurs literally in the XML text.

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.

This method is quite slow.

Domain. Elements and attributes supporting namespaces.

    method localname : string

For namespace-aware implementations of the node class, this method returns the local part of the name of the element or attribute.

The local name is the part of the name after the colon, or the whole name if there is no colon.

Domain. Elements and attributes supporting namespaces.

    method namespace_uri : string

For namespace-aware implementations of the node class, this method returns the namespace URI of the element, attribute or namespace.

If the node does not have a namespace prefix, and there is no default namespace, this method returns "".

The namespace URI is the unique name of the namespace.

Domain. Elements and attributes supporting namespaces; furthermore namespace nodes.

    method namespace_manager : Pxp_dtd.namespace_manager

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 `Not_found` is raised.

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.

Domain. Elements and attributes supporting namespaces; furthermore namespace nodes.

    method namespace_scope : Pxp_dtd.namespace_scope

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.

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.

Domain. Elements and attributes supporting namespaces

    method set_namespace_scope : Pxp_dtd.namespace_scope -> unit

`set_namespace_scope scope`: 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.

Domain. Elements and attributes supporting namespaces

    method namespaces_as_nodes : 'a node list

Returns the namespaces found in the `namespace_scope` object and all parent scope objects (except declarations that are hidden by more recent declarations). The namespaces are returned as node objects with type `T_namespace name` where `name` is the normalized prefix.

This method should be used if it is required for typing reasons that the namespaces have also type `node`. A common example are sets that may both contain elements and namespaces, as they are used in the XPath language.

The namespace nodes are read-only; any call to a method modifying their contents will raise `Method_not_applicable`. See the class `namespace_impl` below for more information about the returned nodes.

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).

The method `namespaces_as_nodes` computes the list of namespace nodes when it is first invoked, and it will return the same list again in subsequent invocations.

See also Irregular nodes: namespace nodes and attribute nodes.

Domain. This method is only applicable to elements that support namespaces.

## Writing trees as XML text

The `write` and `display` 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 `write` method uses the normalized prefixes for this purpose. The `display` 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 `display` produces an more exact copy of the text, whereas `write` shows the prefixes as they are seen by the program.

    method write : ?prefixes:string list ->
           ?default:string ->
           ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] ->
           Pxp_types.output_stream -> Pxp_types.encoding -> unit

`write stream enc`: Write the contents of this node and the subtrees to the passed `stream` encoded as `enc`. The generated output is again XML. The output style is rather compact and should not be considered as "pretty printing".

The namespace-aware nodes use a notation with normalized prefixes. The namespace scope is ignored.

Option `~prefixes`: The class `namespace_element_impl` interprets this option and passes it recursively to subordinate invocations of `write`. 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.

Option `~default`: Specifies the normprefix that becomes the default namespace in the output.

Option `~minimization`: How to write out empty elements. ``AllEmpty` means that all empty elements are minimized (using the <name/> form). ``DeclaredEmpty` minimizes only empty elements that are declared as empty in the DTD. ``None` does not minimize at all and is the default.

Domain. All regular node types (elements, data nodes, comments, processing instructions, super root nodes).

    method display : ?prefixes:string Pxp_types.StringMap.t ->
           ?minimization:[ `AllEmpty | `DeclaredEmpty | `None ] ->
           Pxp_types.output_stream -> Pxp_types.encoding -> unit

`display stream enc`: Write the contents of this node and the subtrees to the passed `stream` encoded as `enc`. The generated output is again XML. The output style is rather compact and should not be considered as "pretty printing".

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.

Option `~prefixes`: The class `namespace_element_impl` interprets this option and passes it recursively to subordinate invocations of `display`. The mapping contains the declarations currently in effect as pairs of `(prefix,uri)`. The option defaults to [] forcing the method to output all necessary prefix declarations.

Option `~minimization`: How to write out empty elements. ``AllEmpty` means that all empty elements are minimized (using the <name/> form). ``DeclaredEmpty` minimizes only empty elements that are declared as empty in the DTD. ``None` does not minimize at all and is the default.

Domain. All regular node types (elements, data nodes, comments, processing instructions, super root nodes).

## Internals

These methods are considered as private of the implementation.

    method internal_adopt : 'a node option -> int -> unit

    method internal_set_pos : int -> unit

    method internal_delete : 'a node -> unit

    method internal_init : Pxp_types.entity_id ->
           string * int * int ->
           Pxp_types.pool option ->
           bool ->
           Pxp_dtd.dtd ->
           string ->
           (string * string) list -> (string * Pxp_types.att_value) list -> unit

    method internal_init_other : Pxp_types.entity_id ->
           string * int * int -> Pxp_dtd.dtd -> node_type -> unit

    method dump : Format.formatter -> unit