Provided by: libxml-perl_0.08-3_all bug


       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:

           The pattern-action list to apply.

           An instance of the pattern or query matching module.

           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.

           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:

           Ignore this element, but continue processing it's children (compare to -ignore).
           "-pcdata" may be used with this option.

           Ignore (discard) this element and it's children (compare to -holder).

           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

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

           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.

           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.

           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:

           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:

               <summary>A short summary</summary>
               <description>A long description that may
                 contain a subset of HTML</description>
                 <summary>A short summary</summary>
                 <description>A long description</description>

       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,


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

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