NAME
    Perl::Compare - Normalized Comparison for Perl Source Trees

  STATUS
    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.

DESCRIPTION
    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.

  Comparison Targets
    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').

METHODS
  new from => $target [, filter => $Rule ]
    The "new" constructor creates a new comparison object. It takes a number
    of different arguments to control it.

    from
        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.

    layer
        The optional "layer" argument specifies the document normalisation
        layer to be used in the comparison. (1 by default)

        If you use a stored Perl::Signature::Set file in the comparison, it
        must match the layer used when creating the Perl::Compare object.

    filter
        The optional "filter" argument allows you to pass a File::Find::Rule
        object that will limit the comparison to a particular set of files.

        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.

  layer
    The "layer" accessor returns the normalization layer to be used for the
    comparison.

  filter
    The "filter" accessor returns the File::Find::Rule filter to be used for
    finding the files for the comparison.

  compare $target
    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.

    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.

  compare_report $target
    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.

      + file/added/in_target.t
      ! file/functionally/different.pm
      - removed/in/target.pl

    Returns the report as a single string, or "undef" on error

SUPPORT
    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.

AUTHOR
    Adam Kennedy <adamk@cpan.org>

SEE ALSO
    PPI, PPI::Normal, Perl::Signature

COPYRIGHT
    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.

