.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 2024-07-12 "perl v5.38.2" "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 XML 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 `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 (\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 \fIPACKAGE\fR" 4
.IX Item "-make PACKAGE"
Create an object blessed into \fIPACKAGE\fR, and continue processing this
element and it's children.  \fIPACKAGE\fR may be the type `\f(CW\*(C`HASH\*(C'\fR' to
simply create an anonyous hash.
.IP "\fB\-args\fR \fIARGUMENTS\fR" 4
.IX Item "-args ARGUMENTS"
Use \fIARGUMENTS\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 \fIFIELD\fR" 4
.IX Item "-field FIELD"
Store this element, object, or children of this element in the parent
object's field named by \fIFIELD\fR.
.IP "\fB\-push\-field\fR \fIFIELD\fR" 4
.IX Item "-push-field FIELD"
Similar to \fB\-field\fR, except that \fIFIELD\fR is an array and the
contents are pushed onto that array.
.IP "\fB\-value\fR \fIVALUE\fR" 4
.IX Item "-value VALUE"
Use \fIVALUE\fR as a literal value to store in \fIFIELD\fR, otherwise
ignoring this element and it's children.  Only valid with \fB\-field\fR or
\&\fB\-push\-field\fR.  `\f(CW\*(C`%{\fR\f(CIATTRIBUTE\fR\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 \fIFIELD\fR.  Only valid with
\&\fB\-field\fR or \fB\-push\-field\fR.
.IP \fB\-grove\fR 4
.IX Item "-grove"
Copy this element to \fIFIELD\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:
.ie n .IP \fR\fB@ELEM\fR\fB@\fR 4
.el .IP \fR\f(CB@ELEM\fR\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 XML::DOM it will be an
XML::DOM::Element.
.SH EXAMPLE
.IX Header "EXAMPLE"
The example pattern-action list below will convert the following XML
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 XML 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 XML 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.