1XML::PatAct::ToObjects(U3s)er Contributed Perl DocumentatXiMoLn::PatAct::ToObjects(3)
2
6 XML::PatAct::ToObjects - An action module for creating Perl objects
7
9 use XML::PatAct::ToObjects;
10 my $patterns = [ PATTERN => [ OPTIONS ],
12 PATTERN => "PERL-CODE",
13 ... ];
14 my $matcher = XML::PatAct::ToObjects->new( Patterns => $patterns,
16 Matcher => $matcher,
17 CopyId => 1,
18 CopyAttributes => 1 );
19
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 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 Patterns
31 The pattern-action list to apply.
32 Matcher
34 An instance of the pattern or query matching module.
35 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 CopyAttributes
43 Causes all attributes of the element to be copied to the newly
44 created objects.
45 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 Options that can be used in an action item containing an option-list:
52 -holder
54 Ignore this element, but continue processing it's children (compare
55 to -ignore). "-pcdata" may be used with this option.
56 -ignore
58 Ignore (discard) this element and it's children (compare to
59 -holder).
60 -pcdata
62 Character data in this element should be copied to the "Contents"
63 field.
64 -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 -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 -make => 'HASH', -args => 'URL => %{href}'
76 would copy the `"href"' attribute in an element to the `"URL"'
78 field of the newly created hash.
79 -field FIELD
81 Store this element, object, or children of this element in the
82 parent object's field named by FIELD.
83 -push-field FIELD
85 Similar to -field, except that FIELD is an array and the contents
86 are pushed onto that array.
87 -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 -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 -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 -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 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 @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
122 The example pattern-action list below will convert the following XML
123 representing a Database schema:
124 <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 into Perl objects looking like:
143 [
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 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 use XML::Parser::PerlSAX;
167 use XML::PatAct::MatchName;
168 use XML::PatAct::ToObjects;
169 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 my $matcher = XML::PatAct::MatchName->new( Patterns => $patterns );
183 my $handler = XML::PatAct::ToObjects->new( Patterns => $patterns,
184 Matcher => $matcher);
185 my $parser = XML::Parser::PerlSAX->new( Handler => $handler );
187 my $schema = $parser->parse(Source => { SystemId => $ARGV[0] } );
188
190 · It'd be nice if patterns could be applied even in -as-string and
191 -grove.
192 · Implement Perl code actions.
194 · -as-xml to write XML into the field.
196
198 Ken MacLeod, ken@bitsko.slc.ut.us
199
201 perl(1), Data::Grove(3)
202 ``Using PatAct Modules'' and ``Creating PatAct Modules'' in libxml-
204 perl.
205perl v5.32.0 2020-07-28 XML::PatAct::ToObjects(3)