Xml (cow.Cow.Xml)

include module type of Xmlm

Basic types and values

type encoding = [

`\|` `UTF_8
`\|` `UTF_16	Endianness determined from the BOM.
`\|` `UTF_16BE
`\|` `UTF_16LE
`\|` `ISO_8859_1
`\|` `US_ASCII

]

The type for character encodings. For `UTF_16, endianness is determined from the BOM.

type dtd = string option

The type for the optional DTD.

type name = string * string

The type for attribute and element's expanded names (uri,local). An empty uri represents a name without a namespace name, i.e. an unprefixed name that is not under the scope of a default namespace.

type attribute = name * string

The type for attributes. Name and attribute data.

type tag = name * attribute list

The type for an element tag. Tag name and attribute list.

type signal = [

| `Dtd of dtd

| `El_start of tag

| `El_end

| `Data of string

]

The type for signals. A well-formed sequence of signals belongs to the language of the doc grammar :

doc ::= `Dtd tree
tree ::= `El_start child `El_end
child ::= `Data trees | trees
trees ::= tree child | epsilon

The trees production is used to expresses the fact that there will never be two consecutive `Data signals in the children of an element.

Input and output deal only with well-formed sequences or exceptions are raised. However on output consecutive `Data signals are allowed.

val ns_xml : string

Namespace name value bound to the reserved "xml" prefix.

val ns_xmlns : string

Namespace name value bound to the reserved "xmlns" prefix.

val pp_dtd : Stdlib.Format.formatter -> dtd -> unit

pp_dtd ppf dtd prints an unspecified representation of dtd on ppf.

val pp_name : Stdlib.Format.formatter -> name -> unit

pp_name ppf name prints an unspecified representation of name on ppf.

val pp_attribute : Stdlib.Format.formatter -> attribute -> unit

pp_attribute ppf att prints an unspecified representation of att on ppf.

val pp_tag : Stdlib.Format.formatter -> tag -> unit

pp_tag ppf tag prints an unspecified representation of tag on ppf.

val pp_signal : Stdlib.Format.formatter -> signal -> unit

pp_signal ppf s prints an unspecified representation of s on ppf.

Input

type pos = int * int

The type for input positions. Line and column number, both start with 1.

type error = [

`\|` `Max_buffer_size	Maximal buffer size exceeded (`Sys.max_string_length`).
`\|` `Unexpected_eoi	Unexpected end of input.
`\|` `Malformed_char_stream	Malformed underlying character stream.
`\|` `Unknown_encoding of string	Unknown encoding.
`\|` `Unknown_entity_ref of string	Unknown entity reference, details.
`\|` `Unknown_ns_prefix of string	Unknown namespace prefix details
`\|` `Illegal_char_ref of string	Illegal character reference.
`\|` `Illegal_char_seq of string	Illegal character sequence.
`\|` `Expected_char_seqs of string list * string	Expected one of the character sequences in the list but found another.
`\|` `Expected_root_element	Expected the document's root element.

]

The type for input errors.

val error_message : error -> string

Converts the error to an english error message.

exception Error of pos * error

Raised on input errors.

type source = [

| `Channel of Stdlib.in_channel

| `String of int * string

| `Fun of unit -> int

]

The type for input sources. For `String starts reading at the given integer position. For `Fun the function must return the next byte as an int and raise End_of_file if there is no such byte.

type input

The type for input abstractions.

val make_input : ?⁠enc:encoding option -> ?⁠strip:bool -> ?⁠ns:(string -> string option) -> ?⁠entity:(string -> string option) -> source -> input

Returns a new input abstraction reading from the given source.

enc, character encoding of the document, details. Defaults to None.
strip, strips whitespace in character data, details. Defaults to false.
ns is called to bind undeclared namespace prefixes, details. Default returns always None.
entity is called to resolve non predefined entity references, details. Default returns always None.

val input : input -> signal

Inputs a signal. Repeated invocation of the function with the same input abstraction will generate a well-formed sequence of signals or an Error is raised. Furthermore there will be no two consecutive `Data signals in the sequence and their string is always non empty.

Deprecated After a well-formed sequence was input another may be input, see eoi and details.

Raises Error on input errors.

val input_tree : el:(tag -> 'a list -> 'a) -> data:(string -> 'a) -> input -> 'a

If the next signal is a :

`Data signal, inputs it and invokes data with the character data.
`El_start signal, inputs the sequence of signals until its matching `El_end and invokes el and data as follows
- el, is called on each `El_end signals with the corresponding `El_start tag and the result of the callback invocation for the element's children.
- data, is called on each `Data signals with the character data. This function won't be called twice consecutively or with the empty string.
Other signals, raises Invalid_argument.

Raises Error on input errors and Invalid_argument if the next signal is not `El_start or `Data.

val input_doc_tree : el:(tag -> 'a list -> 'a) -> data:(string -> 'a) -> input -> dtd * 'a

Same as input_tree but reads a complete well-formed sequence of signals.

Raises Error on input errors and Invalid_argument if the next signal is not `Dtd.

val peek : input -> signal

Same as Input but doesn't remove the signal from the sequence.

Raises Error on input errors.

val eoi : input -> bool

Returns true if the end of input is reached. See details.

Raises Error on input errors.

val pos : input -> pos

Current position in the input abstraction.

Output

type 'a frag = [

| `El of tag * 'a list

| `Data of string

]

The type for deconstructing data structures of type 'a.

type dest = [

| `Channel of Stdlib.out_channel

| `Buffer of Stdlib.Buffer.t

| `Fun of int -> unit

]

The type for output destinations. For `Buffer, the buffer won't be cleared. For `Fun the function is called with the output bytes as ints.

type output

The type for output abstractions.

val make_output : ?⁠decl:bool -> ?⁠nl:bool -> ?⁠indent:int option -> ?⁠ns_prefix:(string -> string option) -> dest -> output

Returns a new output abstraction writing to the given destination.

decl, if true the XML declaration is output (defaults to true).
nl, if true a newline is output when the root's element `El_end signal is output. Defaults to false.
indent, identation behaviour, see details. Defaults to None.
ns_prefix, undeclared namespace prefix bindings, see details. Default returns always None.

val output : output -> signal -> unit

Outputs a signal.

Deprecated. After a well-formed sequence of signals was output a new well-formed sequence can be output.

Raises Invalid_argument if the resulting signal sequence on the output abstraction is not well-formed or if a namespace name could not be bound to a prefix.

val output_depth : output -> int

output_depth o is o's current element nesting level (undefined before the first `El_start and after the last `El_end).

val output_tree : ('a -> 'a frag) -> output -> 'a -> unit

Outputs signals corresponding to a value by recursively applying the given value deconstructor.

Raises see Output.

val output_doc_tree : ('a -> 'a frag) -> output -> (dtd * 'a) -> unit

Same as output_tree but outputs a complete well-formed sequence of signals.

Raises see Output.

Functorial interface (deprecated)

type std_string = string

type std_buffer = Stdlib.Buffer.t

module type String = sig ... end

Input signature for strings.

module type Buffer = sig ... end

Input signature for internal buffers.

module type S = sig ... end

Output signature of Make.

module Make : functor (String : String) -> functor (Buffer : Buffer with type string = String.t) -> S with type string = String.t

Functor building streaming XML IO with the given strings and buffers.

Features and limitations

Input

Encoding

White space handling

Namespaces

Character and entity references

Sequences of documents (deprecated)

WARNING. This feature is deprecated and will be removed.

When a well-formed sequence of signals is input, no data is consumed beyond the closing '>' of the document's root element.

If you want to parse a document as defined in the XML specification, call eoi after a well-formed sequence of signals, it must return true. If you expect another document on the same input abstraction a new well-formed sequence of signals can be Input. Use eoi to check if a document follows (this may consume data).

Invoking eoi after a well-formed sequence of signals skips whitespaces, comments and processing instructions until it gets to either an XML declaration or a DTD or the start of a new element or the end of input (in which case eoi returns true). If there is a new document but there is no XML declaration or the declaration specifies UTF-16, the same encoding as for the previous document is used.

Miscellaneous

Output

Encoding

Namespaces

Xmlm's names are expanded names. Expanded names are automatically converted to qualified names by the output abstraction. There is no particular api to specify prefixes and default namespaces, the actual result depends solely on the output of attributes belonging to the ns_xmlns namespace. For example to set the default namespace of an element to http://example.org/myns, use the following attribute :

(* xmlns='http://example.org/myns' *)
let default_ns = (Xmlm.ns_xmlns, "xmlns"), "http://example.org/myns"

To bind the prefix "ex" to http://example.org/ex, use the following attribute :

(* xmlns:ex='http://example.org/ex' *)
let ex_ns = (Xmlm.ns_xmlns, "ex"), "http://example.org/ex"

Note that outputing input signals without touching namespace declaration attributes will preserve existing prefixes and bindings provided the same namespace name is not bound to different prefixes in a given context.

The callback ns_prefix of an output abstraction can be used to give a prefix to a namespace name lacking a prefix binding in the current output scope. Given a namespace name the function must return the prefix to use. Note that this will not add any namespace declaration attribute to the output. If the function returns None, Output will raise Invalid_argument. The default function returns always None.

Indentation

Sequences of documents (deprecated)

Miscellaneous

Tips

Examples

Sequential processing

Sequential processing has the advantage that you don't need to get the whole document tree in memory to process it.

The following function reads a single document on an input channel and outputs it.

let id ic oc =
let i = Xmlm.make_input (`Channel ic) in
let o = Xmlm.make_output (`Channel oc) in
let rec pull i o depth =
  Xmlm.output o (Xmlm.peek i);
  match Xmlm.input i with
  | `El_start _ -> pull i o (depth + 1)
  | `El_end -> if depth = 1 then () else pull i o (depth - 1)
  | `Data _ -> pull i o depth
  | `Dtd _ -> assert false
in
Xmlm.output o (Xmlm.input i); (* `Dtd *)
pull i o 0;
if not (Xmlm.eoi i) then invalid_arg "document not well-formed"

The following function reads a sequence of documents on an input channel and outputs it.

let id_seq ic oc =
let i = Xmlm.make_input (`Channel ic) in
let o = Xmlm.make_output ~nl:true (`Channel oc) in
while not (Xmlm.eoi i) do Xmlm.output o (Xmlm.input i) done

The following function reads a sequence of documents on the input channel. In each document's tree it prunes non root elements whose name belongs to prune_list.

let prune_docs prune_list ic oc =
let i = Xmlm.make_input (`Channel ic) in
let o = Xmlm.make_output ~nl:true (`Channel oc) in
let copy i o = Xmlm.output o (Xmlm.input i) in
let prune (name, _) = List.mem name prune_list in
let rec process i o d =
  let rec skip i d = match Xmlm.input i with
  | `El_start _ -> skip i (d + 1)
  | `El_end -> if d = 1 then () else skip i (d - 1)
  | s -> skip i d
  in
  match Xmlm.peek i with
  | `El_start tag when prune tag -> skip i 0; process i o d
  | `El_start _ -> copy i o; process i o (d + 1)
  | `El_end -> copy i o; if d = 0 then () else process i o (d - 1)
  | `Data _ -> copy i o; process i o d
  | `Dtd _ -> assert false
in
let rec docs i o =
  copy i o; (* `Dtd *)
  copy i o; (* root start *)
  process i o 0;
  if Xmlm.eoi i then () else docs i o
in
docs i o

Tree processing

A document's sequence of signals can be easily converted to an arborescent data structure. Assume your trees are defined by :

type tree = E of Xmlm.tag * tree list | D of string

The following functions input/output xml documents from/to abstractions as value of type tree.

let in_tree i =
  let el tag childs = E (tag, childs)  in
  let data d = D d in
  Xmlm.input_doc_tree ~el ~data i

let out_tree o t =
  let frag = function
  | E (tag, childs) -> `El (tag, childs)
  | D d -> `Data d
  in
  Xmlm.output_doc_tree frag o t

Tabular data processing

We show how to process XML data that represents tabular data (some people like do that).

The file we need to deal with represents nominal data about W3C bureaucrats. There are no namespaces and attributes are ignored. The element structure of the document is :

<list>
- <bureaucrat> represents a W3C bureaucrat (zero or more).
  A bureaucrat contains the following elements, in order.
  - <name> its name (mandatory, string).
  - <surname> its surname (mandatory, string).
  - <honest> present iff he implemented one of its spec (optional, empty).
  - <obfuscation_level> its grade on the open scale of obfuscation (mandatory, float).
  - <tr> (zero or more, string), technical reports he worked on.

In OCaml we represent a W3C bureaucrat by this type :

type w3c_bureaucrat = {
  name : string;
  surname : string;
  honest : bool;
  obfuscation_level : float;
  trs : string list; }

The following functions input and output W3C bureaucrats as lists of values of type w3c_bureaucrat.

let in_w3c_bureaucrats src =
  let i = Xmlm.make_input ~strip:true src in
  let tag n = ("", n), [] in
  let error () = invalid_arg "parse error" in
  let accept s i = if Xmlm.input i = s then () else error () in
  let rec i_seq el acc i = match Xmlm.peek i with
  | `El_start _ -> i_seq el ((el i) :: acc) i
  | `El_end -> List.rev acc
  | _ -> error ()
  in
  let i_el n i =
    accept (`El_start (tag n)) i;
    let d = match Xmlm.peek i with
    | `Data d -> ignore (Xmlm.input i); d
    | `El_end -> ""
    | _ -> error ()
    in
    accept (`El_end) i;
    d
  in
  let i_bureaucrat i =
    try
      accept (`El_start (tag "bureaucrat")) i;
      let name = i_el "name" i in
      let surname = i_el "surname" i in
      let honest = match Xmlm.peek i with
      | `El_start (("", "honest"), []) -> ignore (i_el "honest" i); true
      | _ -> false
      in
      let obf = float_of_string (i_el "obfuscation_level" i) in
      let trs = i_seq (i_el "tr") [] i in
      accept (`El_end) i;
      { name = name; surname = surname; honest = honest;
        obfuscation_level = obf; trs = trs }
    with
    | Failure _ -> error () (* float_of_string *)
  in
  accept (`Dtd None) i;
  accept (`El_start (tag "list")) i;
  let bl = i_seq i_bureaucrat [] i in
  accept (`El_end) i;
  if not (Xmlm.eoi i) then invalid_arg "more than one document";
  bl

let out_w3c_bureaucrats dst bl =
  let tag n = ("", n), [] in
  let o = Xmlm.make_output ~nl:true ~indent:(Some 2) dst in
  let out = Xmlm.output o in
  let o_el n d =
    out (`El_start (tag n));
    if d <> "" then out (`Data d);
    out `El_end
  in
  let o_bureaucrat b =
    out (`El_start (tag "bureaucrat"));
    o_el "name" b.name;
    o_el "surname" b.surname;
    if b.honest then o_el "honest" "";
    o_el "obfuscation_level" (string_of_float b.obfuscation_level);
    List.iter (o_el "tr") b.trs;
    out `El_end
  in
  out (`Dtd None);
  out (`El_start (tag "list"));
  List.iter o_bureaucrat bl;
  out (`El_end)

type t = 'a frag as 'a frag list

The type for XML fragments.

val to_string : ?⁠decl:bool -> t -> string

val of_string : ?⁠entity:(string -> string option) -> ?⁠enc:encoding -> string -> t

of_string s returns the XML tree described by s.

parameter entity: is called to resolve non predefined entity references such as "&". It must return an UTF-8 string corresponding to the replacement character data. By default, only predefined entities, i.e., "<", ">", "&", "'", and """, are recognized.

parameter enc: The encoding of the document. Default None which means that one does not know the encoding.

Combinators

val empty : t

empty is the empty XML fragment.

val string : string -> t

string s is the XML fragment s.

val int : int -> t

int i is the XML fragment i.

val float : float -> t

float f is the XML fragment f.

val list : t list -> t

list xs is the XML fragment x1 ... xn.

val some : t option -> t

some t is t if it's not empty, empty otherwise.

val uri : Uri.t -> t

uri t is t.

val tag : string -> ?⁠attrs:(string * string) list -> t -> t

tag k v is <k>v</k>

val tago : string -> ?⁠attrs:(string * string) list -> t option -> t

tago k v is k v if v is not None, otherwise it's empty.

val (++) : t -> t -> t

x ++ y is x y

`\|` `UTF_8
`\|` `UTF_16	Endianness determined from the BOM.
`\|` `UTF_16BE
`\|` `UTF_16LE
`\|` `ISO_8859_1
`\|` `US_ASCII