r21381 - in /branches/upstream/libperldoc-search-perl: ./ current/ current/eg/ current/lib/ current/lib/Perldoc/ current/t/
gregoa at users.alioth.debian.org
gregoa at users.alioth.debian.org
Sun Jun 15 14:45:39 UTC 2008
Author: gregoa
Date: Sun Jun 15 14:45:38 2008
New Revision: 21381
URL: http://svn.debian.org/wsvn/?sc=1&rev=21381
Log:
[svn-inject] Installing original source of libperldoc-search-perl
Added:
branches/upstream/libperldoc-search-perl/
branches/upstream/libperldoc-search-perl/current/
branches/upstream/libperldoc-search-perl/current/Changes
branches/upstream/libperldoc-search-perl/current/MANIFEST
branches/upstream/libperldoc-search-perl/current/MANIFEST.SKIP
branches/upstream/libperldoc-search-perl/current/META.yml
branches/upstream/libperldoc-search-perl/current/Makefile.PL
branches/upstream/libperldoc-search-perl/current/README
branches/upstream/libperldoc-search-perl/current/eg/
branches/upstream/libperldoc-search-perl/current/eg/perldig (with props)
branches/upstream/libperldoc-search-perl/current/lib/
branches/upstream/libperldoc-search-perl/current/lib/Perldoc/
branches/upstream/libperldoc-search-perl/current/lib/Perldoc/Search.pm
branches/upstream/libperldoc-search-perl/current/t/
branches/upstream/libperldoc-search-perl/current/t/001Basic.t
Added: branches/upstream/libperldoc-search-perl/current/Changes
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/Changes?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/Changes (added)
+++ branches/upstream/libperldoc-search-perl/current/Changes Sun Jun 15 14:45:38 2008
@@ -1,0 +1,5 @@
+######################################################################
+Revision history for Perl extension Perldoc::Search
+
+0.01 2005/08/21
+ * Where it all began.
Added: branches/upstream/libperldoc-search-perl/current/MANIFEST
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/MANIFEST?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/MANIFEST (added)
+++ branches/upstream/libperldoc-search-perl/current/MANIFEST Sun Jun 15 14:45:38 2008
@@ -1,0 +1,9 @@
+Changes
+eg/perldig
+lib/Perldoc/Search.pm
+Makefile.PL
+MANIFEST This list of files
+MANIFEST.SKIP
+README
+t/001Basic.t
+META.yml Module meta-data (added by MakeMaker)
Added: branches/upstream/libperldoc-search-perl/current/MANIFEST.SKIP
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/MANIFEST.SKIP?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/MANIFEST.SKIP (added)
+++ branches/upstream/libperldoc-search-perl/current/MANIFEST.SKIP Sun Jun 15 14:45:38 2008
@@ -1,0 +1,8 @@
+blib
+^Makefile$
+^Makefile.old$
+CVS
+.cvsignore
+docs
+MANIFEST.bak
+adm/release
Added: branches/upstream/libperldoc-search-perl/current/META.yml
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/META.yml?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/META.yml (added)
+++ branches/upstream/libperldoc-search-perl/current/META.yml Sun Jun 15 14:45:38 2008
@@ -1,0 +1,14 @@
+# http://module-build.sourceforge.net/META-spec.html
+#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
+name: Perldoc-Search
+version: 0.01
+version_from: lib/Perldoc/Search.pm
+installdirs: site
+requires:
+ File::Temp: 0
+ Pod::Simple::TextContent: 0
+ Shell::POSIX::Select: 0
+ SWISH::API::Common: 0
+
+distribution_type: module
+generated_by: ExtUtils::MakeMaker version 6.30
Added: branches/upstream/libperldoc-search-perl/current/Makefile.PL
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/Makefile.PL?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/Makefile.PL (added)
+++ branches/upstream/libperldoc-search-perl/current/Makefile.PL Sun Jun 15 14:45:38 2008
@@ -1,0 +1,19 @@
+######################################################################
+# Makefile.PL for Perldoc::Search
+# 2005, Mike Schilli <cpan at perlmeister.com>
+######################################################################
+use ExtUtils::MakeMaker;
+WriteMakefile(
+ 'NAME' => 'Perldoc::Search',
+ 'VERSION_FROM' => 'lib/Perldoc/Search.pm', # finds $VERSION
+ 'PREREQ_PM' => {
+ SWISH::API::Common => 0,
+ Shell::POSIX::Select => 0,
+ Pod::Simple::TextContent => 0,
+ File::Temp => 0,
+ }, # e.g., Module::Name => 1.1
+ EXE_FILES => ['eg/perldig'],
+ ($] >= 5.005 ? ## Add these new keywords supported since 5.005
+ (ABSTRACT_FROM => 'lib/Perldoc/Search.pm',
+ AUTHOR => 'Mike Schilli <cpan at perlmeister.com>') : ()),
+);
Added: branches/upstream/libperldoc-search-perl/current/README
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/README?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/README (added)
+++ branches/upstream/libperldoc-search-perl/current/README Sun Jun 15 14:45:38 2008
@@ -1,0 +1,91 @@
+######################################################################
+ Perldoc::Search 0.01
+######################################################################
+
+NAME
+ Perldoc::Search - Index and Search local Perl Documentation
+
+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";
+ }
+
+DESCRIPTION
+ "Perldoc::Search" uses the swish-e engine to index the local Perl
+ documentation. It provides both the command line utility "perldig" and
+ an API to perform searches on the index. It uses "SWISH::API::Common" as
+ the indexing and search engine.
+
+ Most likely, you will want the command line utility "perldig", please
+ check the documentation that comes with it by calling
+
+ perldoc perldig
+
+ In case you're interested in the API, read on.
+
+METHODS
+ "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 "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",
+ }
+ );
+
+ "$searcher-"update()>
+ Update the index. This operation might take a couple of minutes.
+
+ "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";
+ }
+
+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.
+
+AUTHOR
+ 2005, Mike Schilli <cpan at perlmeister.com>
+
Added: branches/upstream/libperldoc-search-perl/current/eg/perldig
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/eg/perldig?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/eg/perldig (added)
+++ branches/upstream/libperldoc-search-perl/current/eg/perldig Sun Jun 15 14:45:38 2008
@@ -1,0 +1,147 @@
+#!/usr/bin/perl
+use warnings;
+use strict;
+
+use Config;
+use Perldoc::Search;
+use Shell::POSIX::Select;
+use File::Basename;
+use Getopt::Std;
+use Pod::Simple::TextContent;
+
+our $LESS = "/usr/bin/less";
+
+getopts("u", \my %opts);
+
+my $searcher = Perldoc::Search->new();
+
+if($opts{u}) {
+ print "This will take a couple of minutes, please stand by.\n";
+ $searcher->update();
+ print "Done\n";
+} elsif(@ARGV) {
+ search();
+}
+
+###########################################
+sub search {
+###########################################
+
+ # Search documents containing both "swish" and "install"
+ my @hits = $searcher->search("@ARGV");
+
+ if ( !@hits ) {
+ print "No Results\n";
+ return;
+ }
+
+ my @select = ();
+ my %map = ();
+
+ # Shut up the goofy Shell::POSIX::Select implementation
+ our($Eof, $Reply);
+
+ for my $hit (@hits) {
+ if(! defined $hit) {
+ die "Before searching, please run the indexer: perldig -u\n";
+ }
+ my $path = my $org_path = $hit->path();
+ $path = $searcher->relative($path);
+ push @select, $path;
+ $map{$path} = $org_path;
+ }
+
+ @select = sort @select;
+
+ select my $file (@select) {
+ system "$LESS $map{$file}";
+ last;
+ }
+}
+
+__END__
+
+=head1 NAME
+
+ perldig - Dig up keywords in the local Perl documentation
+
+=head1 SYNOPSIS
+
+ # Update the index (required before first start)
+ perldig -u
+
+ # Search for a keyword
+ perldig keyword(s)
+
+=head1 DESCRIPTION
+
+When using C<perldig> for the first time, a new index needs to be
+created. Just call
+
+ $ perldig -u
+
+and everything happens automatically: A crawler will detect locally
+installed Perl documentation pages, rummage through the POD and index
+them. When this initial run has been completed, C<perldig> is ready to
+process search requests:
+
+ $ perldig frobnicate
+
+ 1) pod/perlguts.pod 2) pod/perlxstut.pod 3) pod/perlnewmod.pod
+
+ Enter number of choice:
+
+The command above shows a search for the keyword C<frobnicate>. Yes,
+that's a word used in the Perl documentation! It shows three hits and
+asks the user to enter a number between 1 and 3 to open the selected
+documentation page in a pager program (typically C<less>). In there,
+an in-text search for the expression can be started by using the C</>
+(slash) command.
+
+If two or more keywords are given, the search will yield pages that
+contain all of them. When searching for phrases, please include quotes
+(make sure to quote the quotes so the shell doesn't eat them):
+
+ $ perldig '"floating point"'
+
+The underlying I<swish-e> search engine also understands expressions
+connected via AND and OR:
+
+ $ perldig "'floating point' AND approximate AND 'real number'"
+
+To keep the index up to date, it is probably a good idea to run a
+cronjob every morning:
+
+ 00 4 * * * /usr/bin/perldig -u >/dev/null 2>&1
+
+If you can read German, please check out this article in the "Linux-
+Magazin", where this script was originally published:
+
+ http://www.linux-magazin.de/Artikel/ausgabe/2003/10/perl/perl.html
+
+=head1 EXAMPLES
+
+ # Update/create the index
+ $ perldig -u
+
+ $ perldig frobnicate
+
+ 1) pod/perlguts.pod 2) pod/perlxstut.pod 3) pod/perlnewmod.pod
+
+ Enter number of choice: 1
+ [ ... perlguts man page shows ... ]
+
+=head1 FILES
+
+C<perldig> puts the I<swish-e> index files into the folder C<.perldig>
+in the user's home directory.
+
+=head1 LEGALESE
+
+Copyright 2003-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
+
+2003, Mike Schilli <m at perlmeister.com>
Propchange: branches/upstream/libperldoc-search-perl/current/eg/perldig
------------------------------------------------------------------------------
svn:executable =
Added: branches/upstream/libperldoc-search-perl/current/lib/Perldoc/Search.pm
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/lib/Perldoc/Search.pm?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/lib/Perldoc/Search.pm (added)
+++ branches/upstream/libperldoc-search-perl/current/lib/Perldoc/Search.pm Sun Jun 15 14:45:38 2008
@@ -1,0 +1,175 @@
+###########################################
+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 at perlmeister.com>
Added: branches/upstream/libperldoc-search-perl/current/t/001Basic.t
URL: http://svn.debian.org/wsvn/branches/upstream/libperldoc-search-perl/current/t/001Basic.t?rev=21381&op=file
==============================================================================
--- branches/upstream/libperldoc-search-perl/current/t/001Basic.t (added)
+++ branches/upstream/libperldoc-search-perl/current/t/001Basic.t Sun Jun 15 14:45:38 2008
@@ -1,0 +1,50 @@
+######################################################################
+# Test suite for Perldoc::Search
+# by Mike Schilli <cpan at perlmeister.com>
+######################################################################
+
+use warnings;
+use strict;
+
+use Test::More qw(no_plan);
+use File::Temp qw(tempdir);
+
+BEGIN { use_ok('Perldoc::Search') };
+
+my $tempdir = tempdir(CLEANUP => 1);
+mkdir "$tempdir/adm" or die "Cannot mkdir ($!)";
+mkdir "$tempdir/data" or die "Cannot mkdir ($!)";
+
+my $searcher = Perldoc::Search->new(
+ dirs => ["$tempdir/data"],
+ swish_options => {
+ swish_adm_dir => "$tempdir/adm",
+ }
+);
+
+blurt("abc def ghi", "$tempdir/data/file1");
+blurt("abc def jkl", "$tempdir/data/file2");
+
+ok($searcher->update(), "Updating index");
+
+my $hits = join "-", map { $_->path() } $searcher->search("ghi");
+like($hits, qr/file1/, "Query");
+unlike($hits, qr/file2/, "Query");
+
+$hits = join "-", map { $_->path() } $searcher->search("jkl");
+unlike($hits, qr/file1/, "Query");
+like($hits, qr/file2/, "Query");
+
+$hits = join "-", map { $_->path() } $searcher->search("abc AND def");
+like($hits, qr/file1/, "Query");
+like($hits, qr/file2/, "Query");
+
+#################
+sub blurt {
+#################
+ my($data, $file) = @_;
+
+ open FILE, ">$file" or die "Cannot open $file ($!)";
+ print FILE $data;
+ close FILE;
+}
More information about the Pkg-perl-cvs-commits
mailing list