1XML::SemanticDiff(3)  User Contributed Perl Documentation XML::SemanticDiff(3)
2
3
4

NAME

6       XML::SemanticDiff - Perl extension for comparing XML documents.
7

VERSION

9       version 1.0007
10

SYNOPSIS

12         use XML::SemanticDiff;
13         my $diff = XML::SemanticDiff->new();
14
15         foreach my $change ($diff->compare($file, $file2)) {
16             print "$change->{message} in context $change->{context}\n";
17         }
18
19         # or, if you want line numbers:
20
21         my $diff = XML::SemanticDiff->new(keeplinenums => 1);
22
23         foreach my $change ($diff->compare($file, $file2)) {
24             print "$change->{message} (between lines $change->{startline} and $change->{endline})\n";
25         }
26

DESCRIPTION

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

VERSION

33       version 1.0007
34

METHODS

36   $obj->new([%options])
37       Ye olde object constructor.
38
39       The new() method recognizes the following options:
40
41       •   keeplinenums
42
43           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
49       •   keepdata
50
51           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
56           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
62           Note that using this option will greatly increase the amount of
63           memory used by your application.
64
65       •   diffhandler
66
67           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
71           Please see the section on 'CUSTOM HANDLERS' below.
72
73       •   ignorexpath
74
75           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
80           Current implementation ignores namespaces during comparison.
81
82   @results = $differ->compare($xml1, $xml2)
83       Compares the XMLs $xml1 and $xml2 . $xml1 and $xml2 can be:
84
85       •   filenames
86
87           This will be considered if it is a string that does not contain
88           newlines and exists in the filesystem.
89
90       •   the XML text itself.
91
92           This will be considered if it's any kind of string.
93
94       •   the results of read_xml(). (see below)
95
96           This will be considered if it's a hash reference.
97
98   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

CUSTOM HANDLERS

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

HANDLER METHODS

115       The following is a list of handler methods that can be used for your
116       custom diff-handler class.
117
118   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
125   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
129   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
133   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
142   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
150   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
154   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
160   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
165   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
170       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

AUTHOR

175       Originally by Kip Hampton, khampton@totalcinema.com .
176
177       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
184       Shlomi Fish hereby disclaims any implicit or explicit copyrights on
185       this software.
186

LICENSE

188       This program is free software; you can redistribute it and/or modify it
189       under the same terms as Perl itself.
190

SEE ALSO

192       perl(1).
193

AUTHORS

195       •   Shlomi Fish <shlomif@cpan.org>
196
197       •   Chris Prather <chris.prather@tamarou.com>
198
200       This software is copyright (c) 2001 by Kip Hampton.
201
202       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

BUGS

206       Please report any bugs or feature requests on the bugtracker website
207       <https://github.com/shlomif/perl-XML-SemanticDiff/issues>
208
209       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

SUPPORT

213   Perldoc
214       You can find documentation for this module with the perldoc command.
215
216         perldoc XML::SemanticDiff
217
218   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
223       •   MetaCPAN
224
225           A modern, open-source CPAN search engine, useful to view POD in
226           HTML format.
227
228           <https://metacpan.org/release/XML-SemanticDiff>
229
230       •   Search CPAN
231
232           The default CPAN search engine, useful to view POD in HTML format.
233
234           <http://search.cpan.org/dist/XML-SemanticDiff>
235
236       •   RT: CPAN's Bug Tracker
237
238           The RT ( Request Tracker ) website is the default bug/issue
239           tracking system for CPAN.
240
241           <https://rt.cpan.org/Public/Dist/Display.html?Name=XML-SemanticDiff>
242
243       •   AnnoCPAN
244
245           The AnnoCPAN is a website that allows community annotations of Perl
246           module documentation.
247
248           <http://annocpan.org/dist/XML-SemanticDiff>
249
250       •   CPAN Ratings
251
252           The CPAN Ratings is a website that allows community ratings and
253           reviews of Perl modules.
254
255           <http://cpanratings.perl.org/d/XML-SemanticDiff>
256
257       •   CPANTS
258
259           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
260           of a distribution.
261
262           <http://cpants.cpanauthors.org/dist/XML-SemanticDiff>
263
264       •   CPAN Testers
265
266           The CPAN Testers is a network of smoke testers who run automated
267           tests on uploaded CPAN distributions.
268
269           <http://www.cpantesters.org/distro/X/XML-SemanticDiff>
270
271       •   CPAN Testers Matrix
272
273           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
277           <http://matrix.cpantesters.org/?dist=XML-SemanticDiff>
278
279       •   CPAN Testers Dependencies
280
281           The CPAN Testers Dependencies is a website that shows a chart of
282           the test results of all dependencies for a distribution.
283
284           <http://deps.cpantesters.org/?module=XML::SemanticDiff>
285
286   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
293   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
299       <https://github.com/shlomif/perl-XML-SemanticDiff>
300
301         git clone git://github.com/shlomif/perl-XML-SemanticDiff.git
302
303
304
305perl v5.36.0                      2022-07-22              XML::SemanticDiff(3)
Impressum