1XML::PatAct::ToObjects(U3s)er Contributed Perl DocumentatXiMoLn::PatAct::ToObjects(3)
2
3
4

NAME

6       XML::PatAct::ToObjects - An action module for creating Perl objects
7

SYNOPSIS

9        use XML::PatAct::ToObjects;
10
11        my $patterns = [ PATTERN => [ OPTIONS ],
12                         PATTERN => "PERL-CODE",
13                         ... ];
14
15        my $matcher = XML::PatAct::ToObjects->new( Patterns => $patterns,
16                                                   Matcher => $matcher,
17                                                   CopyId => 1,
18                                                   CopyAttributes => 1 );
19

DESCRIPTION

21       XML::PatAct::ToObjects is a PerlSAX handler for applying pattern-action
22       lists to XML parses or trees.  XML::PatAct::ToObjects creates Perl
23       objects of the types and contents of the action items you define.
24
25       New XML::PatAct::ToObject instances are creating by calling `new()'.
26       Parameters can be passed as a list of key, value pairs or a hash.
27       `new()' requires the Patterns and Matcher parameters, the rest are
28       optional:
29
30       Patterns
31           The pattern-action list to apply.
32
33       Matcher
34           An instance of the pattern or query matching module.
35
36       CopyId
37           Causes the `ID' attribute, if any, in a source XML element to be
38           copied to an `ID' attribute in newly created objects.  Note that
39           IDs may be lost of no pattern matches that element or an object is
40           not created ("-make") for that element.
41
42       CopyAttributes
43           Causes all attributes of the element to be copied to the newly
44           created objects.
45
46       Each action can either be a list of options defined below or a string
47       containing a fragment of Perl code.  If the action is a string of Perl
48       code then simple then some simple substitutions are made as described
49       further below.
50
51       Options that can be used in an action item containing an option-list:
52
53       -holder
54           Ignore this element, but continue processing it's children (compare
55           to -ignore).  "-pcdata" may be used with this option.
56
57       -ignore
58           Ignore (discard) this element and it's children (compare to
59           -holder).
60
61       -pcdata
62           Character data in this element should be copied to the "Contents"
63           field.
64
65       -make PACKAGE
66           Create an object blessed into PACKAGE, and continue processing this
67           element and it's children.  PACKAGE may be the type `"HASH"' to
68           simply create an anonyous hash.
69
70       -args ARGUMENTS
71           Use ARGUMENTS in creating the object specified by -make.  This is
72           commonly used to copy element attributes into fields in the newly
73           created object.  For example:
74
75             -make => 'HASH', -args => 'URL => %{href}'
76
77           would copy the `"href"' attribute in an element to the `"URL"'
78           field of the newly created hash.
79
80       -field FIELD
81           Store this element, object, or children of this element in the
82           parent object's field named by FIELD.
83
84       -push-field FIELD
85           Similar to -field, except that FIELD is an array and the contents
86           are pushed onto that array.
87
88       -value VALUE
89           Use VALUE as a literal value to store in FIELD, otherwise ignoring
90           this element and it's children.  Only valid with -field or
91           -push-field.  `"%{ATTRIBUTE}"' notation can be used to substitute
92           the value of an attribute into the literal value.
93
94       -as-string
95           Convert the contents of this element to a string (as in
96           "XML::Grove::AsString") and store in FIELD.  Only valid with -field
97           or -push-field.
98
99       -grove
100           Copy this element to FIELD without further processing.  The element
101           can then be processed later as the Perl objects are manipulated.
102           Only valid with -field or -push-field.  If ToObjects is used with
103           PerlSAX, this will use XML::Grove::Builder to build the grove
104           element.
105
106       -grove-contents
107           Used with -make, -grove-contents creates an object but then takes
108           all of the content of that element and stores it in Contents.
109
110       If an action item is a string, that string is treated as a fragment of
111       Perl code.  The following simple substitutions are performed on the
112       fragment to provide easy access to the information being converted:
113
114       @ELEM@
115           The object that caused this action to be called.  If ToObjects is
116           used with PerlSAX this will be a hash with the element name and
117           attributes, with XML::Grove this will be the element object, with
118           Data::Grove it will be the matching object, and with XML::DOM it
119           will be an XML::DOM::Element.
120

EXAMPLE

122       The example pattern-action list below will convert the following XML
123       representing a Database schema:
124
125           <schema>
126             <table>
127               <name>MyTable</name>
128               <summary>A short summary</summary>
129               <description>A long description that may
130                 contain a subset of HTML</description>
131               <column>
132                 <name>MyColumn1</name>
133                 <summary>A short summary</summary>
134                 <description>A long description</description>
135                 <unique/>
136                 <non-null/>
137                 <default>42</default>
138               </column>
139             </table>
140           </schema>
141
142       into Perl objects looking like:
143
144           [
145             { Name => "MyTable",
146               Summary => "A short summary",
147               Description => $grove_object,
148               Columns => [
149                 { Name => "MyColumn1",
150                   Summary => "A short summary",
151                   Description => $grove_object,
152                   Unique => 1,
153                   NonNull => 1,
154                   Default => 42
155                 }
156               ]
157             }
158           ]
159
160       Here is a Perl script and pattern-action list that will perform the
161       conversion using the simple name matching pattern module
162       XML::PatAct::MatchName.  The script accepts a Schema XML file as an
163       argument ($ARGV[0]) to the script.  This script creates a grove as one
164       of it's objects, so it requires the XML::Grove module.
165
166           use XML::Parser::PerlSAX;
167           use XML::PatAct::MatchName;
168           use XML::PatAct::ToObjects;
169
170           my $patterns = [
171             'schema'      => [ qw{ -holder                                  } ],
172             'table'       => [ qw{ -make Schema::Table                      } ],
173             'name'        => [ qw{ -field Name -as-string                   } ],
174             'summary'     => [ qw{ -field Summary -as-string                } ],
175             'description' => [ qw{ -field Description -grove                } ],
176             'column'      => [ qw{ -make Schema::Column -push-field Columns } ],
177             'unique'      => [ qw{ -field Unique -value 1                   } ],
178             'non-null'    => [ qw{ -field NonNull -value 1                  } ],
179             'default'     => [ qw{ -field Default -as-string                } ],
180           ];
181
182           my $matcher = XML::PatAct::MatchName->new( Patterns => $patterns );
183           my $handler = XML::PatAct::ToObjects->new( Patterns => $patterns,
184                                                      Matcher => $matcher);
185
186           my $parser = XML::Parser::PerlSAX->new( Handler => $handler );
187           my $schema = $parser->parse(Source => { SystemId => $ARGV[0] } );
188

TODO

190       •   It'd be nice if patterns could be applied even in -as-string and
191           -grove.
192
193       •   Implement Perl code actions.
194
195-as-xml to write XML into the field.
196

AUTHOR

198       Ken MacLeod, ken@bitsko.slc.ut.us
199

SEE ALSO

201       perl(1), Data::Grove(3)
202
203       ``Using PatAct Modules'' and ``Creating PatAct Modules'' in libxml-
204       perl.
205
206
207
208perl v5.34.0                      2022-01-21         XML::PatAct::ToObjects(3)
Impressum