phpMan > man > XML::PatAct::ToObjects(3pm)

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

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

    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 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] } );

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 AT bitsko.us

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

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