NAME

Data::Transform::SAXBuilder - A filter for parsing XML with XML::LibXML

SYSNOPSIS

  use Data::Transform::SAXBuilder;
  my $filter = Data::Transform::SAXBuilder->new();

  my $wheel = POE::Wheel:ReadWrite->new(
        Filter          => $filter,
        InputEvent      => 'input_event',
  );

DESCRIPTION

Data::Transform::SAXBuilder is used to turn an XML file or stream into a (series of) DOM tree (fragments). It uses the XML::LibXML modules to do the parsing and for the building of the DOM tree. This gives you very good support for most(all?) XML features, and allows you to use a host of extra modules available for use with XML::LibXML.

To make the potentially time-consuming parsing process not interfere with event-driven environments (like POE), SAXBuolder will return a series of document fragments instead of the entire DOM tree.

There are two modes:

  • The first builds the entire DOM tree, and just gives you pointers into the tree at various points. This is useful if you know the xml document you are parsing is not too big, and you want to be able to run XPATH queries on the entire tree.

  • The second mode splits up the DOM tree into document fragments and returns each seperately. You could still build a complete DOM tree from these fragments. Sometimes that isn't possible, because you're receiving a possibly endless tree (for example when processing an XMPP stream)

You can control how often you get events by specifying till how deep into the tree you want to receive notifications. This also controls the size of the document fragments you'll receive when you're using the second, 'detached' mode.

PUBLIC METHODS

Data::Transform::SAXBuilder follows the Data::Transform API. This documentation only covers things that are special to Data::Transform::SAXBuilder.

new

The constructor accepts two arguments which are both optional:

buffer

A string that is XML waiting to be parsed

handler

A SAX Handler that builds your data structures from SAX events. The default is XML::SAX::IncrementalBuilder::LibXML, which creates DOM tree fragments. But you could create any sort of object/structure you like.

reset_parser

Resets the filter so it is ready to parse a new document from the beginning.

AUTHOR

Martijn van Beers <martijn@cpan.org>

COPYRIGHT

Copyright (c) 2006-2008 Martijn van Beers.

Based on POE::Filter::XML, which is Copyright (c) 2003 Nicholas Perez.

Released and distributed under the GPL.