Module Xmlc.Parser

Parser Combinators for XML signals

type 'a t

A parser that returns value of type 'a.

Exceptions

exception Failure of string * Xmlm.signal option

Raised when parsing fails.

exception End_of_stream

Raised when end of stream is encountered unexpectedly.

Combinators

val return : 'a -> 'a t

return v creates a parser that will always succeed and return v.

val fail : exn -> 'a t

fail exn creates a parser that will always fail with the exception exn.

val fail_with : ?signal:Xmlm.signal -> string -> 'a t

fail_with msg creates a parser that will always fail with the message msg. If an optional signal is provided the error message is annotated with signal.

val (>>=) : 'a t -> ('a -> 'b t) -> 'b t

p >>= f creates a parser that will run p, pass its result to f and run the parser that f produces, and returns its result.

val (>>|) : 'a t -> ('a -> 'b) -> 'b t

p >>| f creates a parser that will run p, and if it succeeds with result v, will return f v

val (<$>) : ('a -> 'b) -> 'a t -> 'b t

f <*> p is equivalent to f >>= fun f -> p >>| f.

val (<*>) : ('a -> 'b) t -> 'a t -> 'b t

f <$> p is equivalent to p >>| f

val (*>) : _ t -> 'a t -> 'a t

p <* q runs p, then runs q, discards its result, and returns the result of p.

val (<*) : 'a t -> _ t -> 'a t

p <* q runs p, then runs q, discards its result, and returns the result of p.

val (<?>) : 'a t -> string -> 'a t

p <?> msg returns a parser that runs p and returns the result of p if p succeeds. If p fails the parser fails with message msg.

val (<|>) : 'a t -> 'a t -> 'a t

p <|> q returns a parser that runs p and returns the result of p if p succeeds. If p fails q is run.

val choice : ?failure_msg:string -> 'a t list -> 'a t

choice ?failure_msg ts runs each parser in ts in order until one succeeds and returns that result. In the case that none of the parser succeeds, then the parser will fail with the message failure_msg, if provided, or a much less informative message otherwise.

val option : 'a t -> 'a option t

option p returns a parser that runs p and returns the result of p as Some _ or None if p fails.

val fix : ('a t -> 'a t) -> 'a t

fix f computes the fixpoint of f and runs the resultant parser. The argument that f receives is the result of fix f, which f must use, paradoxically, to define fix f.

val many : 'a t -> 'a list t

many p runs p zero or more times and returns a list of results from the runs of p.

val stream_end : unit t

stream_end succeeds if the end of input is reached and fails otherwise.

XML Signal Parsers

val dtd : string option t

dtd returns a parser that returns a XML DTD definition.

val data : string t

data reads an XML data signal.

val any_el_start : Xmlm.tag t

any_el_start reads an XML element start and returns the tag.

val el_start : Xmlm.name -> Xmlm.attribute list t

el_start name returns a parser that reads an XML element start with name and returns the attributes.

val el_end : unit t

el_end reads an XML element end signal.

XML Element parsers

These are useful combinations of the XML signal parsers.

val element : Xmlm.name -> (Xmlm.attribute list -> 'b t) -> 'b t

element name f returns a parser that reads an XML element with name and runs the parer resulting by apply f on the attributes of the XML element followed by an el_end parser.

val any_element : (Xmlm.tag -> 'a t) -> 'a t

any_element name f returns a parser that reads any XML element and runs the parer resulting by apply f on the tag of the XML element followed by an el_end parser.

val ignore_any : unit t

ignore_any reads one XML element or data item and ignores it.

val ignore_element : unit t

ignore_element reads one XML and ignores it.

val complex : ?required:Xmlm.name list -> ?ignore_other:bool -> Xmlm.name -> (Xmlm.attribute list -> 'a t) -> (Xmlm.name * ('a -> 'a)) t list -> 'a t

complex ~required name root children returns a parser for a complex object name that is represented with multiple XML child elements that appear in an unspecified order. The root parser is applied to the root element and provides a base object.

If the root element does not have any children complex will return the same parser as root (if no required fields are specified).

Child elements are parsed with the first succeeding parser in children whose elements returns a transformation of the base object.

If a required argument is provided the returned parser will fail if there is no child with given name for every member of required.

If ignore_others (defaults: false) is set then child elements that can not be parsed with parsers in children are ignored.

complex is useful for parsing complex data types such as Atom entries, where there are many optional child elements that may appear in unspecified order.

module Attributes : sig ... end

Helpers for getting attribute values

val parse_stream : 'a t -> Xmlm.signal Lwt_stream.t -> 'a Lwt.t