=head1 NAME
Pangloss::Search - search through Pangloss Terms.
=head1 SYNOPSIS
use Pangloss::Search;
my $search = new Pangloss::Search;
$search->terms( $terms->clone )
->categories( $categories )
->concepts( $concepts )
->languages( $languages )
->users( $users );
$search->add_filters( @filters );
$search->apply;
$results = $search->results;
=cut
package Pangloss::Search;
use Error qw( :try );
use UNIVERSAL qw( isa );
use Pangloss::Terms;
use Pangloss::Users;
use Pangloss::Concepts;
use Pangloss::Languages;
use Pangloss::Categories;
use Pangloss::Search::Results;
use base qw( Pangloss::Object );
use accessors qw( filters categories concepts
languages terms users results );
our $VERSION = ((require Pangloss::Version), $Pangloss::VERSION)[1];
our $REVISION = (split(/ /, ' $Revision: 1.10 $ '))[2];
sub init {
my $self = shift;
$self->filters( [] )
->categories( Pangloss::Categories->new )
->concepts( Pangloss::Concepts->new )
->languages( Pangloss::Languages->new )
->terms( Pangloss::Terms->new )
->users( Pangloss::Users->new );
}
sub add_filters {
my $self = shift;
$self->add_filter($_) for (@_);
return $self;
}
sub add_filter {
my $self = shift;
my $filter = shift;
return unless isa( $filter, 'Pangloss::Search::Filter' );
push @{ $self->filters }, $filter;
return $self;
}
sub apply {
my $self = shift;
my $mode = shift || 'intersect';
my $apply_method = "apply_$mode";
unless ($self->can( $apply_method )) {
$self->emit( "don't know how to apply $mode" );
return;
}
$self->results( Pangloss::Search::Results->new->parent($self) )
->$apply_method
->results->parent(undef);
return $self;
}
sub apply_intersect {
my $self = shift;
I_TERM:
foreach my $term ($self->terms->list) {
my @filters = @{ $self->filters };
while (my $filter = shift @filters) {
$filter->parent( $self );
my $applies = $filter->applies_to( $term );
$filter->parent( undef );
if ($applies) {
# only add if matches all filters
$self->remove_term( $term )
->add_result( $term )
unless (scalar @filters);
} else {
next I_TERM;
}
}
}
return $self;
}
sub apply_union {
my $self = shift;
$self->results( Pangloss::Search::Results->new );
U_TERM:
foreach my $term ($self->terms->list) {
foreach my $filter (@{ $self->filters }) {
$filter->parent( $self );
my $applies = $filter->applies_to( $term );
$filter->parent( undef );
if ($applies) {
$self->remove_term( $term )
->add_result( $term );
next TERM;
}
}
}
return $self;
}
sub add_result {
my $self = shift;
my $term = shift;
$self->results->add( $term->clone );
return $self;
}
sub remove_term {
my $self = shift;
my $term = shift;
try {
$self->terms->remove( $term );
} catch Error with {
$self->emit( "WARNING: error removing $term: " . shift );
};
return $self;
}
1;
__END__
#------------------------------------------------------------------------------
=head1 DESCRIPTION
Search through a collection of L<Pangloss::Terms>.
=head1 METHODS
TODO: document other API methods.
B<Note:> the $obj->terms collection gets modified, so you should consider
cloning it before handing it over... individual terms that end up in the
result set are cloned, so you don't have to worry about doing a deep_clone().
=over 4
=item $obj = $obj->apply( [ $mode ] )
Applies the filters to the L<Pangloss::Terms>, and returns this object. Results
are accessible via $obj->results() (a L<Pangloss::Search::Results> object).
The results will contain all terms that match the filters (ie: those where
$filter->applies_to( $term ) evaluates to C<true>).
The $mode argument is a set-theory switch that affects how terms will be
added to the result set. It defaults to 'intersect', but may also be set to
'union'.
Note that collection of terms will be modified - this means you should give a
shallow copy of the terms to search objects.
=back
=head1 AUTHOR
Steve Purkis <spurkis@quiup.com>
=head1 SEE ALSO
L<Pangloss>,
L<Pangloss::Search::Request>,
L<Pangloss::Search::Results>,
L<Pangloss::Search::Filters>,
=cut