NAME
Perl::Signature - Generate functional signatures for perl code
DESCRIPTION
A large part of the work in creating Perl::Compare was put into it's method for "normalizing" perl code as far as possible.
However, the main problem in working with these normalised files is that we need to do a relatively expensive deep compare of a very large data structure.
Perl::Signature attempts to resolve this problem by taking the normalized perl document, serialising it via a standard serialization mechanism, and then digesting it down to a single 128-bit signature.
This is a fairly expensive process, mainly because it involves a full PPI parse round, the normalization process, serialization, and digesting.
But, having done it for a file once, you can do a direct comparison to the functional signature of any other file, and if they match, then it's a pretty safe bet they are functionally the same.
Avoid Changes in the Calculation
Perl::Signature is relatively sensitive. Because any file goes through 4 stages, any of which could change in structure with an upgrade, you should ensure that all signatures are generated with the same versions of PPI, Perl::Compare and the same set of Perl::Compare plugins installed.
METHODS
Because most of the work is done elsewhere, all the methods are one-shot methods. They will all either return a 32 character hexidecimal MD5 hash, or undef.
file $filename
The file method does the whole deal. Load a file, parse it, normalize, serialize and digest. It actually happens in several parts. file just loads the file and passes it on to source.
Returns a 32 character hexidecimal MD5 signature.
source $content | \$content
The source takes perl source code as either a plain string or a reference to a SCALAR. Parses the content and hands the PPI::Document object off to Document.
Returns a 32 character hexidecimal MD5 signature.
Document
The Document method takes a PPI::Document object and does the final nomalize + serialize + digest steps.
Returns a 32 character hexidecimal MD5 signature.
TO DO
- Write unit tests
- Test test test
SUPPORT
All bugs should be filed via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl%3A%3ASignature
For other issues, contact the author
AUTHORS
Adam Kennedy (Maintainer), http://ali.as/, cpan@ali.as
COPYRIGHT
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.