NAME

       XML::SAX::Machines - manage collections of SAX processors

VERSION

       version 0.46

SYNOPSIS

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

           my $m = Pipeline(
               "My::Filter1",   ## My::Filter1 autoloaded in Pipeline()
               "My::Filter2",   ## My::Filter2     "       "      "
               \*STDOUT,        ## XML::SAX::Writer also loaded
           );

           $m->parse_uri( $uri ); ## A parser is autoloaded via
                                  ## XML::SAX::ParserFactory if
                                  ## My::Filter1 isn't a parser.

           ## To import only individual machines:
           use XML::SAX::Machines qw( Manifold );

           ## Here's a multi-pass machine that reads one document, runs
           ## it through 5 filtering channels (one channel at a time) and
           ## reassembles it in to a single document.
           my $m = Manifold(
               "My::TableOfContentsExtractor",
               "My::AbstractExtractor",
               "My::BodyFitler",
               "My::EndNotesFilter",
               "My::IndexFilter",
           );

           $m->parse_string( $doc );

DESCRIPTION

       SAX machines are a way to gather and manage SAX processors without going nuts.  Or at
       least without going completely nuts.  Individual machines can also be like SAX processors;
       they don't need to parse or write anything:

          my $w = XML::SAX::Writer->new( Output => \*STDOUT );
          my $m = Pipeline( "My::Filter1", "My::Filter2", { Handler => $w } );
          my $p = XML::SAX::ParserFactory->new( handler => $p );

       More documentation to come; see XML::SAX::Pipeline, XML::SAX::Manifold, and
       XML::SAX::Machine for now.

       Here are the machines this module knows about:

           ByRecord  Record oriented processing of documents.
                     L<XML::SAX::ByRecord>

           Machine   Generic "directed graph of SAX processors" machines.
                     L<XML::SAX::Machine>

           Manifold  Multipass document processing
                     L<XML::SAX::Manifold>

           Pipeline  A linear sequence of SAX processors
                     L<XML::SAX::Pipeline>

           Tap       An insertable pass through that examines the
                     events without altering them using SAX processors.
                     L<XML::SAX::Tap>

   Config file
       As mentioned in "LIMITATIONS", you might occasionally need to edit the config file to tell
       XML::SAX::Machine how to handle a particular SAX processor (SAX processors use a wide
       variety of API conventions).

       The config file is a the Perl module XML::SAX::Machines::SiteConfig, which contains a Perl
       data structure like:

           package XML::SAX::Machines::SiteConfig;

           $ProcessorClassOptions = {
               "XML::Filter::Tee" => {
                   ConstructWithHashedOptions => 1,
               },
           };

       So far $Processors is the only available configuration structure.  It contains a list of
       SAX processors with known special needs.

       Also, so far the only special need is the ConstructWithHashes option which tells
       XML::SAX::Machine to construct such classes like:

           XML::Filter::Tee->new(
               { Handler => $h }
           );

       instead of

           XML::Filter::Tee->new( Handler => $h );

       WARNING If you modify anything, apply your changes in a new file created from
       XML::SAX::Machines::SiteConfig.pm. On Debian systems, this should be placed in /etc/perl
       so that it is not overwritten during upgrade.  Do not alter
       XML::SAX::Machines::ConfigDefaults.pm or you will lose your changes when you upgrade.

       TODO: Allow per-app and per-machine overrides of options.  When needed.

NAME

           XML::SAX::Machines - manage collections of SAX processors

AUTHORS

       Barrie Slaymaker

LICENCE

       Copyright 2002-2009 by Barrie Slaymaker.

       This software is free.  It is licensed under the same terms as Perl itself.

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.