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.