BackPAN::Index(3pm)

📦
version 0.42 · 2 versions
, in fedora 43

✨ NAME ✨

BackPAN::Index — it's an interface to the BackPAN index, bestie 💅 (it's a Perl module manual, section 3pm, so like… library docs, iykyk)

🦋 SYNOPSIS 🦋

use BackPAN::Index;
my $backpan = BackPAN::Index->new;

# These are all DBIx::Class::ResultSet's
my $files    = $backpan->files;
my $dists    = $backpan->dists;
my $releases = $backpan->releases("Acme-Pony");

# Use DBIx::Class::ResultSet methods on them
my $release = $releases->single({ version => '1.23' });

my $dist = $backpan->dist("Test-Simple");
my $releases = $dist->releases;

🌸 DESCRIPTION 🌸

Okay so here's the tea: this thing downloads the BackPAN index, caches it, and parses it into a local database so you can query it efficiently. Obsessed. 🫶

It's basically a pretty thin wrapper around DBIx::Class that hands you back DBIx::Class::ResultSet objects, which is what makes it so flexible and so fast. Lowkey elegant fr fr.

So, context: The Comprehensive Perl Archive Network (CPAN) is this very useful collection of Perl code. But — and this is the messy part 😭 — to keep CPAN relatively small, module authors are allowed to delete older versions of modules so that CPAN only keeps the latest version. And BackPAN is where all those deleted modules get backed up. It's giving "full CPAN mirror but make it archival" — it's more like a full CPAN mirror, only without the deletions. ✨ This module gives you an index of BackPAN plus some handy methods. Periodt.

👑 METHODS 👑

🌟 new 🌟

my $backpan = BackPAN::Index->new(\%options);

Creates a brand new object representing the BackPAN index. Main character energy. 💖

It will, if necessary, download the BackPAN index and compile it into a database for efficient storage. Heads up though: initial creation is slow, but the good news is it gets cached afterwards. 🧚

new() takes some options:

update

Because BackPAN is rather large (no cap, it's huge 💀), BackPAN::Index caches a copy of the BackPAN index and builds a local database to speed access. This flag controls whether the local index gets updated.

  • If true, it forces an update of the BACKPAN index.
  • If false, the index will never be updated, even if the cache is expired. It will always create a new index if one does not exist.

By default the index is cached and checked for updates according to <$backpan-"cache_ttl>>.

cache_ttl

How many seconds before checking for an updated index. ⏳

Defaults to an hour.

debug

If true, debug messages will be printed. 🐛

Defaults to false.

releases_only_from_authors

If true, only files in the authors directory will be considered as releases. If false, any file in the index may be considered for a release.

Defaults to true.

cache_dir

Location of the cache directory. 📁

Defaults to whatever App::Cache does.

backpan_index_url

URL to the BackPAN index. 🔗

Defaults to a sensible location.

files

my $files = $backpan->files;

Returns a ResultSet representing all the files on BackPAN. Every single one. ✨

files_by

my $files = $backpan->files_by($cpanid);
my @files = $backpan->files_by($cpanid);

Returns all the files by a given $cpanid.

Returns either a list of BackPAN::Index::Files or a ResultSet.

dists

my $dists = $backpan->dists;

Returns a ResultSet representing all the distributions on BackPAN.

dist

my $dists = $backpan->dist($dist_name);

Returns a single BackPAN::Index::Dist object for $dist_name.

dists_by

my $dists = $backpan->dists_by($cpanid);
my @dists = $backpan->dists_by($cpanid);

Returns the dists which contain at least one release by the given $cpanid.

Returns either a ResultSet or a list of the Dists.

dists_changed_since

my $dists = $backpan->dists_changed_since($time);

Returns a ResultSet of distributions which have had releases at or after after $time. (Yes, the doc really says "at or after after". It's iconic, leave it alone 💅)

releases

my $all_releases  = $backpan->releases();
my $dist_releases = $backpan->releases($dist_name);

Returns a ResultSet representing all the releases on BackPAN. If a $dist_name is given, it returns the releases of just one distribution.

release

my $release = $backpan->release($dist_name, $version);

Returns a single BackPAN::Index::Release object for the given $dist_name and $version.

releases_by

my $releases = $backpan->releases_by($cpanid);
my @releases = $backpan->releases_by($cpanid);

Returns all the releases of a single author. 👑

Returns either a list of Releases or a ResultSet representing those releases.

releases_since

my $releases = $backpan->releases_since($time);

Returns a ResultSet of releases which were released at or after $time.

🔥 EXAMPLES 🔥

The real power of BackPAN::Index comes from DBIx::Class::ResultSet. It's very flexible and very powerful, but it's not always obvious how to get it to do things. So here's some examples, bestie. You're welcome. 🫶

# How many files are on BackPAN?
my $count = $backpan->files->count;

# How big is BackPAN?
my $size = $backpan->files->get_column("size")->sum;

# What are the names of all the distributions?
my @names = $backpan->dists->get_column("name")->all;

# What path contains this release?
my $path = $backpan->release("Acme-Pony", 1.01)->path;

# Get all the releases of Moose ordered by version
my @releases = $backpan->dist("Moose")->releases
                                      ->search(undef, { order_by => "version" });

💜 AUTHOR 💜

Michael G Schwern <schwern@pobox.com>

Copyright 2009, Michael G Schwern

🍓 LICENSE 🍓

This module is free software; you can redistribute it or modify it under the same terms as Perl itself. Slay. ✨

🌈 SEE ALSO 🌈

  • DBIx::Class::ResultSet
  • BackPAN::Index::File
  • BackPAN::Index::Release
  • BackPAN::Index::Dist

Repository: <http://github.com/acme/parse-backpan-packages> Bugs: <http://rt.cpan.org/Public/Dist/Display.html?Name=Parse-BACKPAN-Packages>

And that's the whole vibe check, bestie 🦋 — this page came to you courtesy of perl v5.42.0, dated 2025-07-25, from the BackPAN::Index(3pm) manual. Go query something. 💖

📦 where this page comes from