The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CPAN-Nearest-0.07
River stage zero No dependents
++
/ CPAN::Nearest

NAME

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

SYNOPSIS

    use CPAN::Nearest 'search';
    my $module = search ('02package.details.txt', 'Lingua::Stop::Wars');
    # Now $module = "Lingua::StopWords";

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, intended for people making tools like cpan, cpanm, pm-uninstall, and anything else which needs to use the CPAN packages list. CPAN::Nearest was written to be fast enough for practical use, and without dependencies.

CPAN::Nearest was inspired by the helpful "git" version control system, which provides suggestions for spelling mistakes.

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. E.g. if you search for "Harry::Potter",

    my $close_name = search ($file, 'Harry::Potter');

the value in $close_name, the closest CPAN module, is "Data::Lotter".

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. This may be specified as the file name. This module can read either a compressed or uncompressed version. There is a speed increase of 10-20% when an uncompressed file is used.

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.

STANDALONE PROGRAM

The distribution includes a standalone program called "nearest-module" as shown in this blog entry. To use this program, edit the file nearest-module.c in the top level of the distribution to point to the name of the file 02packages.details.txt or 02packages.details.txt.gz on your system, and compile it with

    make -f makeitfile nearest-module

It is run with the name of a single module:

    ./nearest-module Lingo::Jingo::Mojo
    Closest to 'Lingo::Jingo::Mojo' is 'Lingua::JA::Moji'.

There is a -v option to view candidate modules:

    $ ./nearest-module -v Lingo::Jingo::Mojo
    Games::Bingo::Bot (9) is nearer than 10.
    Lingua::JA::Moji (7) is nearer than 9.
    Closest to 'Lingo::Jingo::Mojo' is 'Lingua::JA::Moji'.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2012 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.