###########################################
package Perldoc::Search;
###########################################
use strict;
use warnings;
our $VERSION = "0.01";
use Pod::Simple::TextContent;
use SWISH::API::Common;
use Config;
use Cwd;
###########################################
sub new {
###########################################
my($class, %options) = @_;
my $self = {
dirs => [$Config{installsitearch},
$Config{installsitelib},
$Config{installarchlib},
$Config{installprivlib},
],
swish_options => {
swish_adm_dir => "$ENV{HOME}/.perldig",
},
%options,
};
# If the perl lib dir is symlinked, this
# will figure out the real paths
for(@{$self->{dirs}}) {
my $cwd = cwd();
chdir $_ or die "Cannot cwd to $_";
$_ = File::Spec->rel2abs(".");
chdir $cwd;
}
$self->{swish} = SWISH::API::Common->new(
%{$self->{swish_options}}
);
bless $self, $class;
}
###########################################
sub relative {
###########################################
my($self, $path) = @_;
$path =~ s|^$_/|| for @{$self->{dirs}};
return $path;
}
###########################################
sub update {
###########################################
my($self) = @_;
# Index all files in a directory and its subdirectories
$self->{swish}->index(@{$self->{dirs}});
}
###########################################
sub search {
###########################################
my($self, @terms) = @_;
return $self->{swish}->search(@terms);
}
1;
__END__
=head1 NAME
Perldoc::Search - Index and Search local Perl Documentation
=head1 SYNOPSIS
#######################################
# Command line utility:
#######################################
# This is permanent and needs to be performed only once
# (or if new documentation gets installed).
$ perldig -u
# Then, search:
$ perldig log AND apache AND connect
1) CGI/Carp.pm 2) CGI/Prototype.pm
3) DBI/Changes.pm 4) DBI/Changes.pm
Enter number of choice:
#######################################
# API
#######################################
use Perldoc::Search;
my $searcher = Perldoc::Search->new();
# This is permanent and needs to be performed only once
# (or if new documentation gets installed).
$searcher->update();
# Then, search:
for my $hit ($searcher->search("log AND apache")) {
print $hit->path(), "\n";
}
=head1 DESCRIPTION
C<Perldoc::Search> uses the swish-e engine to index the local Perl
documentation. It provides both the command line utility C<perldig>
and an API to perform searches on the index. It uses C<SWISH::API::Common>
as the indexing and search engine.
Most likely, you will want the command line utility C<perldig>, please
check the documentation that comes with it by calling
perldoc perldig
In case you're interested in the API, read on.
=head1 METHODS
=over 4
=item C<my $searcher = Perldoc::Search-$<gt>new()>
Instantiates a searcher object. Usually takes no parameters.
If you like to modify the searched directories or want to pass
different options to C<SWISH::API::Common>, go ahead:
use Config;
my $searcher = Perldoc::Search->new(
dirs => [$Config{installsitearch},
$Config{installsitelib},
$Config{installarchlib},
$Config{installprivlib},
],
swish_options => {
swish_adm_dir => "$ENV{HOME}/.perldig",
}
);
=item C<$searcher->update()>
Update the index. This operation might take a couple of minutes.
=item C<my @hits = $searcher->search("log AND apache")>
Perform a search on the index with the given query. Returns a list of
result objects.
# Search documents containing
# both "foo" and "bar"
for my $hit ($swish->search("foo AND bar")) {
print $hit->path(), "\n";
}
=back
=head1 LEGALESE
Copyright 2005 by Mike Schilli, all rights reserved.
This program is free software, you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 AUTHOR
2005, Mike Schilli <cpan@perlmeister.com>