=head1 Using PatAct Modules

This document is targeted towards people who want to write scripts or
modules that use pattern and action modules.  If you want to create a
new pattern or action module, please see ``Creating PatAct Modules.''

You would want to use pattern/action modules if you want to apply a
complex set of patterns or queries against an XML instance and perform
actions associated with those patterns or queries.  To be able to use
pattern/action modules you will need a pattern-matching module that
supports the format of the pattern or query language you can use and
an action module that will perform the types of actions you need to
perform.

Available pattern-matching modules are:

  XML::PatAct::
  ::MatchName    Simple element name, element hierarchy matching

Available action modules are:

  XML::PatAct::
  ::ToObjects    Convert XML instances into Perl objects
  ::Amsterdam    Simplistic style-sheet using before/after strings

Using pattern/action modules involves loading the modules, creating a
pattern/action list, creating instances of the pattern and matching
modules, and then starting a parse using the matching module as a
handler:

  use XML::Parser::PerlSAX;
  use XML::PatAct::MatchName;
  use XML::PatAct::ToObjects;

  my $patterns = [
      'schema'      => [ qw{ -holder                    } ],
      'table'       => [ qw{ -make Schema::Table        } ],
      'name'        => [ qw{ -field Name -as-string     } ],
  ];

  my $matcher = XML::PatAct::MatchName->new( Patterns => $patterns );
  my $handler = XML::PatAct::ToObjects->new( Patterns => $patterns,
                                             Matcher => $matcher);

  my $parser = XML::Parser::PerlSAX->new( Handler => $handler );
  my $schema = $parser->parse(Source => { SystemId => $ARGV[0] } );

The example above use the MatchName and ToObjects pattern and action
modules.  The pattern list contains pairs of patterns and actions in
the format specified by MatchName and ToObjects, other modules will
use other formats.  The patterns that MatchName supports are a simple
element name or a hierarchy of element names.  The actions that
ToObjects support describe how to create Perl objects from the XML
instances.

The $matcher object is an instance of XML::PatAct::MatchName.
$matcher is created and associated with the pattern/action list that
will be matched against.  The $handler object is an instance of
XML::PatAct::ToObjects.  $handler is created and associated with the
pattern/action list to be matched against as well as the pattern
matching instance $matcher.

$handler is a PerlSAX event handler.  XML::Parser::PerlSAX is used as
the source of XML events.  Other PerlSAX event generators include
XML::Grove::PerlSAX and XML::ESISParser.  $parser is created with the
$handler object as it's Handler.

The `parse()' method of $parser is called to run the handler (the
matching object) to produce the output from XML::PatAct::ToObjects,
which is a Perl object converted from XML, $schema.

The above example is an abbrieviated version.  A complete example of
usage of the MatchName and ToObjects modules, including source XML, is
in the documentation for the XML::PatAct::ToObjects module.  The
script and source XML are also in the examples directory.