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 );
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.
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] } );
-
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.
Ken MacLeod, ken@bitsko.slc.ut.us
perl(1), Data::Grove(3)
``Using PatAct Modules'' and ``Creating PatAct Modules'' in libxml-perl.
|