XML::PatAct::ToObjects - An action module for creating Perl objects

NAME SYNOPSIS DESCRIPTION EXAMPLE TODO AUTHOR SEE ALSO

NAME

XML::PatAct::ToObjects − An action module for creating Perl objects

use XML::PatAct::ToObjects;
my $patterns = [ PATTERN => [ OPTIONS ],
PATTERN => "PERL−CODE",
... ];
my $matcher = XML::PatAct::ToObjects−>new( Patterns => $patterns,
Matcher => $matcher,
CopyId => 1,
CopyAttributes => 1 );

DESCRIPTION

XML::PatAct::ToObjects is a PerlSAX handler for applying pattern−action lists to XML parses or trees. XML::PatAct::ToObjects creates Perl objects of the types and contents of the action items you define.

New XML::PatAct::ToObject instances are creating by calling `new()'. Parameters can be passed as a list of key, value pairs or a hash. `new()' requires the Patterns and Matcher parameters, the rest are optional:
Patterns

The pattern−action list to apply.

Matcher

An instance of the pattern or query matching module.

CopyId

Causes the `ID' attribute, if any, in a source XML element to be copied to an `ID' attribute in newly created objects. Note that IDs may be lost of no pattern matches that element or an object is not created ("−make") for that element.

CopyAttributes

Causes all attributes of the element to be copied to the newly created objects.

Each action can either be a list of options defined below or a string containing a fragment of Perl code. If the action is a string of Perl code then simple then some simple substitutions are made as described further below.

Options that can be used in an action item containing an option−list:
−holder

Ignore this element, but continue processing it's children (compare to −ignore). "−pcdata" may be used with this option.

−ignore

Ignore (discard) this element and it's children (compare to −holder).

−pcdata

Character data in this element should be copied to the "Contents" field.

−make PACKAGE

Create an object blessed into PACKAGE, and continue processing this element and it's children. PACKAGE may be the type `"HASH"' to simply create an anonyous hash.

−args ARGUMENTS

Use ARGUMENTS in creating the object specified by −make. This is commonly used to copy element attributes into fields in the newly created object. For example:

−make => 'HASH', −args => 'URL => %{href}'

would copy the `"href"' attribute in an element to the `"URL"' field of the newly created hash.

−field FIELD

Store this element, object, or children of this element in the parent object's field named by FIELD.

−push−field FIELD

Similar to −field, except that FIELD is an array and the contents are pushed onto that array.

−value VALUE

Use VALUE as a literal value to store in FIELD, otherwise ignoring this element and it's children. Only valid with −field or −push−field. `"%{ATTRIBUTE}"' notation can be used to substitute the value of an attribute into the literal value.

−as−string

Convert the contents of this element to a string (as in "XML::Grove::AsString") and store in FIELD. Only valid with −field or −push−field.

−grove

Copy this element to FIELD without further processing. The element can then be processed later as the Perl objects are manipulated. Only valid with −field or −push−field. If ToObjects is used with PerlSAX, this will use XML::Grove::Builder to build the grove element.

−grove−contents

Used with −make, −grove−contents creates an object but then takes all of the content of that element and stores it in Contents.

If an action item is a string, that string is treated as a fragment of Perl code. The following simple substitutions are performed on the fragment to provide easy access to the information being converted:
@ELEM@

The object that caused this action to be called. If ToObjects is used with PerlSAX this will be a hash with the element name and attributes, with XML::Grove this will be the element object, with Data::Grove it will be the matching object, and with XML::DOM it will be an XML::DOM::Element.

EXAMPLE

The example pattern−action list below will convert the following XML representing a Database schema:

<schema>
<table>
<name>MyTable</name>
<summary>A short summary</summary>
<description>A long description that may
contain a subset of HTML</description>
<column>
<name>MyColumn1</name>
<summary>A short summary</summary>
<description>A long description</description>
<unique/>
<non−null/>
<default>42</default>
</column>
</table>
</schema>

into Perl objects looking like:

[
{ Name => "MyTable",
Summary => "A short summary",
Description => $grove_object,
Columns => [
{ Name => "MyColumn1",
Summary => "A short summary",
Description => $grove_object,
Unique => 1,
NonNull => 1,
Default => 42
}
]
}
]

Here is a Perl script and pattern−action list that will perform the conversion using the simple name matching pattern module XML::PatAct::MatchName. The script accepts a Schema XML file as an argument ($ARGV[0]) to the script. This script creates a grove as one of it's objects, so it requires the XML::Grove module.

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 } ],
'summary' => [ qw{ −field Summary −as−string } ],
'description' => [ qw{ −field Description −grove } ],
'column' => [ qw{ −make Schema::Column −push−field Columns } ],
'unique' => [ qw{ −field Unique −value 1 } ],
'non−null' => [ qw{ −field NonNull −value 1 } ],
'default' => [ qw{ −field Default −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] } );

TODO

	•		It'd be nice if patterns could be applied even in −as−string and −grove.
	•		Implement Perl code actions.
	•		−as−xml to write XML into the field.

AUTHOR

Ken MacLeod, [email protected]