=head1 Creating PatAct Modules

This document is targeted towards the module writer creating a new
pattern or action module or readers who want to understand what is
going on inside a pattern or action module.  If you are only
interesting in using PatAct modules, please see ``Using PatAct
Modules.''

There are two types of modules involved in processing a pattern-action
list the pattern module and the action module.  Pattern modules are
created by users and passed to the `new()' method of action modules,
otherwise all pattern module methods are used only by the action
module.  Action modules are PerlSAX handlers (see PerlSAX.pod in
libxml-perl).  Action modules are responsible for initializing the
pattern module, receiving PerlSAX events, calling the `match()' method
in the pattern module for each element, and applying actions for
matching elements.

The interface the user uses to call the drivers is described in
``Using PatAct Modules''.

In general, the pattern-action modules perform their work on an
element-by-element basis, but the action modules are called with
PerlSAX events for all parse events (characters, processing
instructions, etc.).

=head1 Pattern Modules

Pattern modules have this interface, where PATTERN is the pattern or
query implementation:

  use XML::PatAct::PATTERN;

  $matcher = XML::PatAct::PATTERN->new(Patterns => $patterns [, OPTIONS]);
  $matcher->initialize($actor);
  $index = $matcher->match($element, $names, $nodes);
  $matcher->finalize();

A pattern module instance is created with the pattern list that will
be used or processing as well as any additional options a pattern
module may define.  `$patterns' is the original array reference passed
in by the user to the action module, so it is made up of pairs of
PATTERN => ACTION.  The pattern matcher should ignore the ACTION
items.

`initialize()' is called before any calls to `match()'.  `$actor' is
the action module that is calling the pattern module.  `initialize()'
is normally called from the `start_document()' PerlSAX event.

`match()' performs a single matching against the pattern list and
returns the index of the matching pattern or undef if no pattern
matches.  `$element' is the element to match.  `$names' and `$nodes'
are array references containing the names and nodes (hashes) of this
element and all parent elements up to the element where processing
started.

`finalize()' is called at the end of processing and may be used to
release state information.  `finalize()' is normally called from the
`end_document()' PerlSAX event.

Here is a template for creating a pattern module:

@include ../lib/XML/PatAct/PatternTempl.pm

=head1 Action Modules

Action modules are PerlSAX handlers (see PerlSAX.pod in libxml-perl).
Action modules are responsible for initializing the pattern module,
receiving PerlSAX events, calling the `match()' method in the pattern
module for each element, and applying actions for matching elements.
Action modules must also maintain arrays of element names and element
nodes to be passed to the `match()' method.

Here is a template for creating an action module:

@include ../lib/XML/PatAct/ActionTempl.pm