NAME

       XML::SAX::ByRecord - Record oriented processing of (data) documents

VERSION

       version 0.46

SYNOPSIS

           use XML::SAX::Machines qw( ByRecord ) ;

           my $m = ByRecord(
               "My::RecordFilter1",
               "My::RecordFilter2",
               ...
               {
                   Handler => $h, ## optional
               }
           );

           $m->parse_uri( "foo.xml" );

DESCRIPTION

       XML::SAX::ByRecord is a SAX machine that treats a document as a series of records.
       Everything before and after the records is emitted as-is while the records are excerpted
       in to little mini-documents and run one at a time through the filter pipeline contained in
       ByRecord.

       The output is a document that has the same exact things before, after, and between the
       records that the input document did, but which has run each record through a filter.  So
       if a document has 10 records in it, the per-record filter pipeline will see 10 sets of (
       start_document, body of record, end_document ) events.  An example is below.

       This has several use cases:

       •   Big, record oriented documents

           Big documents can be treated a record at a time with various DOM oriented processors
           like XML::Filter::XSLT.

       •   Streaming XML

           Small sections of an XML stream can be run through a document processor without
           holding up the stream.

       •   Record oriented style sheets / processors

           Sometimes it's just plain easier to write a style sheet or SAX filter that applies to
           a single record at at time, rather than having to run through a series of records.

   Topology
       Here's how the innards look:

          +-----------------------------------------------------------+
          |                  An XML:SAX::ByRecord                     |
          |    Intake                                                 |
          |   +----------+    +---------+         +--------+  Exhaust |
        --+-->| Splitter |--->| Stage_1 |-->...-->| Merger |----------+----->
          |   +----------+    +---------+         +--------+          |
          |               \                            ^              |
          |                \                           |              |
          |                 +---------->---------------+              |
          |                   Events not in any records               |
          |                                                           |
          +-----------------------------------------------------------+

       The "Splitter" is an XML::Filter::DocSplitter by default, and the "Merger" is an
       XML::Filter::Merger by default.  The line that bypasses the "Stage_1 ..." filter pipeline
       is used for all events that do not occur in a record.  All events that occur in a record
       pass through the filter pipeline.

   Example
       Here's a quick little filter to uppercase text content:

           package My::Filter::Uc;

           use vars qw( @ISA );
           @ISA = qw( XML::SAX::Base );

           use XML::SAX::Base;

           sub characters {
               my $self = shift;
               my ( $data ) = @_;
               $data->{Data} = uc $data->{Data};
               $self->SUPER::characters( @_ );
           }

       And here's a little machine that uses it:

           $m = Pipeline(
               ByRecord( "My::Filter::Uc" ),
               \$out,
           );

       When fed a document like:

           <root> a
               <rec>b</rec> c
               <rec>d</rec> e
               <rec>f</rec> g
           </root>

       the output looks like:

           <root> a
               <rec>B</rec> c
               <rec>C</rec> e
               <rec>D</rec> g
           </root>

       and the My::Filter::Uc got three sets of events like:

           start_document
           start_element: <rec>
           characters:    'b'
           end_element:   </rec>
           end_document

           start_document
           start_element: <rec>
           characters:    'd'
           end_element:   </rec>
           end_document

           start_document
           start_element: <rec>
           characters:   'f'
           end_element:   </rec>
           end_document

NAME

       XML::SAX::ByRecord - Record oriented processing of (data) documents

METHODS

       new
               my $d = XML::SAX::ByRecord->new( @channels, \%options );

           Longhand for calling the ByRecord function exported by XML::SAX::Machines.

CREDIT

       Proposed by Matt Sergeant, with advise by Kip Hampton and Robin Berjon.

Writing an aggregator.

       To be written.  Pretty much just that "start_manifold_processing" and
       "end_manifold_processing" need to be provided.  See XML::Filter::Merger and it's source
       code for a starter.

AUTHORS

       •   Barry Slaymaker

       •   Chris Prather <chris@prather.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Barry Slaymaker.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.