class typeThe class type[< clone : 'a; node : 'a node;node =
set_node : 'a node -> unit; .. >
as 'a]object..end
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.
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
Domain.
Applicable to element, data, comment, processing instruction,
and super root nodes.
method node_type : node_typeT_element t: The node is an element with name tT_data: The node is a data nodeT_comment: The node is a comment nodeT_pinstr n: The node is a processing instruction with
target nT_super_root: The node is a super root nodeT_attribute n: The node is an attribute with name nT_namespace p: The node is a namespace with normalized prefix pmethod dtd : Pxp_dtd.dtd
Domein. All node types. However, exemplars need not to have
an associated DTD, in which case this method fails.
method encoding : Pxp_types.rep_encodingdtd. (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.
method parent : 'a nodeNot_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
Domain. All node types.
method node_position : int0 to l-1 where l is the
length of the list of regular children.0 to m-1; all namespace
nodes have positions from 0 to n-1.Not_found.method node_path : int list
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
Domain. All node types.
method iter_nodes : ('a node -> unit) -> unitobj#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) ->
unitobj#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 childpred is None if the child is the first in the list,
and Some p otherwise; p is the predecessor of chsucc is None if the child is the last in the list,
and Some s otherwise; s is the successor of chsub_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 nodenth_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 nodeNot_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 nodeNot_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.
Also see the Pxp_document.node.node_type method which returns
the type of the node, and for elements their names.
method data : stringNot_found
if the comment string is not set (see also the comment method
below for an alternate way of getting the comment string)""
if the data part is missing (see also the pinstr method
below for an alternay way of accessing processing instructions)Not_found if the attribute
is implied.method attribute : string -> Pxp_types.att_valueattribute 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
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_typeattribute_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(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 -> stringrequired_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 listrequired_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 optionoptional_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 listoptional_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 : stringID. 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 : stringID. 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 listIDREF 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 listT_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 listpinstr 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 listpinstr 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 optionSome 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.
method entity_id : Pxp_types.entity_identity_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(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_classificationclassify_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
constraintCD_other: n is not a data nodeCD_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 senseCD_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.
Domain. Elements.
method append_node : 'a node -> unitappend_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 -> unitappend_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 -> unitinsert_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
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 : unitremovemethod remove_nodes : ?pos:int -> ?len:int -> unit -> unitremove_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 -> unitset_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.
method set_data : string -> unitset_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 -> unitset_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 -> unitset_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 -> unitreset_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 -> unitset_attributesmethod add_pinstr : Pxp_dtd.proc_instruction -> unitadd_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 -> unitset_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.
method validate : unit -> unitvalidate ():
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 -> unitvalidate_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.
use_dfa: If true, the deterministic finite automaton of
regexp content models is used for validation, if available.
Defaults to false.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 -> unitvalidate_contentsmethod complement_attlist : unit -> unitcomplement_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 -> unitvalidate_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.
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 'bclone 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
Domain. All node types.
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 nodecreate_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:
dtdntype (which must be T_element name)att_list and att_values; att_list passes attribute values
as strings while att_values passes attribute values as
type att_valuepositionentity_id
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 entitymethod create_data : Pxp_dtd.dtd -> string -> 'a nodecreate_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:dtdcdata
Domain. Data nodes.
method create_other : ?entity_id:Pxp_types.entity_id ->
?position:string * int * int ->
Pxp_dtd.dtd -> node_type -> 'a nodecreate_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:dtdpositionentity_id
The passed node type ntype must match the node type
of this node.
Domain. Super root nodes, processing instruction nodes,
comment nodes
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 : stringThe 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 : stringThe 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 : stringThe 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 : stringIf 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_managerNot_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_scopeWhen 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 -> unitset_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 listnamespace_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.
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 -> unitwrite 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 -> unitdisplay 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).
These methods are considered as private of the implementation.
method internal_adopt : 'a node option -> int -> unitmethod internal_set_pos : int -> unitmethod internal_delete : 'a node -> unitmethod 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 -> unitmethod internal_init_other : Pxp_types.entity_id ->
string * int * int -> Pxp_dtd.dtd -> node_type -> unitmethod dump : Format.formatter -> unit