3.2. The class type node

General observers .

• extension: The reference to the extension object which belongs to this node (see ...).

• dtd: Returns a reference to the global DTD. All nodes of a tree must share the same DTD.

• parent: Get the father node. Raises Not_found in the case the node does not have a parent, i.e. the node is the root.

• root: Gets the reference to 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 the root, which costs time proportional to the length of the path to the root.

• sub_nodes: Returns references to the children. The returned list reflects the order of the children. For data nodes, this method returns the empty list.

• iter_nodes f: Iterates over the children, and calls f for every child in turn.

• iter_nodes_sibl f: Iterates over the children, and calls f for every child in turn. f gets as arguments the previous node, the current node, and the next node.

• node_type: Returns either T_data which means that the node is a data node, or T_element n which means that the node is an element of type n. If configured, possible node types are also T_pinstr t indicating that the node represents a processing instruction with target t, and T_comment in which case the node is a comment.

• encoding: Returns the encoding of the strings.

• data: Returns the character data of this node and all children, concatenated as one string. The encoding of the string is what the method encoding returns. - For data nodes, this method simply returns the represented characters. For elements, the meaning of the method has been extended such that it returns something useful, i.e. the effectively contained characters, without markup. (For T_pinstr and T_comment nodes, the method returns the empty string.)

• position: If configured, this method returns the position of the element as triple (entity, line, byteposition). For data nodes, the position is not stored. If the position is not available the triple "?", 0, 0 is returned.

• comment: Returns Some text for comment nodes, and None for other nodes. The text is everything between the comment delimiters <-- and -->.

• pinstr n: Returns all processing instructions that are directly contained in this element and that have a target specification of n. The target is the first word after the <?.

• pinstr_names: Returns the list of all targets of processing instructions directly contained in this element.

• write s enc: Prints the node and all subnodes to the passed output stream as valid XML text, using the passed external encoding.

Attribute observers .

• attribute n: Returns the value of the attribute with name n. This method returns a value for every declared attribute, 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. - Possible values are:

  • Implied_value: The attribute has been declared with the keyword #IMPLIED, and the attribute is missing in the attribute list of this 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 present in the attribute list in which case the value is returned in the string s. (2) The attribute has been omitted, and the DTD declared 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.

  • Valuelist l: The attribute has been declared as type IDREFS, as ENTITIES, or as NMTOKENS, and one of the two conditions holds: (1) The attribute value is present 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 declared 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, expansion is performed recursively.

  In well-formedness mode, there is no DTD which could declare an attribute. Because of this, every occuring attribute is considered as a CDATA attribute.

• required_string_attribute n: returns the Value attribute called n, or the Valuelist attribute as a string where the list elements are separated by spaces. If the attribute value is implied, or if the attribute does not exists, the method will fail. - This method is convenient if you expect a non-implied and non-list attribute value.

• optional_string_attribute n: returns the Value attribute called n, or the Valuelist attribute as a string where the list elements are separated by spaces. If the attribute value is implied, or if the attribute does not exists, the method returns None. - This method is convenient if you expect a non-list attribute value including the implied value.

• required_list_attribute n: returns the Valuelist attribute called n, or the Value attribute as a list with a single element. If the attribute value is implied, or if the attribute does not exists, the method will fail. - This method is convenient if you expect a list attribute value.

• optional_list_attribute n: returns the Valuelist attribute called n, or the Value attribute as a list with a single element. If the attribute value is implied, or if the attribute does not exists, an empty list will be returned. - This method is convenient if you expect a list attribute value or the implied value.

• attribute_names: returns the list of all attribute names of this element. As this is a validating parser, this list is equal to the list of declared attributes.

• attribute_type n: returns the type of the attribute called n. See the module Pxp_types for a description of the encoding of the types.

• attributes: returns the list of pairs of names and values for all attributes of this element.

• id_attribute_name: returns the name of the attribute that is declared with type ID. There is at most one such attribute. The method raises Not_found if there is no declared ID attribute for the element type.

• id_attribute_value: returns the value of the attribute that is declared with type ID. There is at most one such attribute. The method raises Not_found if there is no declared ID attribute for the element type.

• idref_attribute_names: returns the list of attribute names that are declared as IDREF or IDREFS.

Modifying methods . The following methods are only defined for element nodes (more exactly: the methods are defined for data nodes, too, but fail always).

• add_node sn: Adds sub node sn to the list of children. This operation is illustrated in the picture A node can only be added if it is a root. This method expects that sn is a root, and it requires that sn and the current object share the same DTD.

  Because add_node is the method the parser itself uses to add new nodes to the tree, it performs by default some simple validation checks: If the content model is a regular expression, it is not allowed to add data nodes to this node unless the new nodes consist only of whitespace. In this case, the new data nodes are silently dropped (you can change this by invoking keep_always_whitespace_mode).

  If the document is flagged as stand-alone, these data nodes only containing whitespace are even forbidden if the element declaration is contained in an external entity. This case is detected and rejected.

  If the content model is EMPTY, it is not allowed to add any data node unless the data node is empty. In this case, the new data node is silently dropped.

  These checks only apply if there is a DTD. In well-formedness mode, it is assumed that every element is declared with content model ANY which prohibits any validation check. Furthermore, you turn these checks off by passing ~force:true as first argument.

• add_pinstr pi: Adds the processing instruction pi to the list of processing instructions.

• delete: Deletes this node from the tree. After this operation, this node is no longer the child of the former father node; and the node loses the connection to the father as well. This operation is illustrated by the figure A deleted node becomes the root of the subtree.

• set_nodes nl: Sets the list of children to nl. It is required that every member of nl is a root, and that all members and the current object share the same DTD. Unlike add_node, no validation checks are performed.

• quick_set_attributes atts: sets the attributes of this element to atts. It is not checked whether atts matches the DTD or not; it is up to the caller of this method to ensure this. (This method may be useful to transform the attribute values, i.e. apply a mapping to every attribute.)

• set_comment text: This method is only applicable to T_comment nodes; it sets the comment text contained by such nodes.

Cloning methods .

• orphaned_clone: 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; it is likely that 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.

  This operation is illustrated by the figure The clone of a subtree.

• orphaned_flat_clone: Returns a clone of the node, but sets the list of sub nodes to [], i.e. the sub nodes are not cloned.

• create_element dtd nt al: Returns a flat copy of this node (which must be an element) with the following modifications: The DTD is set to dtd; the node type is set to nt, and the new attribute list is set to al (given as list of (name,value) pairs). The copy does not have children nor a parent. It does not contain processing instructions. See the example below.

  Note that you can specify the position of the new node by the optional argument ~position.

• create_data dtd cdata: Returns a flat copy of this node (which must be a data node) with the following modifications: The DTD is set to dtd; the node type is set to T_data; the attribute list is empty (data nodes never have attributes); the list of children and PIs is empty, too (same reason). The new node does not have a parent. The value cdata is the new character content of the node. See the example below.

• keep_always_whitespace_mode: Even data nodes which are normally dropped because they only contain ignorable whitespace, can added to this node once this mode is turned on. (This mode is useful to produce canonical XML.)

Validating methods . There is one method which locally validates the node, i.e. checks whether the subnodes match the content model of this node.

• local_validate: Checks that this node conforms to the DTD by comparing the type of the subnodes with the content model for this node. (Applications need not call this method unless they add new nodes themselves to the tree.)

Constructor. You can create a new instance by

new element_impl extension_object

Example. First, create an exemplar by

let exemplar_ext = ... in
let exemplar     = new element_impl exemplar_ext in

let element = exemplar # create_element dtd (T_element name) attlist 

Constructor. You can create a new instance by

new data_impl extension_object

Example. First, create an exemplar by

let exemplar_ext = ... in
let exemplar     = new exemplar_ext data_impl in

let data_node = exemplar # create_data dtd "The characters contained in the data node" 

Building trees. Here is the piece of code that creates the tree of the figure A tree with element nodes, data nodes, and attributes. The extension object and the DTD are beyond the scope of this example.

let exemplar_ext = ... (* some extension *) in
let dtd = ... (* some DTD *) in

let element_exemplar = new element_impl exemplar_ext in
let data_exemplar    = new data_impl    exemplar_ext in

let a1 = element_exemplar # create_element dtd (T_element "a") ["att", "apple"]
and b1 = element_exemplar # create_element dtd (T_element "b") []
and c1 = element_exemplar # create_element dtd (T_element "c") []
and a2 = element_exemplar # create_element dtd (T_element "a") ["att", "orange"]
in

let cherries = data_exemplar # create_data dtd "Cherries" in
let orange   = data_exemplar # create_data dtd "An orange" in

a1 # add_node b1;
a1 # add_node c1;
b1 # add_node a2;
b1 # add_node cherries;
a2 # add_node orange;

a1 # set_nodes [b1; c1];
b1 # set_nodes [a2; cherries];
a2 # set_nodes [orange];

x # root == a1

Searching nodes. The following function searches all nodes of a tree for which a certain condition holds:

let rec search p t =
  if p t then
    t :: search_list p (t # sub_nodes)
  else
    search_list p (t # sub_nodes)

and search_list p l =
  match l with
    []      -> []
  | t :: l' -> (search p t) @ (search_list p l')
;;

Getting attribute values. Suppose we have the declaration:

<!ATTLIST e a CDATA #REQUIRED
            b CDATA #IMPLIED
            c CDATA "12345">

let value_of_a = n # required_string_attribute "a"

let value_of_a = 
  match n # attribute "a" with
    Value s -> s
  | _       -> assert false