XML::SAX::Machines(3pm) 				User Contributed Perl Documentation				   XML::SAX::Machines(3pm)

NAME

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

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.

AUTHORS

       Barrie Slaymaker

LICENCE

       Copyright 2002-2009 by Barrie Slaymaker.

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

perl v5.10.0							    2009-09-02						   XML::SAX::Machines(3pm)