lib/WWW/OpenSearch.pm

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