

=head1 NAME

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

=head1 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 L<F<synopsis.pl>|https://fastapi.metacpan.org/source/BKB/CPAN-Nearest-0.14/examples/synopsis.pl> in the distribution.)


=head1 VERSION

This documents CPAN::Nearest version 0.14
corresponding to git commit L<e5d10622fb2b0d42cc35557d36be2885583521fe|https://github.com/benkasminbullock/nearest-module/commit/e5d10622fb2b0d42cc35557d36be2885583521fe> released on Fri Oct 5 10:43:44 2018 +0900.

=head1 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.

=head1 FUNCTIONS

=head2 search

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

Search the package detail file C<$file> for a module named
C<$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 L<F<harry-potter.pl>|https://fastapi.metacpan.org/source/BKB/CPAN-Nearest-0.14/examples/harry-potter.pl> in the distribution.)


The file specified by the first argument, C<$file> in the example, is
usually found at F<~/.cpan/sources/modules/02packages.details.txt.gz>
on a Unix-like system. See L</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.

=head1 EXPORTS

L</search> is exported on demand.

=head1 DEPENDENCIES

=over

=item L<Carp>

=item Text::Fuzzy

L<Text::Fuzzy> is used to do the searches of the CPAN data. See
L</HISTORY>.

=item Gzip::Faster

L<Gzip::Faster> is used to process compressed package files.

=back

=head1 SEE ALSO

=over

=item L<fatfinger>

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

=back

=head1 FILES

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

=head1 HISTORY

CPAN::Nearest was created as a module for people making tools like
C<cpan>, C<cpanm>, C<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 L<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.



=head1 AUTHOR

Ben Bullock, <bkb@cpan.org>

=head1 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.



