XML::PatAct::ToObjects(3pm)				User Contributed Perl Documentation			       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

       o   It'd be nice if patterns could be applied even in -as-string and -grove.

       o   Implement Perl code actions.

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

perl v5.10.1							    2010-01-28					       XML::PatAct::ToObjects(3pm)