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