xml::patact::toobjects(3)

NAME

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

SYNOPSIS

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::Pat
Act::ToObjects creates Perl objects of the types and con
tents of the action items you define.

New XML::PatAct::ToObject instances are creating by call
ing `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 pat
tern 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 sim
ple 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 (com
pare 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 ele
ment 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, other wise 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 ele
ment.

-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 pat
tern 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, ken@bitsko.slc.ut.us

SEE ALSO

perl(1), Data::Grove(3)

``Using PatAct Modules'' and ``Creating PatAct Modules''
in libxml-perl.

perl v5.8.0 2000-02-22 XML::PatAct::ToObjects(3)