CPAN::Mini::Visit::Simple - Lightweight traversal of a minicpan repository
use CPAN::Mini::Visit::Simple; $self = CPAN::Mini::Visit::Simple->new(); $self->identify_distros();
This Perl extension is a variant on David Golden's App-CPAN-Mini-Visit. It can be used to:
Calculate a subset of the set of distributions in a minicpan repository.
Refresh such a subset when new versions of the distributions which are its elements have appeared in the minicpan repository.
Perform an action on each element of the subset.
Primary List
A set of distributions calculated by this module's methods.
Derived List
A humanly edited version of a primary list; prepared via deletions from -- but not additions to -- a primary list.
Refreshed List
A prepared list whose elements have been updated to reflect the arrival of updated versions of those distributions in the minicpan repository.
Visit
An operation performed on each element of any of the three types of list above.
new()
Purpose
CPAN::Mini::Visit::Simple constructor. While it cannot verify that you have a complete minicpan repository on disk, it does check that the most essential directories are present.
Arguments
$self = CPAN::Mini::Visit::Simple->new();
or
$self = CPAN::Mini::Visit::Simple->new({ minicpan => /path/to/a/minicpan, });
If called with no arguments, the constructor will use the value of the local key-value pair in your .minicpanrc file.
local
May also be called with a single hash reference whose minicpan element's value is the absolute path to a minicpan repository.
minicpan
Return Value
CPAN::Mini::Visit::Simple object.
get_minicpan()
Get the full path to the local minicpan/ installation as stored within the object.
$minicpan_dir = $self->get_minicpan();
String holding path to directory.
get_id_dir()
A minicpan installation, like CPAN itself, is structured with an authors/id/ directory underneath the top-level directory. This method returns the full path to that directory as stored within the object.
$minicpan_id_dir = $self->get_id_dir();
identify_distros()
By traversing a minicpan repository and examining the names of distributions, prepare a list of distributions needing a visit. We will call this list, which is produced without human editing, a primary list.
May be called in any of the following two mutually exclusive ways:
$self->identify_distros();
This will add all distributions found in the minicpan repository to the primary list.
You may provide a hash reference with one or more of several elements.
start_dir
$rv = $self->identify_distros( { start_dir => "$minicpan_id_dir/D/DR/DROLSKY", } );
If a list element is not provided but a start_dir element is provided, its value must be an absolute path to a directory inside the minicpan repository that is below the authors/id/ directory. The list of distributions to be visited will consist of all distributions below that point in the minicpan.
list
pattern
$rv = $self->identify_distros( { pattern => qr/Moose/, } );
If a list element is provided but a pattern element is provided, its value must be a compiled regular expression. The list of distributions to be visited will consist of all distributions in the minicpan whose paths match that pattern.
Combination of start_dir and pattern
$rv = $self->identify_distros( { start_dir => "$minicpan_id_dir/D/DR/DROLSKY", pattern => qr/Moose/, } );
You may provide both a start_dir element and a pattern element. In this case, the start_dir element takes precedence, i.e., the list of distributions to be visited will consist of all distributions below the start_dir which also match the pattern.
Returns true value -- though this is not particularly meaningful. The list of distributions to be visited will be stored inside the object and can be accessed by other methods.
identify_distros_from_derived_list()
Similar to identify_distros(), but used where, through human editing of a primary list, we have produced a derived_list.
$minicpan_id_dir = $self->get_id_dir(); $rv = $self->identify_distros_from_derived_list( { list => [ "$minicpan_id_dir/D/DR/DROLSKY/Alzabo-0.92.tar.gz", "$minicpan_id_dir/D/DR/DROLSKY/DateTime-0.53.tar.gz", "$minicpan_id_dir/D/DR/DROLSKY/Params-Validate-0.95.tar.gz", ], } );
Hash reference with single element whose key is list and whose value is an array reference holding the full paths to the selected distribution archives.
Returns true value upon success.
Comment
This method was present in earlier versions of this library but was incorrectly documented as an option for identify_distros().
say_list()
Prints a list of distributions to be visited.
$self->say_list();
$self->say_list( { file => /path/to/list } );
Optional single hashref. Hash must have file element whose value is absolute path to a file to which list is written. Otherwise, output is simply sent to STDOUT.
file
Implicitly returns true value.
get_list()
Get the set of distributions resulting from the operation of identify_distros().
@output_list = $self->get_list(); # list context
$output_list = $self->get_list(); # scalar context
No arguments needed. All information, if available, is inside the object.
List context: List of distributions if the underlying set exists in the object; undefined otherwise.
Scalar context: Number of elements if the underlying set exists in the object; undefined otherwise.
Because of the deduplication feature of identify_distros, the order of elements in the list returned cannot be guaranteed.
identify_distros
get_list_ref()
Get a reference to the set of distributions resulting from the operation of identify_distros().
$output_ref = $self->get_list_ref();
Array reference if the underlying set exists in the object; undefined otherwise.
Because of the deduplication feature of identify_distros, the order of elements in the list underneath the reference returned cannot be guaranteed.
refresh_list()
Takes a previously created list of distributions and replaces elements with the most recent versions of those distributions as needed.
Suppose that you have a list of distributions, created originally from your minicpan repository, that you are using to test some new CPAN-wide functionality. Suppose further that you update your minicpan repository with the minicpan utility while still working on your project. You will probably want to make sure that you are testing against HEAD, so to speak.
refresh_list() will replace any elements in your list if updated versions thereof have appeared in your minicpan. It will also delete any elements if their corresponding distributions have been removed entirely from CPAN and hence from your minicpan.
$refreshed_list_ref = $self->refresh_list( { derived_list => \@derived_list, # Next two are optional, but should be used if they were # used to calculate the primary list. start_dir => "$minicpan_id_dir/D/DR/DROLSKY", pattern => qr/Moose/, } );
Returns an reference to an array holding the refreshed list. This arrayref is suitable for use as the value of the list element in the hashref passed to the next call of identify_distros().
visit()
Executes an action on each distribution in the list.
Takes a hash reference. Eligible keys for that hash are:
action
$rv = $self->visit( { action => sub { my $distro = shift @_; if ( -f 'Makefile.PL' ) { say "$distro has Makefile.PL"; } if ( -f 'Build.PL' ) { say "$distro has Build.PL"; } }, } );
Reference to a subroutine which is to be executed once for each distribution in the list. This element is required.
action_args
Reference to an array of arguments to be provided to each iteration of the code reference defined in action. This element is optional.
do_not_visit
Reference to an array of strings which are absolute paths to tarballs which are not to be visited. This should be used, for example, where experience has shown that a tarball has technical defects which prevent it from being extracted without warnings.
%build_generators = (); my @non_visits = ( '/home/username/minicpan/authors/id/J/JK/JKEENAN/Data-Presenter-1.03.tar.gz'), ); $rv = $self->visit( { do_not_visit => [ @non_visits ], action => sub { my $distro = shift @_; if ( -f 'Makefile.PL' ) { $build_generators{Makefile}{$distro}++; } elsif ( -f 'Build.PL' ) { $build_generators{Build}{$distro}++; } else { $build_generators{unidentified}++; } }, } );
quiet
$rv = $self->visit( { action => sub { my $distro = shift @_; if ( -f 'Makefile.PL' ) { say "$distro has Makefile.PL"; } if ( -f 'Build.PL' ) { say "$distro has Build.PL"; } }, quiet => 1, } );
If provided with a true value, suppress any warnings that may appear as files are extracted from individual tarballs in the minicpan.
Report bugs at https://rt.cpan.org/Public/Bug/Report.html?Queue=CPAN-Mini-Visit-Simple.
James E Keenan CPAN ID: jkeenan jkeenan@cpan.org http://thenceforward.net/perl/modules/CPAN-Mini-Visit-Simple/
Mohammad S Anwar
Charlie Gonzalez
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
perl(1). App-CPAN-Mini-Visit. CPAN-Mini.
To install CPAN::Mini::Visit::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CPAN::Mini::Visit::Simple
CPAN shell
perl -MCPAN -e shell install CPAN::Mini::Visit::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.