Perl::Compare - Normalized Comparison for Perl Source Trees
In the original 0.01 implementation of this module, cobbled together as a proof-of-concept during a 9 hour caffiene-fuelled exploratory hacking session, the "Document Normalization" process was included/embedded inside of Perl::Compare.
In the 6 months between then and the first beta of PPI, it was realised that normalization was both a more independant and important process than only as part of a Document comparison system.
As such, normalization has been moved into the PPI core as PPI::Normal, and a basic form of comparison can be done with the following.
sub compare ($$) { $_[0]->normalized == $_[1]->normalized }
This can be done without needing either Perl::Compare OR Perl::Signature (a dependency of this module).
This module is now primarily intended for use in testing entire directory trees of modules. Using this module for comparison of single files is discouraged, as it will unduly increase the number of module dependencies in your code/module.
Perl::Compare is designed to allow you to create customised comparisons between different directory trees of Perl source code which are based on normalized documents, and thus ignore "unimportant" changes to files.
A comparison target is either a directory containing Perl code, a Perl::Signature::Set object, or a file that contains a frozen Perl::Signature::Set (not yet supported, dies with 'CODE INCOMPLETE').
The new constructor creates a new comparison object. It takes a number of different arguments to control it.
new
The mandatory from argument should be the target for the main source tree. The comparison report works on a from->to basis, so an entry will be 'added' if it is not present in the from target but is present in the comparison target.
from
The optional layer argument specifies the document normalisation layer to be used in the comparison. (1 by default)
layer
If you use a stored Perl::Signature::Set file in the comparison, it must match the layer used when creating the Perl::Compare object.
The optional filter argument allows you to pass a File::Find::Rule object that will limit the comparison to a particular set of files.
filter
By default, the comparison object will check .pm, .pl and .t files only.
Returns a Perl::Compare object, or undef on error or invalid arguments.
undef
The layer accessor returns the normalization layer to be used for the comparison.
The filter accessor returns the File::Find::Rule filter to be used for finding the files for the comparison.
The compare method takes as argument a single comparison target and runs a standard comparison of the different from the contructor from argument to the target argument.
compare
The result is a reference to a HASH where the names of the files are the key, and the value is one of either 'added', 'removed', or 'changed'.
Returns a reference to a HASH if there is a different between the two targets, false if there is no difference, or undef on error.
The compare_report takes the same argument and performs the same task as the compare method, but instead of a structured hash, it formats the results into a conveniently-printable summary in the following format.
compare_report
+ file/added/in_target.t ! file/functionally/different.pm - removed/in/target.pl
Returns the report as a single string, or undef on error
Bugs should always be submitted via the CPAN bug tracker, located at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-Compare
For general comments, contact the author.
Adam Kennedy <adamk@cpan.org>
PPI, PPI::Normal, Perl::Signature
Copyright 2004 - 2008 Adam Kennedy.
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.
To install Perl::Compare, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl::Compare
CPAN shell
perl -MCPAN -e shell install Perl::Compare
For more information on module installation, please visit the detailed CPAN module installation guide.