File Coverage

blib/lib/Plucene/Simple.pm

Criterion	Covered	Total	%
statement	117	119	98.3
branch	15	20	75.0
condition			n/a
subroutine	31	31	100.0
pod	8	8	100.0
total	171	178	96.0

package Plucene::Simple;

=head1 NAME

Plucene::Simple - An interface to Plucene

=head1 SYNOPSIS

	use Plucene::Simple;

	# create an index
	my $plucy = Plucene::Simple->open($index_path);

	# add to the index
	$plucy->add(
		$id1 => { $field => $term1 },
		$id2 => { $field => $term2 },
	);

	# or ...
	$plucy->index_document($id => $data);

	# search an existing index
	my $plucy = Plucene::Simple->open($index_path);
	my @results = $plucy->search($search_string);

	# optimize the index
	$plucy->optimize;

	# remove something from the index
	$plucy->delete_document($id);

	# is something in the index?
	if ($plucy->indexed($id) { ... }

=head1 DESCRIPTION

This provides a simple interface to L. Plucene is large and
multi-featured, and it expected that users will subclass it, and tie
all the pieces together to suit their own needs. Plucene::Simple is,
therefore, just one way to use Plucene. It's not expected that it will
do exactly what *you* want, but you can always use it as an example of
how to build your own interface.

=head1 INDEXING

=head2 open

You make a new Plucene::Simple object like so:

	my $plucy = Plucene::Simple->open($index_path);

If this index doesn't exist, then it will be created for you, otherwise you
will be adding to an exisiting one.

Then you can add your documents to the index:

=head2 add

Every document must be indexed with a unique key (which will be returned
from searches).

A document can be made up of many fields, which can be added as
a hashref:

	$plucy->add($key, \%data);

	$plucy->add(
		chap1  => {
			title => "Moby-Dick",
			author => "Herman Melville",
	 		text => "Call me Ishmael ..."
		},
		chap2  => {
			title => "Boo-Hoo",
			author => "Lydia Lee",
			text => "...",
		}
	);

=head2 index_document

Alternatively, if you do not want to index lots of metadata, but rather
just simple text, you can use the index_document() method.

	$plucy->index_document($key, $data);
	$plucy->index_document(chap1 => 'Call me Ishmael ...');

=head2 delete_document

	$plucy->delete_document($id);

=head2 optimize

	$plucy->optimize;

Plucene is set-up to perform insertions quickly. After a bunch of inserts
it is good to optimize() the index for better search speed.

=head1 SEARCHING

=head2 search

	my @ids = $plucy->search('ishmael');
	  # ("chap1", ...)

This will return the IDs of each document matching the search term.

If you have indexed your documents with fields, you can also search with
the field name as a prefix:

	my @ids = $plucy->search("author:lee");
		# ("chap2" ...)

	my @results = $plucy->search($search_string);

This will search the index with the given query, and return a list of
document ids.

Searches can be much more powerful than this - see L for
further details.

=head2 search_during

	my @results = $lucy->search_during($search_string, $date1, $date2);
	my @results = $lucy->search_during("to:Fred", "2001-01-01" => "2003-12-31");

If your documents were given an ISO 'date' field when indexing,
search_during() will restrict the results to all documents between the
specified dates. Any document without a 'date' field will be ignored.

=head2 indexed

	if ($plucy->indexed($id) { ... }

This returns true if there is a document with the given ID in the index.

=cut

use strict;
use warnings;

our $VERSION = '1.04';

use Plucene::Analysis::SimpleAnalyzer;
use Plucene::Analysis::WhitespaceAnalyzer;
use Plucene::Document;
use Plucene::Document::DateSerializer;
use Plucene::Document::Field;
use Plucene::Index::Reader;
use Plucene::Index::Writer;
use Plucene::QueryParser;
use Plucene::Search::DateFilter;
use Plucene::Search::HitCollector;
use Plucene::Search::IndexSearcher;

use Carp;
use File::Spec::Functions qw(catfile);
use Time::Piece;
use Time::Piece::Range;

sub open {
	my ($class, $dir) = @_;
	$dir or croak "No directory given";
	bless { _dir => $dir }, $class;
}

sub _dir { shift->{_dir} }

sub _parsed_query {
	my ($self, $query, $default) = @_;
	my $parser = Plucene::QueryParser->new({
			analyzer => Plucene::Analysis::SimpleAnalyzer->new(),
			default  => $default
		});
	$parser->parse($query);
}

sub _searcher { Plucene::Search::IndexSearcher->new(shift->_dir) }

sub _reader { Plucene::Index::Reader->open(shift->_dir) }

sub search {
	my ($self, $sstring) = @_;
	return () unless $sstring;
	my @docs;
	my $searcher = $self->_searcher;
	my $hc       = Plucene::Search::HitCollector->new(
		collect => sub {
			my ($self, $doc, $score) = @_;
			my $res = eval { $searcher->doc($doc) };
			push @docs, [ $res, $score ] if $res;
		});
	$searcher->search_hc($self->_parsed_query($sstring, 'text'), $hc);
	return map $_->[0]->get("id")->string, sort { $b->[1] <=> $a->[1] } @docs;
}

sub search_during {
	my ($self, $sstring, $date1, $date2) = @_;
	return () unless $sstring;
	my $range = Time::Piece::Range->new(
		Time::Piece->strptime($date1, "%Y-%m-%d"),
		Time::Piece->strptime($date2, "%Y-%m-%d"));
	my $filter = Plucene::Search::DateFilter->new({
			field => '_date_',
			from  => $range->start,
			to    => $range->end,
		});
	my $qp = Plucene::QueryParser->new({
			analyzer => Plucene::Analysis::WhitespaceAnalyzer->new(),
			default  => "text"
		});
	my $query = $qp->parse($sstring);
	my $hits = $self->_searcher->search($query, $filter);
	return () unless $hits->length;
	my @docs = map $hits->doc($_), 0 .. ($hits->length - 1);
	return map $_->get("id")->string, @docs;
}

sub _writer {
	my $self = shift;
	return Plucene::Index::Writer->new(
		$self->_dir,
		Plucene::Analysis::SimpleAnalyzer->new(),
		-e catfile($self->_dir, "segments") ? 0 : 1
	);
}

sub add {
	my ($self, @data) = @_;
	my $writer = $self->_writer;
	while (my ($id, $terms) = splice @data, 0, 2) {
		my $doc = Plucene::Document->new;
		$doc->add(Plucene::Document::Field->Keyword(id => $id));
		foreach my $key (keys %$terms) {
			if ($key eq 'text') {
				next;    # gets added at the end anyway
			} elsif ($key eq "date") {
				my $date = eval { Time::Piece->strptime($terms->{date}, "%Y-%m-%d") };
				do { $date = Time::Piece->new; $terms->{date} = $date->ymd; } if $@;
				$doc->add(
					Plucene::Document::Field->Keyword("_date_", freeze_date($date)));
				$doc->add(Plucene::Document::Field->Keyword("date", $date->ymd));
			} else {
				$doc->add(Plucene::Document::Field->UnStored($key => $terms->{$key}));
				$terms->{text} .= " " . $terms->{$key} unless $key =~ /^_/;
			}
		}
		$doc->add(Plucene::Document::Field->UnStored(text => $terms->{text}));
		$writer->add_document($doc);
	}
	undef $writer;
}

sub index_document {
	my ($self, $id, $data) = @_;
	my $writer = $self->_writer;
	my $doc    = Plucene::Document->new;
	$doc->add(Plucene::Document::Field->Keyword(id => $id));
	$doc->add(Plucene::Document::Field->UnStored('text' => $data));
	$writer->add_document($doc);
	undef $writer;
}

sub delete_document {
	my ($self, $id) = @_;
	my $reader = $self->_reader;
	$reader->delete_term(
		Plucene::Index::Term->new({ field => "id", text => $id }));
	$reader->close;
}

sub optimize { shift->_writer->optimize() }

sub indexed {
	my ($self, $id) = @_;
	my $term = Plucene::Index::Term->new({ field => 'id', text => $id });
	return $self->_reader->doc_freq($term);
}

=head1 COPYRIGHT

Copyright (C) 2003-2004 Kasei Limited

=cut

1;