NAME

CPAN::Mini::Visit::Simple - Lightweight traversal of a minicpan repository

SYNOPSIS

use CPAN::Mini::Visit::Simple;
$self = CPAN::Mini::Visit::Simple->new();
$self->identify_distros();

DESCRIPTION

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.

GLOSSARY

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.

METHODS

`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.

May also be called with a single hash reference whose minicpan element's value is the absolute path to a minicpan repository.
Return Value

CPAN::Mini::Visit::Simple object.

`get_minicpan()`

Purpose

Get the full path to the local minicpan/ installation as stored within the object.
Arguments
```
$minicpan_dir = $self->get_minicpan();
```
Return Value

String holding path to directory.

`get_id_dir()`

Purpose

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.
Arguments
```
$minicpan_id_dir = $self->get_id_dir();
```
Return Value

String holding path to directory.

`identify_distros()`

Purpose

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.
Arguments

May be called in any of the following two mutually exclusive ways:
1 No arguments
```
$self->identify_distros();
```
This will add all distributions found in the minicpan repository to the primary list.
2 Single hash reference
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.
- 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.
Return Value

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()`

Purpose

Similar to identify_distros(), but used where, through human editing of a primary list, we have produced a derived_list.

Arguments

$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.

Return Value

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()`

Purpose

Prints a list of distributions to be visited.
Arguments
```
$self->say_list();
```
or
```
$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.
Return Value

Implicitly returns true value.

`get_list()`

Purpose

Get the set of distributions resulting from the operation of identify_distros().

Arguments

@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.

Return Value

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.
Comment

Because of the deduplication feature of identify_distros, the order of elements in the list returned cannot be guaranteed.

`get_list_ref()`

Purpose

Get a reference to the set of distributions resulting from the operation of identify_distros().
Arguments
```
$output_ref = $self->get_list_ref();
```
No arguments needed. All information, if available, is inside the object.
Return Value

Array reference if the underlying set exists in the object; undefined otherwise.
Comment

Because of the deduplication feature of identify_distros, the order of elements in the list underneath the reference returned cannot be guaranteed.

`refresh_list()`

Purpose

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.

Arguments

$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/,
} );

Return Value

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()`

Purpose

Executes an action on each distribution in the list.

Arguments

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.

Return Value

Returns true value upon success.

BUGS

Report bugs at https://rt.cpan.org/Public/Bug/Report.html?Queue=CPAN-Mini-Visit-Simple.

AUTHOR

James E Keenan
CPAN ID: jkeenan
jkeenan@cpan.org
http://thenceforward.net/perl/modules/CPAN-Mini-Visit-Simple/

ADDITIONAL CONTRIBUTORS

Mohammad S Anwar
Charlie Gonzalez

COPYRIGHT

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

GLOSSARY

METHODS

new()

get_minicpan()

get_id_dir()

identify_distros()

identify_distros_from_derived_list()

say_list()

get_list()

get_list_ref()

refresh_list()

visit()

BUGS

AUTHOR

ADDITIONAL CONTRIBUTORS

COPYRIGHT

SEE ALSO

Module Install Instructions

`new()`

`get_minicpan()`

`get_id_dir()`

`identify_distros()`

`identify_distros_from_derived_list()`

`say_list()`

`get_list()`

`get_list_ref()`

`refresh_list()`

`visit()`