The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PGXN-API-Searcher-v0.10.1
River stage one • 1 direct dependent • 1 total dependent
++
/ PGXN::API::Searcher

Name

PGXN::API::Searcher - PGXN API full text search interface

Synopsis

  use PGXN::API::Searcher;
  use JSON;
  my $search = PGXN::API::Searcher->new('/path/to/api/root');
  encode_json $search->search( query => $query, in => 'docs' );

Description

PGXN is a CPAN-inspired network for distributing extensions for the PostgreSQL RDBMS. All of the infrastructure tools, however, have been designed to be used to create networks for distributing any kind of release distributions and for providing a lightweight static file JSON REST API.

This module encapsulates the PGXN API search functionality. The indexes are created by PGXN::API::Indexer; this module parses search queries, executes them against the appropriate index, and returns the results as a hash suitable for serializing to JSON in response to a request.

To use this module, one must have a path to the API server document root created by PGXN::API. That is, with access to the same file system. It is therefore used by PGXN::API itself to process search requests. It will also be used by WWW::PGXN if its mirror URI is specified as a file: URI.

Chances are, if you want to use the PGXN search API, what you really want to use is WWW::PGXN. This module simply provides the low-level file system access to the search databases used by PGXN::API and WWW::PGXN to provide the search interfaces.

But in case you do want to use this module, here are the gory details.

Interface

Constructor

new

  my $search = PGXN::API::Searcher->new('/path/to/pgxn/api/root');

Constructs a PGXN::API::Searcher object, pointing it to a valid PGXN::API root directory.

Accessors

doc_root

  my $doc_root = $search->doc_root;

Returns the path to the document root passed to new().

parsers

  my $doc_parser = $search->parsers->{docs};

Returns a hash reference of search query parsers. The keys are the names of the indexes, and the values are Lucy::Search::QueryParser objects.

Instance Method

  my $results = $search->search( in => 'docs', query => $q );

Queries the specified index and returns a hash reference with the results. The parameters supported in the hash reference second argument are:

query

The search query. See Lucy::Search::QueryParser for the supported syntax of the query. Required.

in

The name of the search index in which to run the query. The default is "docs". The possible values are covered below.

offset

How many hits to skip before showing results. Defaults to 0.

limit

Maximum number of hits to return. Defaults to 50 and may not be greater than 1024.

The results will be returned as a hash with the following keys:

query

The query string. Same value as the query parameter.

limit

Maximum number of records returned. Same as the limit parameter unless it exceeds 1024, in which case it will be the default value, 50.

offset

The number of hits skipped.

count

The total count of hits, without regard to limit or offset. Use for laying out pagination links.

hits

An array of hash references. These constitute the search results. The keys in the hashes depend on which index was searched. See below for that information.

The structure of the hits hash reference depends on which index is specified via the index parameter. The possible values are:

docs

Full text indexing of PGXN documentation. The hits hashes will have the following keys:

title

The document title.

abstract

The document abstract.

excerpt

An excerpt from the document with the search keywords highlighted in <<strong> > tags.

dist

The name of the distribution in which the document is found.

version

The version of the distribution in which the document is found.

docpath

The path to the document within the distribution.

date

The distribution date.

user

The nickname of the user who created the distribution.

user_name

The full name of the user who created the distribution.

dists

Full text search of PGXN distributions. The hits hashes will have the following keys:

name

The name of the distribution.

version

The distribution version.

excerpt

An excerpt from the distribution with the search keywords highlighted in <strong> tags.

abstract

The distribution abstract.

date

The distribution date.

user

The nickname of the user who created the distribution.

user_name

The full name of the user who created the distribution.

extensions

Full text search of PGXN extensions. The hits hashes will have the following keys:

name

The name of the extension.

excerpt

An excerpt from the extension with the search keywords highlighted in <strong> tags.

abstract

The extension abstract.

dist

The name of the distribution in which the extension is found.

version

The version of the distribution in which the extension is found.

docpath

The path to the extension's documentation within the distribution. This is the same format as used for the "docpath" key in docs results, and as used by the "htmldoc" URI template.

date

The distribution date.

user

The nickname of the user who created the distribution.

user_name

The full name of the user who created the distribution.

users

Full text search of PGXN users. The hits hashes will have the following keys:

user

The user's nickname.

name

The user's full name.

uri

The user's URI

excerpt

An excerpt from the user with the search keywords highlighted in <<strong> > tags.

tags

Full text search of PGXN tags. The hits hashes will have the following keys:

name

The tag name.

Support

This module is stored in an open GitHub repository. Feel free to fork and contribute!

Please file bug reports via GitHub Issues or by sending mail to bug-PGXN-API-Searcher@rt.cpan.org.

See Also

PGXN::Manager

The heart of any PGXN network, PGXN::Manager manages distribution uploads and mirror maintenance. You'll want to look at it if you plan to build your own network.

WWW::PGXN

A Perl interface over a PGXN mirror or API. Able to read the mirror or API via HTTP or from the local file system. Use PGXN::API::Searcher when the specified API URI maps to the local file system.

PGXN::Site

A layer over the PGXN API providing a nicely-formatted Web site for folks to perform full text searches, read documentation, or browse information about users, distributions, tags, and extensions.

PGXN::API

Creates the full text indexes used by PGXN::API::Searcher>. Also uses PGXN::API::Searcher to manage /search HTTP requests.

Author

David E. Wheeler <david.wheeler@pgexperts.com>

Copyright and License

Copyright (c) 2011 David E. Wheeler.

This module is free software; you can redistribute it and/or modify it under the PostgreSQL License.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.

In no event shall David E. Wheeler be liable to any party for direct, indirect, special, incidental, or consequential damages, including lost profits, arising out of the use of this software and its documentation, even if David E. Wheeler has been advised of the possibility of such damage.

David E. Wheeler specifically disclaims any warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The software provided hereunder is on an "as is" basis, and David E. Wheeler has no obligations to provide maintenance, support, updates, enhancements, or modifications.