# NAME

Data::SearchEngine - A role for search engine abstraction.

# VERSION

version 0.32

# SYNOPSIS

  package Data::SearchEngine::MySearch;
  use Moose;

  with 'Data::SearchEngine';

  sub search {
    my ($self, $query) = @_;

    # ... your internal search junk

    my $result = Data::SearchEngine::Results->new(
        query => $query,
        pager => # ... make a Data::Page
    );

    my @hits; # Populate with hits somehow

    foreach my $hit (@hits) {
        $result->add(Data::SearchEngine::Item->new(
            values => {
                name => $hit->name,
                description => $hit->description
            },
            score => $hit->score
        ));
    }

    return $result;
  }

# DESCRIPTION

There are __lots__ of search engine libraries.  Each has a different interface.
The goal of Data::SearchEngine is to provide a simple, extensive set of
classes and roles that you can use to wrap a search implementation.  The net
result will be an easily swappable backend with a common set of features.

# IMPLEMENTATION

__NOTE:__ You should avoid adding new attributes or subclassing
Data::SearchEngine classes unless otherwise noted. Doing so will break
compatability with future releases and obviate the whole reason that
Data::SearchEngine exists.  The only exception is the Results class (step 3
below) which should __only__ be a subclass with roles applied, no new attributes
or methods.

## Step 1 - Wrap a search implementation

As shown in the SYNOPSIS, use the [Data::SearchEngine](http://search.cpan.org/perldoc?Data::SearchEngine) role in a class that
wraps your search implementation.  Implement a `search` method that takes a
[Data::SearchEngine::Query](http://search.cpan.org/perldoc?Data::SearchEngine::Query) object and returns a
[Data::SearchEngine::Results](http://search.cpan.org/perldoc?Data::SearchEngine::Results) object.

## Step 2 - Use Other Roles

If your library includes functionality other than searching, such as indexing
new documents or removing them, you may include the 
[Data::SearchEngine::Modifiable](http://search.cpan.org/perldoc?Data::SearchEngine::Modifiable) role.  If you have other suggestions for
roles please drop me a line!

## Step 3 - Extend the Results

The results object may not have quite enough pieces for your implementation.
If not, you can `extend` [Data::SearchEngine::Results](http://search.cpan.org/perldoc?Data::SearchEngine::Results) and add some other
roles:

- Data::SearchEngine::Results::Faceted

For results that contain faceted data.

- Data::SearchEngine::Results::Spellcheck

For results that contain spellcheck data.

# DIGESTS

Data::SearchEngine provides a Digestable trait that can be applied to
attributes of `Query`.  Attributes with this trait will be added to
a base64 MD5 digest to produce a unique key identifying this query.  You can
then serialize the Result using [MooseX::Storage](http://search.cpan.org/perldoc?MooseX::Storage) and store it under the
digest of the Query for caching.

# ATTRIBUTES

## debug

An attribute that signals the backend should operate in a debugging mode.
Please see the implementation module for specifics on how to use this.

## defaults

The `defaults` attribute is a simple HashRef that backends may use to get
default settings from the user.  The implementation of `search` may then use
these defaults when setting up instances of a search.

# METHODS

## is_debug

Method for determining if the debug attribute has been set.

## get_default ($key)

Returns the value from `defaults` (if any) for the specified key.

## set_default ($key, $value)

Sets the value in `defaults`.

# AUTHOR

Cory G Watson <gphat@cpan.org>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Cold Hard Code, LLC.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.