Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::SemanticDiff(3)  User Contributed Perl Documentation XML::SemanticDiff(3)

NAME
       XML::SemanticDiff - Perl	extension for comparing	XML documents.

VERSION
       version 1.0005

SYNOPSIS
	 use XML::SemanticDiff;
	 my $diff = XML::SemanticDiff->new();

	 foreach my $change ($diff->compare($file, $file2)) {
	     print "$change->{message} in context $change->{context}\n";
	 }

	 # or, if you want line	numbers:

	 my $diff = XML::SemanticDiff->new(keeplinenums	=> 1);

	 foreach my $change ($diff->compare($file, $file2)) {
	     print "$change->{message} (between	lines $change->{startline} and $change->{endline})\n";
	 }

DESCRIPTION
       XML::SematicDiff	provides a way to compare the contents and structure
       of two XML documents. By	default, it returns a list of hashrefs where
       each hashref describes a	single difference between the two docs.

VERSION
       version 1.0005

METHODS
   $obj->new([%options])
       Ye olde object constructor.

       The new() method	recognizes the following options:

       o   keeplinenums

	   When	this option is enabled XML::SemanticDiff will add the
	   'startline' and 'endline' properties	(containing the	line numbers
	   for the reported element's start tag	and end	tag) to	each warning.
	   For attribute events	these numbers reflect the start	and end	tags
	   of the element which	contains that attribute.

       o   keepdata

	   When	this option is enabled XML::SemanticDiff will add the
	   'old_value' and 'new_value' properties to each warning. These
	   properties contain, surprisingly, the old and new values for	the
	   element or attribute	being reported.

	   In the case of missing elements or attributes (those	in the first
	   document, not in the	second)	only the 'old_value' property will be
	   defined. Similarly, in the case of rogue elements or	attributes
	   (those in the second	document but not in the	first) only the
	   'new_value' property	will be	defined.

	   Note	that using this	option will greatly increase the amount	of
	   memory used by your application.

       o   diffhandler

	   Taking a blessed object as it's sole	argument, this option provides
	   a way to hook the basic semantic diff engine	into your own custom
	   handler class.

	   Please see the section on 'CUSTOM HANDLERS' below.

       o   ignorexpath

	   This	option takes array of strings as argument. Strings are
	   interpreted as simple xpath expressions. Nodes matching these
	   expressions are ignored during comparison. All xpath	expressions
	   should be absolute (start with '/').

	   Current implementation ignores namespaces during comparison.

   @results = $differ->compare($xml1, $xml2)
       Compares	the XMLs $xml1 and $xml2 . $xml1 and $xml2 can be:

       o   filenames

	   This	will be	considered if it is a string that does not contain
	   newlines and	exists in the filesystem.

       o   the XML text	itself.

	   This	will be	considered if it's any kind of string.

       o   the results of read_xml(). (see below)

	   This	will be	considered if it's a hash reference.

   my $doc = read_xml($xml_location)
       This will read the XML, process it for comparison and return it.	See
       compare() for how it is determined.

CUSTOM HANDLERS
       Internally, XML::SemanticDiff uses an event-based model somewhat
       reminiscent of SAX where	the various 'semantic diff events' are handed
       off to a	separate handler class to cope with the	details. For most
       general cases where the user only cares about reporting the differences
       between two docs, the default handler, XML::SemanticDiff::BasicHandler,
       will probably suffice. However, it is often desirable to	add side-
       effects to the diff process (updating datastores, widget	callbacks,
       etc.) and a custom handler allows you to	be creative with what to do
       about differences between two XML documents and how those differences
       are reported back to the	application through the	compare() method.

HANDLER	METHODS
       The following is	a list of handler methods that can be used for your
       custom diff-handler class.

   init($self, $diff_obj)
       The "init" method is called immediately before the the two document
       HASHes are compared. The	blessed	XML::SemanticDiff object is passed as
       the sole	argument, so any values	that you wish to pass from your
       application to your custom handler can safely be	added to the call to
       XML::SemanticDiff's constructor method.

   rogue_element($self,	$element_name, $todoc_element_properties)
       The "rogue_element" method handles those	cases where a given element
       exists in the to-file but not in	the from-file.

   missing_element($self, $element_name, $fromdoc_element_properties)
       The "missing_element" method handles those cases	where a	given element
       exists in the from-file but not in the to-file.

   element_value($self,	$element, $to_element_properties,
       $fromdoc_element_properties)
       The "element_value" method handles those	cases where the	text data
       differs between two elements that have the same name, namespace URI,
       and are at the same location in the document tree. Note that all
       whitespace is normalized	and the	text from mixed-content	elements
       (those containing both text and child elements mixed together) is
       aggregated down to a single value.

   namespace_uri($self,	$element, $todoc_element_properties,
       $fromdoc_element_properties)
       The "namespace_uri" method handles case where the XML namespace URI
       differs between a given element in the two documents. Note that the
       namespace URI is	checked, not the element prefixes since	<foo:element/>
       <bar:element/> and <element/> are all considered	equivalent as long as
       they are	bound to the same namespace URI.

   rogue_attribute($self, $attr_name, $element,	$todoc_element_properties)
       The "rogue_attribute" method handles those cases	where an attribute
       exists in a given element the to-file but not in	the from-file.

   missing_attribute($self, $attr_name,	$element, $todoc_element_properties,
       $fromdoc_element_properties)
       The "missing_attribute" method handles those cases where	an attribute
       exists in a given element exists	in the from-file but not in the	to-
       file.

   attribute_value($self, $attr_name, $element,	$todoc_element_properties,
       $fromdoc_element_properties)
       The "attribute_value" method handles those cases	where the value	of an
       attribute varies	between	the same element in both documents.

   final($self,	$diff_obj)
       The "final" method is called immediately	after the two document HASHes
       are compared. Like the "init" handler, it is passed a copy of the
       XML::SemanticDiff object	as it's	sole argument.

       Note that if a given method is not implemented in your custom handler
       class, XML::SemanticDiff	will not complain; but it means	that all of
       those events will be silently ignored. Consider yourself	warned.

AUTHOR
       Originally by Kip Hampton, khampton@totalcinema.com .

       Further Maintained by Shlomi Fish, <http://www.shlomifish.org/> .

COPYRIGHT
       Copyright (c) 2000 Kip Hampton. All rights reserved. This program is
       free software; you can redistribute it and/or modify it under the same
       terms as	Perl itself.

       Shlomi Fish hereby disclaims any	implicit or explicit copyrights	on
       this software.

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

SEE ALSO
       perl(1).

AUTHOR
       Shlomi Fish <shlomif@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2001 by Kim Hampton.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

BUGS
       Please report any bugs or feature requests on the bugtracker website
       http://rt.cpan.org/Public/Dist/Display.html?Name=XML-SemanticDiff or by
       email to	bug-xml-semanticdiff@rt.cpan.org.

       When submitting a bug or	request, please	include	a test-file or a patch
       to an existing test-file	that illustrates the bug or desired feature.

SUPPORT
   Perldoc
       You can find documentation for this module with the perldoc command.

	 perldoc XML::SemanticDiff

   Websites
       The following websites have more	information about this module, and may
       be of help to you. As always, in	addition to those websites please use
       your favorite search engine to discover more resources.

       o   MetaCPAN

	   A modern, open-source CPAN search engine, useful to view POD	in
	   HTML	format.

	   <http://metacpan.org/release/XML-SemanticDiff>

       o   Search CPAN

	   The default CPAN search engine, useful to view POD in HTML format.

	   <http://search.cpan.org/dist/XML-SemanticDiff>

       o   RT: CPAN's Bug Tracker

	   The RT ( Request Tracker ) website is the default bug/issue
	   tracking system for CPAN.

	   <https://rt.cpan.org/Public/Dist/Display.html?Name=XML-SemanticDiff>

       o   AnnoCPAN

	   The AnnoCPAN	is a website that allows community annotations of Perl
	   module documentation.

	   <http://annocpan.org/dist/XML-SemanticDiff>

       o   CPAN	Ratings

	   The CPAN Ratings is a website that allows community ratings and
	   reviews of Perl modules.

	   <http://cpanratings.perl.org/d/XML-SemanticDiff>

       o   CPAN	Forum

	   The CPAN Forum is a web forum for discussing	Perl modules.

	   <http://cpanforum.com/dist/XML-SemanticDiff>

       o   CPANTS

	   The CPANTS is a website that	analyzes the Kwalitee (	code metrics )
	   of a	distribution.

	   <http://cpants.cpanauthors.org/dist/XML-SemanticDiff>

       o   CPAN	Testers

	   The CPAN Testers is a network of smokers who	run automated tests on
	   uploaded CPAN distributions.

	   <http://www.cpantesters.org/distro/X/XML-SemanticDiff>

       o   CPAN	Testers	Matrix

	   The CPAN Testers Matrix is a	website	that provides a	visual
	   overview of the test	results	for a distribution on various
	   Perls/platforms.

	   <http://matrix.cpantesters.org/?dist=XML-SemanticDiff>

       o   CPAN	Testers	Dependencies

	   The CPAN Testers Dependencies is a website that shows a chart of
	   the test results of all dependencies	for a distribution.

	   <http://deps.cpantesters.org/?module=XML::SemanticDiff>

   Bugs	/ Feature Requests
       Please report any bugs or feature requests by email to
       "bug-xml-semanticdiff at	rt.cpan.org", or through the web interface at
       <https://rt.cpan.org/Public/Bug/Report.html?Queue=XML-SemanticDiff>.
       You will	be automatically notified of any progress on the request by
       the system.

   Source Code
       The code	is open	to the world, and available for	you to hack on.	Please
       feel free to browse it and play with it,	or whatever. If	you want to
       contribute patches, please send me a diff or prod me to pull from your
       repository :)

       <https://github.com/shlomif/perl-XML-SemanticDiff>

	 git clone https://github.com/shlomif/perl-XML-SemanticDiff.git

perl v5.24.1			  2017-07-02		  XML::SemanticDiff(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | VERSION | METHODS | CUSTOM HANDLERS | HANDLER METHODS | AUTHOR | COPYRIGHT | LICENSE | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE | BUGS | SUPPORT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::SemanticDiff&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help