1XML::SemanticDiff(3) User Contributed Perl Documentation XML::SemanticDiff(3)
2
6 XML::SemanticDiff - Perl extension for comparing XML documents.
7
9 version 1.0007
10
12 use XML::SemanticDiff;
13 my $diff = XML::SemanticDiff->new();
14 foreach my $change ($diff->compare($file, $file2)) {
16 print "$change->{message} in context $change->{context}\n";
17 }
18 # or, if you want line numbers:
20 my $diff = XML::SemanticDiff->new(keeplinenums => 1);
22 foreach my $change ($diff->compare($file, $file2)) {
24 print "$change->{message} (between lines $change->{startline} and $change->{endline})\n";
25 }
26
28 XML::SematicDiff provides a way to compare the contents and structure
29 of two XML documents. By default, it returns a list of hashrefs where
30 each hashref describes a single difference between the two docs.
31
33 version 1.0007
34
36 $obj->new([%options])
37 Ye olde object constructor.
38 The new() method recognizes the following options:
40 • keeplinenums
42 When this option is enabled XML::SemanticDiff will add the
44 'startline' and 'endline' properties (containing the line numbers
45 for the reported element's start tag and end tag) to each warning.
46 For attribute events these numbers reflect the start and end tags
47 of the element which contains that attribute.
48 • keepdata
50 When this option is enabled XML::SemanticDiff will add the
52 'old_value' and 'new_value' properties to each warning. These
53 properties contain, surprisingly, the old and new values for the
54 element or attribute being reported.
55 In the case of missing elements or attributes (those in the first
57 document, not in the second) only the 'old_value' property will be
58 defined. Similarly, in the case of rogue elements or attributes
59 (those in the second document but not in the first) only the
60 'new_value' property will be defined.
61 Note that using this option will greatly increase the amount of
63 memory used by your application.
64 • diffhandler
66 Taking a blessed object as it's sole argument, this option provides
68 a way to hook the basic semantic diff engine into your own custom
69 handler class.
70 Please see the section on 'CUSTOM HANDLERS' below.
72 • ignorexpath
74 This option takes array of strings as argument. Strings are
76 interpreted as simple xpath expressions. Nodes matching these
77 expressions are ignored during comparison. All xpath expressions
78 should be absolute (start with '/').
79 Current implementation ignores namespaces during comparison.
81 @results = $differ->compare($xml1, $xml2)
83 Compares the XMLs $xml1 and $xml2 . $xml1 and $xml2 can be:
84 • filenames
86 This will be considered if it is a string that does not contain
88 newlines and exists in the filesystem.
89 • the XML text itself.
91 This will be considered if it's any kind of string.
93 • the results of read_xml(). (see below)
95 This will be considered if it's a hash reference.
97 my $doc = read_xml($xml_location)
99 This will read the XML, process it for comparison and return it. See
100 compare() for how it is determined.
101
103 Internally, XML::SemanticDiff uses an event-based model somewhat
104 reminiscent of SAX where the various 'semantic diff events' are handed
105 off to a separate handler class to cope with the details. For most
106 general cases where the user only cares about reporting the differences
107 between two docs, the default handler, XML::SemanticDiff::BasicHandler,
108 will probably suffice. However, it is often desirable to add side-
109 effects to the diff process (updating datastores, widget callbacks,
110 etc.) and a custom handler allows you to be creative with what to do
111 about differences between two XML documents and how those differences
112 are reported back to the application through the compare() method.
113
115 The following is a list of handler methods that can be used for your
116 custom diff-handler class.
117 init($self, $diff_obj)
119 The "init" method is called immediately before the the two document
120 HASHes are compared. The blessed XML::SemanticDiff object is passed as
121 the sole argument, so any values that you wish to pass from your
122 application to your custom handler can safely be added to the call to
123 XML::SemanticDiff's constructor method.
124 rogue_element($self, $element_name, $todoc_element_properties)
126 The "rogue_element" method handles those cases where a given element
127 exists in the to-file but not in the from-file.
128 missing_element($self, $element_name, $fromdoc_element_properties)
130 The "missing_element" method handles those cases where a given element
131 exists in the from-file but not in the to-file.
132 element_value($self, $element, $to_element_properties,
134 $fromdoc_element_properties)
135 The "element_value" method handles those cases where the text data
136 differs between two elements that have the same name, namespace URI,
137 and are at the same location in the document tree. Note that all
138 whitespace is normalized and the text from mixed-content elements
139 (those containing both text and child elements mixed together) is
140 aggregated down to a single value.
141 namespace_uri($self, $element, $todoc_element_properties,
143 $fromdoc_element_properties)
144 The "namespace_uri" method handles case where the XML namespace URI
145 differs between a given element in the two documents. Note that the
146 namespace URI is checked, not the element prefixes since <foo:element/>
147 <bar:element/> and <element/> are all considered equivalent as long as
148 they are bound to the same namespace URI.
149 rogue_attribute($self, $attr_name, $element, $todoc_element_properties)
151 The "rogue_attribute" method handles those cases where an attribute
152 exists in a given element the to-file but not in the from-file.
153 missing_attribute($self, $attr_name, $element, $todoc_element_properties,
155 $fromdoc_element_properties)
156 The "missing_attribute" method handles those cases where an attribute
157 exists in a given element exists in the from-file but not in the to-
158 file.
159 attribute_value($self, $attr_name, $element, $todoc_element_properties,
161 $fromdoc_element_properties)
162 The "attribute_value" method handles those cases where the value of an
163 attribute varies between the same element in both documents.
164 final($self, $diff_obj)
166 The "final" method is called immediately after the two document HASHes
167 are compared. Like the "init" handler, it is passed a copy of the
168 XML::SemanticDiff object as it's sole argument.
169 Note that if a given method is not implemented in your custom handler
171 class, XML::SemanticDiff will not complain; but it means that all of
172 those events will be silently ignored. Consider yourself warned.
173
175 Originally by Kip Hampton, khampton@totalcinema.com .
176 Further Maintained by Shlomi Fish, <http://www.shlomifish.org/> .
178
180 Copyright (c) 2000 Kip Hampton. All rights reserved. This program is
181 free software; you can redistribute it and/or modify it under the same
182 terms as Perl itself.
183 Shlomi Fish hereby disclaims any implicit or explicit copyrights on
185 this software.
186
188 This program is free software; you can redistribute it and/or modify it
189 under the same terms as Perl itself.
190
192 perl(1).
193
195 • Shlomi Fish <shlomif@cpan.org>
196 • Chris Prather <chris.prather@tamarou.com>
198
200 This software is copyright (c) 2001 by Kip Hampton.
201 This is free software; you can redistribute it and/or modify it under
203 the same terms as the Perl 5 programming language system itself.
204
206 Please report any bugs or feature requests on the bugtracker website
207 <https://github.com/shlomif/perl-XML-SemanticDiff/issues>
208 When submitting a bug or request, please include a test-file or a patch
210 to an existing test-file that illustrates the bug or desired feature.
211
213 Perldoc
214 You can find documentation for this module with the perldoc command.
215 perldoc XML::SemanticDiff
217 Websites
219 The following websites have more information about this module, and may
220 be of help to you. As always, in addition to those websites please use
221 your favorite search engine to discover more resources.
222 • MetaCPAN
224 A modern, open-source CPAN search engine, useful to view POD in
226 HTML format.
227 <https://metacpan.org/release/XML-SemanticDiff>
229 • Search CPAN
231 The default CPAN search engine, useful to view POD in HTML format.
233 <http://search.cpan.org/dist/XML-SemanticDiff>
235 • RT: CPAN's Bug Tracker
237 The RT ( Request Tracker ) website is the default bug/issue
239 tracking system for CPAN.
240 <https://rt.cpan.org/Public/Dist/Display.html?Name=XML-SemanticDiff>
242 • AnnoCPAN
244 The AnnoCPAN is a website that allows community annotations of Perl
246 module documentation.
247 <http://annocpan.org/dist/XML-SemanticDiff>
249 • CPAN Ratings
251 The CPAN Ratings is a website that allows community ratings and
253 reviews of Perl modules.
254 <http://cpanratings.perl.org/d/XML-SemanticDiff>
256 • CPANTS
258 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
260 of a distribution.
261 <http://cpants.cpanauthors.org/dist/XML-SemanticDiff>
263 • CPAN Testers
265 The CPAN Testers is a network of smoke testers who run automated
267 tests on uploaded CPAN distributions.
268 <http://www.cpantesters.org/distro/X/XML-SemanticDiff>
270 • CPAN Testers Matrix
272 The CPAN Testers Matrix is a website that provides a visual
274 overview of the test results for a distribution on various
275 Perls/platforms.
276 <http://matrix.cpantesters.org/?dist=XML-SemanticDiff>
278 • CPAN Testers Dependencies
280 The CPAN Testers Dependencies is a website that shows a chart of
282 the test results of all dependencies for a distribution.
283 <http://deps.cpantesters.org/?module=XML::SemanticDiff>
285 Bugs / Feature Requests
287 Please report any bugs or feature requests by email to
288 "bug-xml-semanticdiff at rt.cpan.org", or through the web interface at
289 <https://rt.cpan.org/Public/Bug/Report.html?Queue=XML-SemanticDiff>.
290 You will be automatically notified of any progress on the request by
291 the system.
292 Source Code
294 The code is open to the world, and available for you to hack on. Please
295 feel free to browse it and play with it, or whatever. If you want to
296 contribute patches, please send me a diff or prod me to pull from your
297 repository :)
298 <https://github.com/shlomif/perl-XML-SemanticDiff>
300 git clone git://github.com/shlomif/perl-XML-SemanticDiff.git
302perl v5.36.0 2023-01-20 XML::SemanticDiff(3)