View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
David Golden > CPAN-Visitor-0.003 > CPAN::Visitor



Annotate this POD


View/Report Bugs
Module Version: 0.003   Source   Latest Release: CPAN-Visitor-0.005


CPAN::Visitor - Generic traversal of distributions in a CPAN repository


version 0.003


     use CPAN::Visitor;
     my $visitor = CPAN::Visitor->new( cpan => "/path/to/cpan" );
     # Prepare to visit all distributions
     # Or a subset of distributions
       subtrees => [ qr{D/DA}, qr{A/AD} ], # relative to authors/id/
       exclude => qr{/Acme-},              # No Acme- dists
       match => qr{/Test-}                 # Only Test- dists
     # Action is specified via a callback
       visit => sub {
         my $job = shift;
         print $job->{distfile} if -f 'Build.PL'
     # Or start with a list of files
     $visitor = CPAN::Visitor->new(
       cpan => "/path/to/cpan",
       files => \@distfiles,     # e.g. ANDK/CPAN-1.94.tar.gz
     $visitor->iterate( visit => \&callback );
     # Iterate in parallel
     $visitor->iterate( visit => \&callback, jobs => 5 );


A very generic, callback-driven program to iterate over a CPAN repository.

Needs better documentation and tests, but is provided for others to examine, use or contribute to.



   my $visitor = CPAN::Visitor->new( @args );

Object attributes include:


   $visitor->select( @args );

Valid arguments include:

The select method returns a count of files selected.


  $visitor->iterate( @args );

Valid arguments include:

See "ACTION CALLBACKS" for more. Generally, you only need to provide the visit callback, which is called from inside the unpacked distribution directory.

The iterate method always returns true.


Each selected distribution is processed with a series of callback functions. These are each passed a hash-ref with information about the particular distribution being processed.

   sub _my_visit {
     my $job = shift;
     # do stuff

The job hash-ref is initialized with the following fields:

The result field is used to accumulate the return values from action callbacks. For example, the return value from the default 'extract' action is the unpacked distribution directory:

   $job->{result}{extract} # distribution directory path

You do not need to store the results yourself -- the iterate method takes care of it for you.

Callbacks occur in the following order. Some callbacks skip further processing if the return value is false.

These allow complete customization of the iteration process. For example, one could do something like this:

This could potentially speed up iteration if only the file names within the distribution are of interest and not the contents of the actual files.


Please report any bugs or feature requests using the CPAN Request Tracker web interface at

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.



Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

  git clone


David Golden <>


This software is Copyright (c) 2010 by David Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004
syntax highlighting: