Module exmpp_xmlstream

The module exmpp_xmlstream sends events to a specified process or function based on elements and trees returned by the parser exmpp_xml.

Authors: Jean-Sébastien Pédron (js.pedron@meetic-corp.com).

Description

The module exmpp_xmlstream sends events to a specified process or function based on elements and trees returned by the parser exmpp_xml.

It also provides a high-level function to parse an XML document without the overhead of parser initialization.

The API isn't stabilized yet. What's left to be done:

Data Types

callback()

callback() = Gen_Fsm | Process | Function | No_Callback | Log

Represents the recipient of each event.

In case of a Gen_Fsm, the call will be:
  gen_fsm:send_event(Pid_or_Name, Event)

See gen_fsm documentation for more informations.

In case of a Process, the event is sent using the Erlang ! operator.

In case of a Function, the call will be:
  Mod:Func(Event, Extra)

So this function must have an arity of 2.

In case of No_Callback, events are accumulated and returned to parse/2 caller.

For Function, it must return {error, Reason} if an error occured or anything else if the event is accepted.

If the callback() doesn't match any of these specifications (the Log case), the event will be logged with error_logger:info_msg/2.

xmlstream()

abstract datatype: xmlstream()

Handler for the opened stream, initialized with a call to start/0 or start/1.

xmlstreamevent()

xmlstreamevent() = Stream_Start | Stream_Element | Stream_End | Error

Records representing an event sent by the parse/2 function.

Function Index

get_parser/1Return the XML parser used.
parse/2Parse a chunk of XML data and send events to the callback process or function, or return them to the caller.
parse_element/1Parse the given data.
parse_element/2Parse the given data.
reset/1Reset stream and the underlying XML parser.
send_events/2
set_wrapper_tagnames/2Reset stream and the underlying XML parser.
start/2Start a new stream handler.
start/3Start a new stream handler.
stop/1Close a stream handler.

Function Details

get_parser/1

get_parser(Xml_stream::Stream) -> Parser

Return the XML parser used.

parse/2

parse(Xml_stream::Stream, Data) -> {ok, New_Stream} | {ok, New_Stream, Events} | {error, Reason}

Parse a chunk of XML data and send events to the callback process or function, or return them to the caller.

If Data doesn't contain one or more complete XML elements, this function may not send any event.

Potential events are described by the xmlstreamevent() type.

parse_element/1

parse_element(Data) -> [XML_Element]

Parse the given data.

The XML parser is created with default options.

See also: exmpp_xml:parse_document/1, exmpp_xml:start_parser/0.

parse_element/2

parse_element(Data, Parser_Options) -> [XML_Element]

Parse the given data.

The XML parser is created with given Parser_Options options.

See also: exmpp_xml:parse_document/2, exmpp_xml:start_parser/1.

reset/1

reset(Xml_stream::Stream) -> New_Stream

Reset stream and the underlying XML parser.

send_events/2

send_events(Xml_stream, Rest) -> any()

set_wrapper_tagnames/2

set_wrapper_tagnames(Stream, TagNames) -> New_Stream

Reset stream and the underlying XML parser.

start/2

start(Callback, Parser) -> Stream

Start a new stream handler.

The XML parser is reset and options {root_depth, 1} and emit_endtag are set.

The stream will use the old xmlstreamstart tuple.

See also: exmpp_xml:reset_parser/2, exmpp_xml:start_parser/1.

start/3

start(Callback, Parser, Stream_Options) -> Stream

Start a new stream handler.

The XML parser is reset and options {root_depth, 1} and emit_endtag are set.

The stream will use the old xmlstreamstart tuple by default.

See also: exmpp_xml:reset_parser/2, exmpp_xml:start_parser/1.

stop/1

stop(Stream) -> ok | {error, Reason}

Close a stream handler.

This must be called when Stream (returned by start/2 or start/3 isn't necessary anymore.

Currently this is a NOOP.

The caller is responsible to terminate the parser.

See also: get_parser/1.


Generated by EDoc, Jan 21 2011, 01:43:52.