The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

CPAN::Nearest - find the nearest module to a given name.

SYNOPSIS

    use CPAN::Nearest 'search';
    my $mod = 'Lingua::Stop::Wars';
    my $pfile = "$ENV{HOME}/.cpan/sources/modules/02packages.details.txt.gz";
    print "Nearest to $mod in $pfile is '", search ($pfile, $mod), "'.\n";
    

produces output

    Nearest to Lingua::Stop::Wars in /home/ben/.cpan/sources/modules/02packages.details.txt.gz is 'Lingua::StopWords'.

(This example is included as synopsis.pl in the distribution.)

VERSION

This documents CPAN::Nearest version 0.14 corresponding to git commit e5d10622fb2b0d42cc35557d36be2885583521fe released on Fri Oct 5 10:43:44 2018 +0900.

DESCRIPTION

This module provides a way of searching for CPAN modules whose name may be misspelt. For example, if a user accidentally types "Lingua::Stopwords" when looking for the module "Lingua::StopWords", the common cpan clients will not be able to function:

    cpan Lingua::Stopwords

gives

    Warning: Cannot install Lingua::Stopwords, don't know what it is.
    Try the command

    i /Lingua::Stopwords/

    to find objects with matching identifiers.

and

    cpanm Lingua::Stopwords

gives

    ! Finding Lingua::Stopwords on cpanmetadb failed.
    ! Finding Lingua::Stopwords on search.cpan.org failed.
    ! Finding Lingua::Stopwords () on mirror http://www.cpan.org failed.
    ! Couldn't find module or a distribution Lingua::Stopwords ()

CPAN::Nearest supplies a spelling-mistake tolerant search for the most similar name.

FUNCTIONS

    my $close_name = search ($file, $module_name);

Search the package detail file $file for a module named $module_name and return the closest name. For example, if you search for "Harry::Potter":

    use CPAN::Nearest 'search';
    my $file = "$ENV{HOME}/.cpan/sources/modules/02packages.details.txt.gz";
    my $close_name = search ($file, 'Harry::Potter');
    print "$close_name\n";

produces output

    Data::Lotter

(This example is included as harry-potter.pl in the distribution.)

The file specified by the first argument, $file in the example, is usually found at ~/.cpan/sources/modules/02packages.details.txt.gz on a Unix-like system. See "FILES" if you want to locate this file. This may be specified as the file name. This module can read either a compressed or uncompressed version.

EXPORTS

"search" is exported on demand.

DEPENDENCIES

Carp
Text::Fuzzy

Text::Fuzzy is used to do the searches of the CPAN data. See "HISTORY".

Gzip::Faster

Gzip::Faster is used to process compressed package files.

SEE ALSO

fatfinger

This looks for similarly-named modules via Text::Levenshtein::Damerau.

FILES

Users of the cpan utility supplied with Perl may find the file listing the CPAN modules in ~/.cpan/sources/modules/02packages.details.txt.gz. Others can download the file from the directory /modules/ of any CPAN mirror.

HISTORY

CPAN::Nearest was created as a module for people making tools like cpan, cpanm, pm-uninstall, and anything else which needs to use the CPAN packages list. It was inspired by the helpful "git" version control system, which provides suggestions for spelling mistakes. CPAN::Nearest was written to be fast enough for practical use by writing it mostly in C with an XS binding to Perl.

It was the precursor of Text::Fuzzy by the same author (Ben Bullock). In version 0.13, all of the search functionality of CPAN::Nearest was moved to Text::Fuzzy and the XS parts of the module were removed, and the package-list reading part rewritten in Perl. The standalone C program was also removed from the distribution in version 0.13, and its documentation was deleted in version 0.14.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2012-2018 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.