The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Search-OpenSearch-0.400
River stage two • 6 direct dependents • 12 total dependents
1 ++
/ Search::OpenSearch::Engine

NAME

Search::OpenSearch::Engine - abstract base class

SYNOPSIS

 use Search::OpenSearch::Engine;
 my $engine = Search::OpenSearch::Engine->new(
    index       => [qw( path/to/index1 path/to/index2 )],
    facets      => {
        names       => [qw( color size flavor )],
        sample_size => 10_000,
    },
    fields      => [qw( color size flavor )],   # result attributes in response
    indexer_config  => {
        somekey => somevalue,
    },
    searcher_config => {
        anotherkey => anothervalue,
    },
    suggester_config => {
        akey => avalue,
    },
    cache_ok        => 1,
    cache           => CHI->new(
        driver           => 'File',
        dir_create_mode  => 0770,
        file_create_mode => 0660,
        root_dir         => "/tmp/opensearch_cache",
    ),
    cache_ttl       => 3600,
    do_not_hilite   => { color => 1 },
    snipper_config  => { as_sentences => 1 },        # see Search::Tools::Snipper
    hiliter_config  => { class => 'h', tag => 'b' }, # see Search::Tools::HiLiter
    parser_config   => {},                           # see Search::Query::Parser
    
 );
 my $response = $engine->search(
    q   => 'quick brown fox',   # query
    s   => 'score desc',        # sort order
    o   => 0,                   # offset
    p   => 25,                  # page size
    h   => 1,                   # highlight query terms in results
    c   => 0,                   # count total only (same as f=0 r=0)
    L   => 'field|low|high',    # limit results to inclusive range
    f   => 1,                   # include facets
    r   => 1,                   # include results
    t   => 'XML',               # or JSON
    u   => 'http://yourdomain.foo/opensearch/',
    b   => 'AND',               # or OR
    x   => [qw( foo bar )],     # return only a subset of fields
 );
 print $response;

DESCRIPTION

Search::OpenSearch::Engine is an abstract base class. It defines some sane method behavior based on the SWISH::Prog::Searcher API.

METHODS

This class is a subclass of Rose::ObjectX::CAF. Only new or overridden methods are documented here.

version

Returns the $VERSION for the Engine.

BUILD

Sets up the new object.

init_indexer

Subclasses must implement this method if they wish to support REST methods (PUT POST DELETE).

Initialize the link() attribute. This is a builder method.

init_searcher

Subclasses must implement this method. If the Searcher object acts like a SWISH::Prog::Searcher or Dezi::Searcher, then search() will Just Work. Otherwise, your Engine subclass should likely override search() as well.

init_suggester

Subclasses may implement this method. It should return an object that acts like LucyX::Suggester: it should have a method called suggest() which expects a query string and returns an array ref of strings which will be included in the Response under the suggestions key.

search( args )

See the SYNOPSIS.

Returns a Search::OpenSearch::Response object based on the format specified in args.

set_limit( args )

Called internally by search(). The args will be three key/value pairs, with keys "field," "low", and "high".

facets

Get/set a Search::OpenSearch::Facets object.

index

Get/set the location of the inverted indexes to be searched. The value is intented to be used in init_searcher().

searcher

The value returned by init_searcher().

suggester

The value returned by init_suggester().

fields

Get/set the arrayref of field names to be fetched for each search result.

type

Should return a unique identifier for your Engine subclass. Default is to croak().

The base URI for Responses. Passed to Response->link.

get_facets_cache_key( query, search_args )

Returns a string used to key the facets cache. Override this method in a subclass to implement more nuanced string construction.

get_facets( query, results )

Checks the cache for facets related to query and, if found, returns them. If not found, calls build_facets(), which must be implemented by each Engine subclass.

build_facets( query, results )

Default will croak. Engine subclasses must implement this method to provide Facet support.

build_results( results )

results should be an iterator like SWISH::Prog::Results.

Returns an array ref of hash refs, each corresponding to a single search result.

process_result( hash_of_args )

Called by build_results for each result object. hash_of_args is a list of key/value pairs that includes:

result

The values returned from results->next.

hiliter

A Search::Tools::HiLiter object.

snipper

A Search::Tools::Snipper object.

XMLer

A Search::Tools::XML object.

fields

Array ref of fields defined in the new() constructor.

Returns a hash ref, where each key is a field name.

cache_ok

If set to 0, no internal cache object will be created for you. You can still set one in the cache param, but the automatic creation is turned off.

cache

Get/set the internal CHI object. Defaults to the File driver. Typically passed as param in new().

init_cache_key_seed

The string used in get_facets_cache_key() to construct the key for caching facets. You can set in new() with 'cache_key_seed' or override in a base class.

cache_ttl

Get/set the cache key time-to-live. Default is 1 hour. Typically passed as param in new().

do_not_hilite

Get/set the hash ref of field names that should not be hilited in a Response. Typically passed as param in new().

snipper_config

Get/set the hash ref of Search::Tools::Snipper->new params. Typically passed as param in new().

hiliter_config

Get/set the hash ref of Search::Tools::HiLiter->new params. Typically passed as param in new().

parser_config

Get/set the hash ref of Search::Tools::QueryParser->new params. Typically passed as param in new().

indexer_config

Get/set the hash ref available to subclasses that implement a REST API. Typically passed as param in new().

searcher_config

Get/set the hash ref available to subclasses in init_searcher(). Typically passed as param in new().

suggester_config

Get/set the hash ref available to subclasses that implement init_suggester(). Typically passed as param in new().

no_hiliting( field_name )

By default, looks up field_name in the do_no_hilite() hash, but you can override this method to implement whatever logic you want.

logger( logger_object )

Get/set an optional logging object, which must implement a method called log and expect a single string.

has_rest_api( 0|1 )

Override this method in a subclass in order to indicate support for more than just searching an index. Examples include support for DELETE, PUT, POST and GET HTTP methods on particular documents in the index.

Default is false.

get_allowed_http_methods

Override this method in a subclass in order to indicate the supported HTTP methods. Assumes has_rest_api() is true.

debug([boolean])

Get/set the debug flag for messaging on stderr.

init_default_response_format

Returns default response format. Defaults to 'XML'.

error

Get/set the error value for the Engine.

array_field_values([boolean])

Return all non-default field values as array refs rather than strings. This supports the multi-value \003 separator used by SWISH::3.

response_version

The version string to include in Response. Defaults to version().

init_cache

Builder method for cache.

init_hiliter_config

Builder method for hiliter_config.

init_indexer_config

Builder method for indexer_config.

init_parser_config

Builder method for parser_config.

init_searcher_config

Builder method for searcher_config.

init_snipper_config

Builder method for snipper_config.

init_suggester_config

Builder method for suggester_config.

AUTHOR

Peter Karman, <karman at cpan.org>

BUGS

Please report any bugs or feature requests to bug-search-opensearch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Search-OpenSearch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Search::OpenSearch

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2010 Peter Karman.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.