BackPAN::Index(3pm)

1BackPAN::Index(3)     User Contributed Perl Documentation    BackPAN::Index(3)
2
3
4

NAME

6       BackPAN::Index - An interface to the BackPAN index
7

SYNOPSIS

9           use BackPAN::Index;
10           my $backpan = BackPAN::Index->new;
11
12           # These are all DBIx::Class::ResultSet's
13           my $files    = $backpan->files;
14           my $dists    = $backpan->dists;
15           my $releases = $backpan->releases("Acme-Pony");
16
17           # Use DBIx::Class::ResultSet methods on them
18           my $release = $releases->single({ version => '1.23' });
19
20           my $dist = $backpan->dist("Test-Simple");
21           my $releases = $dist->releases;
22

DESCRIPTION

24       This downloads, caches and parses the BackPAN index into a local
25       database for efficient querying.
26
27       Its a pretty thin wrapper around DBIx::Class returning
28       DBIx::Class::ResultSet objects which makes it efficient and flexible.
29
30       The Comprehensive Perl Archive Network (CPAN) is a very useful
31       collection of Perl code. However, in order to keep CPAN relatively
32       small, authors of modules can delete older versions of modules to only
33       let CPAN have the latest version of a module. BackPAN is where these
34       deleted modules are backed up. It's more like a full CPAN mirror, only
35       without the deletions. This module provides an index of BackPAN and
36       some handy methods.
37

METHODS

39   new
40           my $backpan = BackPAN::Index->new(\%options);
41
42       Create a new object representing the BackPAN index.
43
44       It will, if necessary, download the BackPAN index and compile it into a
45       database for efficient storage.  Initial creation is slow, but it will
46       be cached.
47
48       new() takes some options
49
50       update
51
52       Because it is rather large, BackPAN::Index caches a copy of the BackPAN
53       index and builds a local database to speed access.  This flag controls
54       if the local index is updated.
55
56       If true, forces an update of the BACKPAN index.
57
58       If false, the index will never be updated even if the cache is expired.
59       It will always create a new index if one does not exist.
60
61       By default the index is cached and checked for updates according to
62       "<$backpan-"cache_ttl>>.
63
64       cache_ttl
65
66       How many seconds before checking for an updated index.
67
68       Defaults to an hour.
69
70       debug
71
72       If true, debug messages will be printed.
73
74       Defaults to false.
75
76       releases_only_from_authors
77
78       If true, only files in the "authors" directory will be considered as
79       releases.  If false any file in the index may be considered for a
80       release.
81
82       Defaults to true.
83
84       cache_dir
85
86       Location of the cache directory.
87
88       Defaults to whatever App::Cache does.
89
90       backpan_index_url
91
92       URL to the BackPAN index.
93
94       Defaults to a sensible location.
95
96   files
97           my $files = $backpan->files;
98
99       Returns a ResultSet representing all the files on BackPAN.
100
101   files_by
102           my $files = $backpan->files_by($cpanid);
103           my @files = $backpan->files_by($cpanid);
104
105       Returns all the files by a given $cpanid.
106
107       Returns either a list of BackPAN::Index::Files or a ResultSet.
108
109   dists
110           my $dists = $backpan->dists;
111
112       Returns a ResultSet representing all the distributions on BackPAN.
113
114   dist
115           my $dists = $backpan->dist($dist_name);
116
117       Returns a single BackPAN::Index::Dist object for $dist_name.
118
119   dists_by
120           my $dists = $backpan->dists_by($cpanid);
121           my @dists = $backpan->dists_by($cpanid);
122
123       Returns the dists which contain at least one release by the given
124       $cpanid.
125
126       Returns either a ResultSet or a list of the Dists.
127
128   dists_changed_since
129           my $dists = $backpan->dists_changed_since($time);
130
131       Returns a ResultSet of distributions which have had releases at or
132       after after $time.
133
134   releases
135           my $all_releases  = $backpan->releases();
136           my $dist_releases = $backpan->releases($dist_name);
137
138       Returns a ResultSet representing all the releases on BackPAN.  If a
139       $dist_name is given it returns the releases of just one distribution.
140
141   release
142           my $release = $backpan->release($dist_name, $version);
143
144       Returns a single BackPAN::Index::Release object for the given
145       $dist_name and $version.
146
147   releases_by
148           my $releases = $backpan->releases_by($cpanid);
149           my @releases = $backpan->releases_by($cpanid);
150
151       Returns all the releases of a single author.
152
153       Returns either a list of Releases or a ResultSet representing those
154       releases.
155
156   releases_since
157           my $releases = $backpan->releases_since($time);
158
159       Returns a ResultSet of releases which were released at or after $time.
160

EXAMPLES

162       The real power of BackPAN::Index comes from DBIx::Class::ResultSet.
163       Its very flexible and very powerful but not always obvious how to get
164       it to do things.  Here's some examples.
165
166           # How many files are on BackPAN?
167           my $count = $backpan->files->count;
168
169           # How big is BackPAN?
170           my $size = $backpan->files->get_column("size")->sum;
171
172           # What are the names of all the distributions?
173           my @names = $backpan->dists->get_column("name")->all;
174
175           # What path contains this release?
176           my $path = $backpan->release("Acme-Pony", 1.01)->path;
177
178           # Get all the releases of Moose ordered by version
179           my @releases = $backpan->dist("Moose")->releases
180                                                 ->search(undef, { order_by => "version" });
181

AUTHOR

183       Michael G Schwern <schwern@pobox.com>
184

COPYRIGHT

186       Copyright 2009, Michael G Schwern
187

LICENSE

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