NAME

Perl::Compare - Compare two perl documents for equivalence

SYNOPSIS

use Perl::Compare;

# Compare my file to yours, to see if they are functionally equivalent
Perl::Compare->compare( 'my/file.pl', 'your/file.pl' );

DESCRIPTION

Perl::Compare module takes perl documents, as a file name, raw source or an existing PPI::Document object, and compares the two to see if they are functionally identical.

The two documents (however they are provided) are loaded into fully lexed PPI::Document structures. These are then destructively modified to factor out anything that may have different content but be functionally equivalent.

At the most basic level, the non-significant Elements are stripped out, and some others converted into some lowest common form. Beyond that, a number of additional transforms are done, using a pseudo-plugin system.

At the end of the normalization process, the two normalised documents are compared with a normal deep structu comparison.

METHODS

compare $left, $right, option => value, ...

The compare method is the primary method for doing a comparison between two Perl documents. It's provided with two arguments, and an optional set of options.

Each comparitor can be either a PPI::Document object, a Perl::Compare::_NormalizedDocument object, a file name, or a reference to a scalar containing raw perl source code. Each comparitor will be loaded, parsed and normalized as needed to get two Perl::Compare::_NormalizedDocument objects, which are then compared using Data::Compare.

The list of options will be documented once this module is actually useful.

Returns true is the two perl items are equivalent, false if not, or undef on error.

normalize $PPI::Document, option => value, ...

The normalize method does the actual normalization of a single PPI::Document object. The method takes as argument a single PPI::Document object, and a set of options compatible with the compare method above, and returns a Perl::Compare::_NormalizeDocument object, which is the munged and destroyed result of the normalization process.

Although primarily used internally, its main public use it to pre-normalize a Document object, when it will be compared a large number of times.

Perl::Compare::_NormalizedDocument

Perl::Compare::_NormalizedDocument is the internal class used to flag a PPI::Document object as being fully normalized.

It has no special properties, or methods (But its completely destroyed in the normalization process of course, so don't try to do anything with it).

TO DO

Create a proper extention mechanism, document it, maybe autodetect plugins, and possibly break it up into multiple phases, so that the simple transforms can be isolated from the more complex ones.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl%3A%3ACompare

For other issues, contact the author.

AUTHOR

Adam Kennedy (Maintainer), http://ali.as/, cpan@ali.as

COPYRIGHT

Thank you to Phase N (http://phase-n.com/) for permitting the Open Sourcing and release of this distribution.

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

The full text of the license can be found in the LICENSE file included with this module.