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.).
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
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