NAME

SeeAlso::Source - Provides OpenSearch Suggestions reponses

VERSION

version 0.71

SYNOPSIS

  $source = SeeAlso::Source->new;
  $source = SeeAlso::Source->new( sub { ... } );
  $source = SeeAlso::Source->new( callback => sub { ... } );
  ...
  $source->description( "ShortName" => "My source" ... );
  ...
  $response = $source->query( $identifier );

new ( [ $callback ] [ $cache ] [ %parameters ] )

Create a new source. If the first parameter is a code reference or another SeeAlso::Source parameter, it is used as callback parameter. If the first or second parameter is a Cache object, it is used as cache parameter.

cache

Cache or SeeAlso::DBI object to be used as cache.

config

Configuration settings as hash reference or as configuration file that will be read into a hash reference. Afterwarrds the The Source section of the configuration is added to the other parameters (existing parameters are not overridden).

other parameters

Are passed to the description method.

callback ( [ $code | $source | undef ] )

Get or set a callback method or callback source.

cache ( [ $cache | undef ] )

Get or set a cache for this source. The parameter must be a Cache object, a SeeAlso::Source object or undef. Undef disables caching and is the default. Returns the cache object or undef.

query ( $identifier [, force => 1 ] )

Given an identifier (either a SeeAlso::Identifier object or just a plain string) returns a SeeAlso::Response object by calling the query callback method or fetching the response from the cache unless the $force parameter is specified.

query_callback ( $identifier )

Internal core method that maps a SeeAlso::Identifier to a SeeAlso::Response. Clients should not call this metod but the 'query' method that includes type-checking and caching. Subclasses should overwrite this method instead of the 'query' method.

description ( [ $key ] | $key => $value, $key => $value, ... )

Returns additional description about this source in a hash (no key provided) or a specific element of the description. The elements are defined according to elements in an OpenSearch description document. Up to now they are:

ShortName

A short name with up to 16 characters.

LongName

A long name with up to 48 characters.

Description

A description with up to 1024 characters.

BaseURL

URL of the script. Will be set automatically via CGI if not defined.

DateModified

Qualified Dublin Core element Date.Modified.

Source

Source of the data (dc:source)

Example[s]

An example query (a hash of 'id' and optional 'response').

about ( )

Return ShortName, Description, and BaseURL from the description of this Source. Undefined fields are returned as empty string.

serve ( [ $query | $source ] [ $config ] )

Serve a SeeAlso request via SeeAlso::Server::query and exit. This method can also be exported and used as function.

INTERNAL FUNCTIONS

load_config ( $filename )

Load a configuration file (relaxed JSON format) and return a hash reference. On error the hash reference is empty.

expand_from_config ( $hashref, $section )

Expand a hash with config parameters from another hash or from a configuration file. This function can read INI files (if Config::IniFiles is installed), YAML files (if YAML::Any is installed), and JSON files.

AUTHOR

Jakob Voss

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voss.

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

cpanm SeeAlso::Server

perl -MCPAN -e shell
install SeeAlso::Server