Module Yaxpodom

module Yaxpodom: sig .. end

Defines an XML 1.0 + XMLNS data model and provides constructors, accessors, mutators, serializers, and parsers for that model.

Data Model

type txt = string

UTF-8 encoded text

type cdata = string

UTF-8 encoded CDATA section

type qname =

`\|`	`QName of txt * txt * txt`

A QName consists of (prefix,local_part,nsURI). nsURI is provided purely as a convenience; the parser will resolve the prefix into the corresponding URI for you, but everything else ignores it.

type att =

`\|`	`Att of qname * txt Pervasives.ref`

An attribute is (name,value). The value is a ref to enable mutation.

type ele =

`\|`	`Element of qname * att list Pervasives.ref * content list Pervasives.ref`

The type of any XML elements: (name,atts,children).

type content =

`\|`	`Text of txt`
`\|`	`CDATA of cdata`
`\|`	`Comment of txt`
`\|`	`PI of txt * txt`	`(*`	`(target,value)`	`*)`
`\|`	`Subele of ele`

The type of element content.

type doc = content list Pervasives.ref * ele Pervasives.ref

A document is a list of comments and PIs, and the document element.

exception Namespace_error

Raised if some namespace processing error occurs. examples:

use of undeclared namespace
two attributes on the same element with the same local part and different prefixes that resolve to the same URI (unique att. spec)

Constructors, Accessors, and Mutators

val qname_pfx : qname -> txt

Retrieve the prefix of a QName.

val qname_local : qname -> txt

Retrieve the local-part of a QName.

val qname_nsURI : qname -> txt

Retrieve the nsURI of a QName.

val qname_eq : qname -> qname -> bool

Returns true if the two qnames have the same prefix and local part.

val qname_eq' : qname -> qname -> bool

Returns true if the two qnames have the same local part and nsURI. (Use = to determine if qnames are equal in all respects)

val att_name : att -> qname

Retrieve the QName of an attribute.

val att_value : att -> txt

Retrieve the value of an attribute.

val find_att : qname -> att list -> att

Find an attribute given its QName, using qname_eq to determine qname equality.
Raises Not_found if the attribute isn't in the list.

val find_att' : qname -> att list -> att

Ditto, except use qname_eq'

val make_ele : qname -> ele

Create an empty element.

val ele_name : ele -> qname

Retrieve the name of an element

val ele_atts : ele -> att list

Retrieve the attributes of an element

val set_ele_atts : ele -> att list -> unit

Replace the attributes of an element.

val ele_children : ele -> content list

Retrieve the children of an attribute

val set_ele_children : ele -> content list -> unit

Replace the children of an element.

val ele_append_child : ele -> content -> unit

Append a child node to an element.

val ele_prepend_child : ele -> content -> unit

Prepend a child node to an element's existing children.

val ele_get_att : ele -> qname -> txt

Get an attribute value, using qname_eq to determine qname equality.
Raises Not_found if the attribute doesn't exist

val ele_get_att' : ele -> qname -> txt

Ditto, except use qname_eq'

val ele_set_att : ele -> qname -> txt -> unit

Set an attribute value, or add the attribute if it isn't already there.

val ele_remove_att : ele -> qname -> unit

Remove an attribute, using qname_eq to determine qname equality.

val ele_remove_att' : ele -> qname -> unit

Ditto, except use qname_eq'

val ele_inner_text : ele -> txt

Returns the text contained in the first Text child of the element. Useful for processing elements expected to be of the form <ele>some-text</ele>

val doc_prolog : doc -> content list

Returns the prolog (comments and PIs) of a document

val doc_ele : doc -> ele

Returns the document element

val clone_qname : qname -> qname

val clone_att : att -> att

val clone_ele : ele -> ele

val clone_content : content -> content

Deep copy

Parsers

val build_element_tree : #Cps_reader.t -> Yaxpo.att list Stack.t -> ele

Construct an ele. The second parameter is supposed to be a stack of lists of Yaxpo attributes representing namespace declarations, so that you can carry over namespace decls if you are only parsing a document fragment. Normally, you can just pass Stack.create () .
Raises

U_char.Bad_char if an invalid character is encountered.
Utf8_char.Bad_encoding if a UTF-8 decoding error occurs.
Yaxpo.Lex_error if a lexical error is encountered.
Yaxpo.Parse_error if a parsing error is encountered.
Namespace_error if a namespace processing error is encountered.
CPS Note: build_element_tree will fail if the underlying Cps_reader.t attempts to pause parsing. To use a pausing reader, you should use the CPS version of this function below.

val build_doc_tree : #Cps_reader.t -> doc

Construct a document.
Raises

U_char.Bad_char if an invalid character is encountered.
Utf8_char.Bad_encoding if a UTF-8 decoding error occurs.
Yaxpo.Lex_error if a lexical error is encountered.
Yaxpo.Parse_error if a parsing error is encountered, or if content comes in the wrong order.
Namespace_error if a namespace processing error is encountered.
CPS Note: build_doc_tree will fail if the underlying Cps_reader.t attempts to pause parsing. To use a pausing reader, you should use the CPS version of this function below.

val build_element_tree_cps : #Cps_reader.t -> Yaxpo.att list Stack.t -> (ele -> unit) -> unit

CPS version of build_element_tree

val build_doc_tree_cps : #Cps_reader.t -> (doc -> unit) -> unit

CPS version of build_doc_tree

Serializers

val string_of_qname : qname -> string

val string_of_att : att -> string

val string_of_atts : att list -> string

val string_of_ele : ele -> string

val string_of_doc : doc -> string

General note: the parser is pretty rigorous about verifying the well-formedness of its input. however, the same is not true of the serializers! you are expected to pass the serializers only valid data. Especially note that the serializers pay no attention to the nsURI parts of qnames; you are expected to emit xmlns declarations in the right places. However, the following may be of use.

module Namespace_utils: sig .. end