NAME

YAX::Parser - fast pure Perl tree and stream parser

SYNOPSIS

 use YAX::Parser;

 my $xml_str = <<XML
   <?xml version="1.0" ?>
   <doc>
     <content id="42"><![CDATA[
        This is a cdata section, so >>anything goes!<<
     ]]>
     </content>
     <!-- comments are nodes too -->
   </doc>
 XML

 # tree parse - the common case
 my $xml_doc = YAX::Parser->parse( $xml_str );
 my $xml_doc = YAX::Parser->parse_file( $path );

 # shallow parse
 my @tokens = YAX::Parser->tokenize( $xml_str );

 # stream parse 
 YAX::Parser->stream( $xml_str, $state, %handlers )
 YAX::Parser->stream_file( '/some/file.xml', $state, %handlers );
 

DESCRIPTION

This module implements a fast DOM and stream parser based on Robert D. Cameron's regular expression shallow parsing grammar and technique. It doesn't implement the full W3C DOM API by design. Instead, it takes a more pragmatic approach. DOM trees are constructed with everything being an object except for attributes, which are stored as a hash reference.

We also borrow some ideas from browser implementations, in particular, nodes are keyed in a table in the document on their id attributes (if present) so you can say:

 my $found = $xml_doc->get( $node_id );

Parsing is usually done by calling class methods on YAX::Parser, which, if invoked as a tree parser, returns an instance of YAX::Document

 my $xml_doc = YAX::Parser->parse( $xml_str );

METHODS

See the "SYNOPSIS" for, here's just the list for now:

parse( $xml_str )

Parse $xml_str and return a YAX::Document object.

parse_file( $path )

Same as above by read the file at $path for the input.

stream( $xml_str, $state, %handlers )

Although not its main focus, YAX::Parser also provides for stream parsing. It tries to be a bit more sane than Expat, in that it allows you to specify a state holder which can be anything and is passed as the first argument to the handler functions. A typical case is to use a hash reference with a stack (for tracking nesting):

 my $state = { stack => [ ] };

all handler functions are optional, but the full list is:

 my %handlers = (
     text => \&handle_text,          # called for text nodes
     elmt => \&handle_element_open,  # called for open tags
     elcl => \&handle_element_close, # called for tag close
     decl => \&handle_declaration,   # called for declarations
     proc => \&handle_proc_inst,     # called for processing instructions
     pass => \&handle_passthrough,   # called when no handlers match
 );

an element handler is passed the state, tag name and attributes hash:

 sub handle_element_open {
     my ( $state, $name, %attributes ) = @_;
     if ( $name eq 'a' and $attributes{href} ) {
         ... 
     }
 }

element close handlers take two arguments: state and tag name:

 sub handle_element_close {
     my ( $state, $name ) = @_;
     die "not well formed" unless pop @{ $state->{stack} } eq $name;
 }

all other handlers take the state and the entire matched token

 sub handle_proc_inst {
     my ( $state, $token ) = @_;
     $token =~ /^<\?(.*?)\?>$/;
     my $instr = $1;
     ...
 }

stream_file( $path, $state, %handlers )

Same as above by read the file at $path for the input.

tokenize( $xml_str )

Useful for quick and dirty tokenizing of $xml_str. Returns a list of tokens.

SEE ALSO

YAX::Document, YAX::Node

LICENSE

This program is free software and may be modified and distributed under the same terms as Perl itself.

AUTHOR

 Richard Hundt