--- name: "XML::PatAct::ToObjects" section: "3pm" platform: "linux" package: "libxml-perl" version: "0.08-9" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/XML::PatAct::ToObjects" --- # XML::PatAct::ToObjects(3pm) An action module for creating Perl objects ## 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: ``` MyTableA short summaryA long description that may contain a subset of HTML MyColumn1 A short summary A long description 42
``` 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@bitsko.slc.ut.us ## SEE ALSO [**perl**(1)](/perl/1.md), **Data::Grove**(3) \`\`Using PatAct Modules'' and \`\`Creating PatAct Modules'' in libxml-perl.