XML::PatAct::ToObjects (3)

Leading comments

Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/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 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 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

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@bitsko.slc.ut.us

SEE ALSO

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

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