XML::PatAct::ToObjects - phpMan

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.