lib/WWW/OpenSearch.pm

   1 package WWW::OpenSearch;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw( Class::Accessor::Fast );
   7
   8 use Carp;
   9 use WWW::OpenSearch::Agent;
  10 use WWW::OpenSearch::Request;
  11 use WWW::OpenSearch::Description;
  12
  13 use Encode ();
  14
  15 __PACKAGE__->mk_accessors( qw( description_url agent description ) );
  16
  17 our $VERSION = '0.15';
  18
  19 =head1 NAME
  20
  21 WWW::OpenSearch - Search A9 OpenSearch compatible engines
  22
  23 =head1 SYNOPSIS
  24
  25     use WWW::OpenSearch;
  26
  27     my $url = "http://bulkfeeds.net/opensearch.xml";
  28     my $engine = WWW::OpenSearch->new($url);
  29
  30     my $name = $engine->description->ShortName;
  31     my $tags = $engine->description->Tags;
  32
  33     # Perform search for "iPod"
  34     my $response = $engine->search("iPod");
  35     for my $item (@{$response->feed->items}) {
  36         print $item->{description};
  37     }
  38
  39     # Retrieve the next page of results
  40     my $next_page = $response->next_page;
  41     for my $item (@{$next_page->feed->items}) {
  42         print $item->{description};
  43     }
  44
  45 =head1 DESCRIPTION
  46
  47 WWW::OpenSearch is a module to search A9's OpenSearch compatible search
  48 engines. See http://opensearch.a9.com/ for details.
  49
  50 =head1 CONSTRUCTOR
  51
  52 =head2 new( $url )
  53
  54 Constructs a new instance of WWW::OpenSearch using the given
  55 URL as the location of the engine's OpenSearch Description
  56 document (retrievable via the description_url accessor).
  57
  58 =head1 METHODS
  59
  60 =head2 fetch_description( [ $url ] )
  61
  62 Fetches the OpenSearch Descsription found either at the given URL
  63 or at the URL specified by the description_url accessor. Fetched
  64 description may be accessed via the description accessor.
  65
  66 =head2 search( $query [, \%params] )
  67
  68 Searches the engine for the given query using the given
  69 search parameters. Valid search parameters include:
  70
  71 =over 4
  72
  73 =item * startPage
  74
  75 =item * totalResults
  76
  77 =item * startIndex
  78
  79 =item * itemsPerPage
  80
  81 =back
  82
  83 See http://opensearch.a9.com/spec/1.1/response/#elements for details.
  84
  85 =head2 do_search( $url [, $method] )
  86
  87 Performs a request for the given URL and returns a
  88 WWW::OpenSearch::Response object. Method defaults to 'GET'.
  89
  90 =head1 ACCESSORS
  91
  92 =head2 description_url( [$description_url] )
  93
  94 =head2 agent( [$agent] )
  95
  96 =head2 description( [$description] )
  97
  98 =head1 AUTHOR
  99
 100 Brian Cassidy E<lt>bricas@cpan.orgE<gt>
 101
 102 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
 103
 104 =head1 COPYRIGHT AND LICENSE
 105
 106 Copyright 2005-2009 by Tatsuhiko Miyagawa and Brian Cassidy
 107
 108 This library is free software; you can redistribute it and/or modify
 109 it under the same terms as Perl itself.
 110
 111 =cut
 112
 113 sub new {
 114     my ( $class, $url ) = @_;
 115
 116     croak( "No OpenSearch Description url provided" ) unless $url;
 117
 118     my $self = $class->SUPER::new;
 119
 120     $self->description_url( $url );
 121     $self->agent( WWW::OpenSearch::Agent->new() );
 122
 123     $self->fetch_description;
 124
 125     return $self;
 126 }
 127
 128 sub fetch_description {
 129     my ( $self, $url ) = @_;
 130     $url ||= $self->description_url;
 131     $self->description_url( $url );
 132     my $response = $self->agent->get( $url );
 133
 134     unless ( $response->is_success ) {
 135         croak "Error while fetching $url: " . $response->status_line;
 136     }
 137
 138     $self->description(
 139         WWW::OpenSearch::Description->new( $response->content ) );
 140 }
 141
 142 sub search {
 143     my ( $self, $query, $params, $url ) = @_;
 144
 145     $params ||= {};
 146     $params->{ searchTerms } = $query;
 147     Encode::_utf8_off( $params->{ searchTerms } );
 148
 149     $url ||= $self->description->get_best_url;
 150     return $self->agent->search(
 151         WWW::OpenSearch::Request->new( $url, $params ) );
 152 }
 153
 154 1;