.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::PatAct::ToObjects 3"
.TH XML::PatAct::ToObjects 3 "2003-10-21" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::PatAct::ToObjects \- An action module for creating Perl objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::PatAct::ToObjects is a PerlSAX handler for applying
pattern-action lists to \s-1XML\s0 parses or trees. XML::PatAct::ToObjects
creates Perl objects of the types and contents of the action items you
define.
.PP
New XML::PatAct::ToObject instances are creating by calling `\fBnew()\fR'.
Parameters can be passed as a list of key, value pairs or a hash.
`\fBnew()\fR' requires the Patterns and Matcher parameters, the rest are
optional:
.IP "Patterns" 4
.IX Item "Patterns"
The pattern-action list to apply.
.IP "Matcher" 4
.IX Item "Matcher"
An instance of the pattern or query matching module.
.IP "CopyId" 4
.IX Item "CopyId"
Causes the `\s-1ID\s0' attribute, if any, in a source \s-1XML\s0 element to be
copied to an `\s-1ID\s0' attribute in newly created objects. Note that IDs
may be lost of no pattern matches that element or an object is not
created (\f(CW\*(C`\-make\*(C'\fR) for that element.
.IP "CopyAttributes" 4
.IX Item "CopyAttributes"
Causes all attributes of the element to be copied to the newly created
objects.
.PP
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.
.PP
Options that can be used in an action item containing an option-list:
.IP "\fB\-holder\fR" 4
.IX Item "-holder"
Ignore this element, but continue processing it's children (compare to
\&\fB\-ignore\fR). \f(CW\*(C`\-pcdata\*(C'\fR may be used with this option.
.IP "\fB\-ignore\fR" 4
.IX Item "-ignore"
Ignore (discard) this element and it's children (compare to \fB\-holder\fR).
.IP "\fB\-pcdata\fR" 4
.IX Item "-pcdata"
Character data in this element should be copied to the \f(CW\*(C`Contents\*(C'\fR
field.
.IP "\fB\-make\fR \fI\s-1PACKAGE\s0\fR" 4
.IX Item "-make PACKAGE"
Create an object blessed into \fI\s-1PACKAGE\s0\fR, and continue processing this
element and it's children. \fI\s-1PACKAGE\s0\fR may be the type `\f(CW\*(C`HASH\*(C'\fR' to
simply create an anonyous hash.
.IP "\fB\-args\fR \fI\s-1ARGUMENTS\s0\fR" 4
.IX Item "-args ARGUMENTS"
Use \fI\s-1ARGUMENTS\s0\fR in creating the object specified by \fB\-make\fR. This
is commonly used to copy element attributes into fields in the newly
created object. For example:
.Sp
.Vb 1
\& \-make => \*(AqHASH\*(Aq, \-args => \*(AqURL => %{href}\*(Aq
.Ve
.Sp
would copy the `\f(CW\*(C`href\*(C'\fR' attribute in an element to the `\f(CW\*(C`URL\*(C'\fR' field
of the newly created hash.
.IP "\fB\-field\fR \fI\s-1FIELD\s0\fR" 4
.IX Item "-field FIELD"
Store this element, object, or children of this element in the parent
object's field named by \fI\s-1FIELD\s0\fR.
.IP "\fB\-push\-field\fR \fI\s-1FIELD\s0\fR" 4
.IX Item "-push-field FIELD"
Similar to \fB\-field\fR, except that \fI\s-1FIELD\s0\fR is an array and the
contents are pushed onto that array.
.IP "\fB\-value\fR \fI\s-1VALUE\s0\fR" 4
.IX Item "-value VALUE"
Use \fI\s-1VALUE\s0\fR as a literal value to store in \fI\s-1FIELD\s0\fR, otherwise
ignoring this element and it's children. Only valid with \fB\-field\fR or
\&\fB\-push\-field\fR. `\f(CW\*(C`%{\f(CIATTRIBUTE\f(CW}\*(C'\fR' notation can be used to
substitute the value of an attribute into the literal value.
.IP "\fB\-as\-string\fR" 4
.IX Item "-as-string"
Convert the contents of this element to a string (as in
\&\f(CW\*(C`XML::Grove::AsString\*(C'\fR) and store in \fI\s-1FIELD\s0\fR. Only valid with
\&\fB\-field\fR or \fB\-push\-field\fR.
.IP "\fB\-grove\fR" 4
.IX Item "-grove"
Copy this element to \fI\s-1FIELD\s0\fR without further processing. The element
can then be processed later as the Perl objects are manipulated. Only
valid with \fB\-field\fR or \fB\-push\-field\fR. If ToObjects is used with
PerlSAX, this will use XML::Grove::Builder to build the grove element.
.IP "\fB\-grove\-contents\fR" 4
.IX Item "-grove-contents"
Used with \fB\-make\fR, \fB\-grove\-contents\fR creates an object but then
takes all of the content of that element and stores it in Contents.
.PP
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:
.IP "\fB\f(CB@ELEM\fB@\fR" 4
.IX Item "@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 \s-1XML::DOM\s0 it will be an
XML::DOM::Element.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The example pattern-action list below will convert the following \s-1XML\s0
representing a Database schema:
.PP
.Vb 10
\& <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>
.Ve
.PP
into Perl objects looking like:
.PP
.Vb 10
\& [
\& { 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
\& }
\& ]
\& }
\& ]
.Ve
.PP
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 \s-1XML\s0 file as an
argument (\f(CW$ARGV[0]\fR) to the script. This script creates a grove as
one of it's objects, so it requires the XML::Grove module.
.PP
.Vb 3
\& use XML::Parser::PerlSAX;
\& use XML::PatAct::MatchName;
\& use XML::PatAct::ToObjects;
\&
\& my $patterns = [
\& \*(Aqschema\*(Aq => [ qw{ \-holder } ],
\& \*(Aqtable\*(Aq => [ qw{ \-make Schema::Table } ],
\& \*(Aqname\*(Aq => [ qw{ \-field Name \-as\-string } ],
\& \*(Aqsummary\*(Aq => [ qw{ \-field Summary \-as\-string } ],
\& \*(Aqdescription\*(Aq => [ qw{ \-field Description \-grove } ],
\& \*(Aqcolumn\*(Aq => [ qw{ \-make Schema::Column \-push\-field Columns } ],
\& \*(Aqunique\*(Aq => [ qw{ \-field Unique \-value 1 } ],
\& \*(Aqnon\-null\*(Aq => [ qw{ \-field NonNull \-value 1 } ],
\& \*(Aqdefault\*(Aq => [ 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] } );
.Ve
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
It'd be nice if patterns could be applied even in \fB\-as\-string\fR and
\&\fB\-grove\fR.
.IP "\(bu" 4
Implement Perl code actions.
.IP "\(bu" 4
\&\fB\-as\-xml\fR to write \s-1XML\s0 into the field.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ken MacLeod, ken@bitsko.slc.ut.us
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBData::Grove\fR\|(3)
.PP
``Using PatAct Modules'' and ``Creating PatAct Modules'' in libxml-perl.