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



Annotate this POD


View/Report Bugs
Module Version: 0.005   Source  


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


version 0.005


    use CPAN::Visitor;
    my $visitor = CPAN::Visitor->new( cpan => "/path/to/cpan" );

    # Prepare to visit all distributions

    # Or a subset of distributions
      subtrees => [ 'D/DA', '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.



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: