# phpman > man > XML::PatAct::ToObjects(3pm)

## NAME
    [XML::PatAct::ToObjects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObjects/markdown) - An action module for creating Perl objects

## SYNOPSIS
     use [XML::PatAct::ToObjects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObjects/markdown);

     my $patterns = [ PATTERN => [ OPTIONS ],
                      PATTERN => "PERL-CODE",
                      ... ];

     my $matcher = [XML::PatAct::ToObjects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObjects/markdown)->new( Patterns => $patterns,
                                                Matcher => $matcher,
                                                CopyId => 1,
                                                CopyAttributes => 1 );

## DESCRIPTION
    [XML::PatAct::ToObjects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObjects/markdown) is a PerlSAX handler for applying pattern-action lists to XML parses or
    trees. [XML::PatAct::ToObjects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObjects/markdown) creates Perl objects of the types and contents of the action items
    you define.

    New [XML::PatAct::ToObject](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObject/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AAsString/markdown)") 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](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ABuilder/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) this will be the element
        object, with [Data::Grove](https://www.chedong.com/phpMan.php/perldoc/Data%3A%3AGrove/markdown) it will be the matching object, and with [XML::DOM](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3ADOM/markdown) it will be an
        [XML::DOM::Element](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3ADOM%3A%3AElement/markdown).

## 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](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AMatchName/markdown). 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](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) module.

        use [XML::Parser::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser%3A%3APerlSAX/markdown);
        use [XML::PatAct::MatchName](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AMatchName/markdown);
        use [XML::PatAct::ToObjects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObjects/markdown);

        my $patterns = [
          'schema'      => [ qw{ -holder                                  } ],
          'table'       => [ qw{ -make [Schema::Table](https://www.chedong.com/phpMan.php/perldoc/Schema%3A%3ATable/markdown)                      } ],
          'name'        => [ qw{ -field Name -as-string                   } ],
          'summary'     => [ qw{ -field Summary -as-string                } ],
          'description' => [ qw{ -field Description -grove                } ],
          'column'      => [ qw{ -make [Schema::Column](https://www.chedong.com/phpMan.php/perldoc/Schema%3A%3AColumn/markdown) -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](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AMatchName/markdown)->new( Patterns => $patterns );
        my $handler = [XML::PatAct::ToObjects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3APatAct%3A%3AToObjects/markdown)->new( Patterns => $patterns,
                                                   Matcher => $matcher);

        my $parser = [XML::Parser::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser%3A%3APerlSAX/markdown)->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@bitsko.slc.ut.us>

## SEE ALSO
### perl

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