XML::PatAct::ToObjects






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.









                             ‐2‐


−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.









                             ‐3‐


     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









                             ‐4‐


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.