visitcpan - explore each distribution in a minicpan repository


This documentation refers to 0.006.


     $ visitcpan [OPTIONS] [PROGRAM]
     $ visitcpan [OPTIONS] -- [PROGRAM] [ARGS]


This program executes other programs against each distribution in a minicpan repository. Given a program to run, for each distribution archive in the repository, it will:

If no program to run is provided, visitcpan will instead produce a listing of distribution files, one per line, that can be piped to other programs for analysis.

To avoid conflicts between visitcpan options and arguments provided to the program to run, use two dashes ('--') to separate minicpan options from other arguments.

By default, visitcpan will use a local minicpan repository as defined in a .minicpanrc file.


  --append|-a        --append=dist -> append distname after ARGS
                     --append=path -> append tarball path after ARGS
  -e|-E              run next argument via 'perl -E'
  --help|-h          this usage info 
  --minicpan|-m      directory of a minicpan (defaults to local minicpan 
                     from CPAN::Mini config file)
  --output|-o        file to save output instead of sending to terminal
  --quiet|-q         silence warnings and suppress STDERR from tar
  --version|-V       visitcpan program version
  --                 indicates the end of options for visitcpan


   # count number of distributions in the minicpan
   $ visitcpan | wc -l
   # get a listing of all distributions using Build.PL
   $ visitcpan -q -a dist -o listing.txt -e 'say shift if -f "Build.PL"'
   # run a program against each distribution
   $ visitcpan -q -- ack -a 'use version;'


You will find below a number of requests for improvements to visitcpan. We will begin to work on these at Perl Seminar NY on February 16 2010. You are encouraged to continue working on whatever requests we do not complete at that workshop session.

Visit a single branch rather than the whole tree

As it currently stands, when you call visitcpan you have to traverse every distribution in your minicpan repository tree. That's not quick. But what if you only want to examine a single branch in that tree. Suppose, for instance, that you only want to examine CPAN modules for which DAGOLDEN is the maintainer. In that case, you want to be able to tell visitcpan: "Start your search at authors/id/D/DA/DAGOLDEN/".

Design the command-line interface to this functionality. Implement, test and document it.

Visit a list specified CPAN distributions

Suppose that you already know which CPAN distributions you wish to visit, but that these distributions are not all conveniently found in a single branch of the tree. For instance, suppose that you wish to run a program against every CPAN distribution that contained XS code. Currently, you cannot do that without traversing the whole of your minicpan. But you could if you could provide minicpan with a list of distributions to be visited or (more likely) a path to a file holding such a list.

Design the command-line interface to this functionality. Implement, test and document it.

Avoid spawning one perl process per distribution visited

According to Ricardo Signes (RJBS/rjbs), you provide visitcpan with a Perl program to be run once per distribution. That's over 17000 individual perl processes. Wouldn't it be nicer if you could say something like this:

    App::CPAN::Mini::Visit->visit(sub { ... })

It would chdir properly and call the subroutine, presumably with a hashref of args providing some context like "you're now in this fully-qualified path."

This would make it easy to write complex behavior, and would let you run all your work in one process, keeping a global state. Design, implement, test and document.

Capture results of visit and insert them into SQLite database

Currently, the results of your visit to each distribution in your minicpan are simply printed to STDOUT. What if you wanted to save that information for later analysis. It would be convenient to be able to directly store that information in an SQLite database. Requested by David Golden (DAGOLDEN/xdg). Design, implement, test and document.

Enable parallelization during visiting

If the box on which your minicpan sits is capable of parallel processing, you would probably want to have visitcpan work in parallel, particularly if you actually needed to visit all 17,000+ distributions. Also requested by David Golden.


    mkdir sandbox
    chdir sandbox
    git clone: git://