NAME
    CPAN::Processor - Use PPI to process every perl file/module in CPAN

DESCRIPTION
    CPAN::Processor implements a system for processing every perl file in
    CPAN.

    Under the covers, it subclasses CPAN::Mini to fetch and update all
    significant files in CPAN and PPI::Processor to do the actual
    processing.

  How does it work
    CPAN::Processor starts with a CPAN::Mini local mirror, which it will
    generally update before each run. Once the CPAN::Mini directory is
    current, it will extract all of the perl files to a processor working
    directory.

    A PPI::Processor is then started and run against all of the perl files
    contained in the working directory.

EXTENDING
    This module is relatively stable and complete, but currently uses a
    private modified version of CPAN::Mini. Several additional features of
    this are yet to be merged back into CPAN::Mini, and so the code and API
    are subject to change without notice.

    If you wish to write an extension, please stay in contact with the
    maintainer while doing so.

METHODS
  new
    The "new" constructor is used to create and configure a new CPAN
    Processor. It takes a set of named params something like the following.

      # Create a CPAN processor
      my $Object = CPAN::Processor->new(
            # The normal CPAN::Mini params
            local     => '...',
            remote    => '...',
 
            # Additional params
            processor => $Processor, # A new PPI::Processor object
            );

    minicpan args
        CPAN::Processor inherits from CPAN::Mini, so all of the arguments
        that can be used with CPAN::Mini will also work with
        CPAN::Processor.

        Please note that CPAN::Processor applies some additional defaults,
        turning skip_perl on.

    processor
        A PPI Processor engine is used to do the actual processing of the
        perl files once they have been updated and unpacked.

        The processor param should consist of a created and fully configured
        PPI::Proccessor object. The CPAN::Processor will call it's ->run
        method at the appropriate time.

    force_processor
        Under normal curcumstances, if there are no changes to the minicpan
        mirror, the processor will need to be run. Enabling the
        "force_processor" flag (false by default) will cause the processor
        to be executed, even if there are no changes to the minicpan mirror.

    file_filters
        CPAN::Processor adds an additional type of filter to the standard
        ones.

        Although by default CPAN::Processor only extract files of type .pm,
        .t and .pl from the archives, you can add a list of additional
        things you do not want to be extracted.

          file_filters => [
            qr/\binc\b/i, # Don't extract included modules
            qr/\bAcme\b/, # Don't extract anything related to Acme
          ]

    check_expand
        Once the mirror update has been completed, the check_expand keyword
        forces the processor to go back over every tarball in the mirror and
        double check that it has a corrosponding expanded directory.

    archive_tar_report
        CPAN::Processor does a lot of work with Archive::Tar, and tends to
        encounter a lot of warnings from the various tarballs in CPAN.

        If set to a writable filename, a detailed report on the various
        warnings encountered during processing will be written to the file
        you specify.

    Returns a new CPAN::Processor object, or "undef" on error.

  processor
    The "processor" accessor return the PPI::Processor object the
    CPAN::Processor was created with.

  run
    The "run" methods starts the main process, updating the minicpan mirror
    and extracted version, and then launching the PPI Processor to process
    the files in the source directory.

  errstr
    When an error occurs, the "errstr" method can be used to get access to
    the error message.

    Returns a string containing the error message, or the null string '' if
    there was no error in the last call.

SUPPORT
    Bugs should always be submitted via the CPAN bug tracker

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPAN%3A%3AProcessor>

    For other issues, contact the maintainer

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

    Funding provided by The Perl Foundation

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.

SEE ALSO
    PPI::Processor, PPI, CPAN::Mini, File::Find::Rule

