NAME

WorePAN - creates a partial CPAN mirror for tests

SYNOPSIS

    use WorePAN;

    my $worepan = WorePAN->new(
      root => 'path/to/destination/',
      files => [qw(
        I/IS/ISHIGAKI/WorePAN-0.01.tar.gz
      )],
      cleanup     => 1,
      use_backpan => 0,
      no_network  => 0,
      tmp => 'path/to/tmpdir',
    );

    # walk through a MiniCPAN to investigate META data
    WorePAN->new(use_minicpan => 1)->walk(sub {
      my $dir = shift;
      my $meta_yml = $dir->file('META.yml');
      return unless -f $meta_yml;
      my $meta = eval { Parse::CPAN::Meta->load_file($meta_yml) };
      ...
    });

DESCRIPTION

WorePAN helps you to create a partial CPAN mirror with minimal indices. It's useful when you test something that requires a small part of a CPAN mirror. You can use it to build a DarkPAN as well.

The main differences between this and the friends are: this works under the Windows (hence the "W-"), and this fetches files not only from the CPAN but also from the BackPAN (and from a local directory with the same layout as of the CPAN) if necessary.

METHODS

new

creates an instance, and fetches files/updates indices internally.

Options are:

root

If specified, a WorePAN mirror will be created under the specified directory; otherwise, it will be created under a temporary directory (which is accessible via root).

use_minicpan

If set to true, WorePAN reads .minicpanrc file to find your local MiniCPAN and uses it as a WorePAN root.

cpan

a CPAN mirror from where you'd like to fetch files.

files

takes an arrayref of filenames to fetch. As of this writing they should be paths to existing files or path parts that follow http://your.CPAN.mirror/authors/id/.

dists

If network is available (see below), you can pass a hashref of distribution names (N.B. not package/module names) and required versions, which will be normalized into an array of filenames via remote API. If you don't remember who has released a specific version of a distribution, this may help.

  my $worepan = WorePAN->new(
    dists => {
      'Catalyst-Runtime' => 5.9,
      'DBIx-Class'       => 0,
    },
  );

local_mirror

takes a path to your local CPAN mirror from where files are copied.

no_network

If set to true, WorePAN won't try to fetch files from remote sources. This is set to true by default when you're in tests.

use_backpan

If set to true, WorePAN also looks into the BackPAN when it fails to fetch a file from the CPAN.

backpan

a BackPAN mirror from where you'd like to fetch files.

cleanup

If set to true, WorePAN removes its contents when the instance is gone (mainly for tests).

verbose

no_indices

If set to true, WorePAN won't create/update indices.

developer_releases

WorePAN usually ignores developer releases and doesn't fetch/index them. Set this to true if you need them for whatever reasons.

permissions

If you pass a valid PAUSE::Permissions instance, it will be used while indexing.

tmp

If set, temporary directories will be created in the specified directory.

add_files

  $worepan->add_files(qw{
    I/IS/ISHIGAKI/WorePAN-0.01.tar.gz
  });

Adds files to the WorePAN mirror. When you add files with this method, you need to call update_indices by yourself.

add_dists

  $worepan->add_dists(
    'Catalyst-Runtime' => 5.9,
    'DBIx-Class'       => 0,
  );

Adds distributions to the WorePAN mirror. When you add distributions with this method, you need to call update_indices by yourself.

update_indices

Creates/updates mailrc and packages_details indices.

walk

  $worepan->walk(sub {
    my $distdir = shift;
  
    my $meta_yml = $distdir->file('META.yml');
  
    $distdir->recurse(callback => sub {
      my $file_in_a_dist = shift;
      return unless $file_in_a_dist =~ /\.pm$/;
      ...
    });
  });

Walks down the WorePAN directory and extracts each distribution into a temporary directory, and runs a callback to which a Path::Extended::Tiny object for the directory is passed as an argument. Used internally to create indices.

root

returns a Path::Extended::Tiny object that represents the root path you specified (or created internally).

file

takes a relative path to a distribution ("P/PA/PAUSE/distribution.tar.gz") and returns a Path::Extended::Tiny object.

whois, slurp_whois

returns a Path::Extended::Tiny object that represents the "00whois.xml" file. slurp_whois returns a list of author entries parsed by Parse::CPAN::Whois.

mailrc, slurp_mailrc

returns a Path::Extended::Tiny object that represents the "01mailrc.txt.gz" file. slurp_mailrc returns a list of lines without preambles.

packages_details, slurp_packages_details

returns a Path::Extended::Tiny object that represents the "02packages.details.txt.gz" file. slurp_packages_details returns a list of lines without preambles.

look_for

takes a package name and returns the version and the path of the package if it exists.

authors

returns an array reference of hash references each of which holds an author's information stored in the whois file.

modules

returns an array reference of hash references each of which holds a module name and its version stored in the packages_details file.

files

returns an array reference of files listed in the packages_details file.

latest_distributions

returns an array reference of CPAN::DistnameInfo objects each of which holds a latest distribution's info stored in the packages_details file.

HOW TO PRONOUNCE (IF YOU CARE)

(w)oh-ray-PAN, not WORE-pan. "Ore" (pronounced oh-ray) indicates the first person singular in masculine speech in Japan, and the "w" adds a funny tone to it.

SEE ALSO

OrePAN, CPAN::Faker, CPAN::Mini::FromList, CPAN::ParseDistribution

AUTHOR

Kenichi Ishigaki, <ishigaki@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Kenichi Ishigaki.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm WorePAN

perl -MCPAN -e shell
install WorePAN