1 package WWW::OpenSearch;
\r
6 use base qw( Class::Accessor::Fast );
\r
9 use WWW::OpenSearch::Response;
\r
10 use WWW::OpenSearch::Description;
\r
11 use Encode qw( _utf8_off );
\r
13 __PACKAGE__->mk_accessors( qw( description_url agent description ) );
\r
15 our $VERSION = '0.06_02';
\r
19 WWW::OpenSearch - Search A9 OpenSearch compatible engines
\r
23 use WWW::OpenSearch;
\r
25 my $url = "http://bulkfeeds.net/opensearch.xml";
\r
26 my $engine = WWW::OpenSearch->new($url);
\r
28 my $name = $engine->description->ShortName;
\r
29 my $tags = $engine->description->Tags;
\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
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
45 WWW::OpenSearch is a module to search A9's OpenSearch compatible search engines. See http://opensearch.a9.com/ for details.
\r
49 =head2 new( $url [, $useragent] )
\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
59 =head2 fetch_description( [ $url ] )
\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
65 =head2 search( $query [, \%params] )
\r
67 Searches the engine for the given query using the given
\r
68 search parameters. Valid search parameters include:
\r
74 =item * totalResults
\r
78 =item * itemsPerPage
\r
82 See http://opensearch.a9.com/spec/1.1/response/#elements for details.
\r
84 =head2 do_search( $url [, $method] )
\r
86 Performs a request for the given URL and returns a
\r
87 WWW::OpenSearch::Response object. Method defaults to 'GET'.
\r
91 =head2 description_url( [$description_url] )
\r
93 =head2 agent( [$agent] )
\r
95 =head2 description( [$description] )
\r
101 =item * Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
\r
103 =item * Brian Cassidy E<lt>bricas@cpan.orgE<gt>
\r
107 =head1 COPYRIGHT AND LICENSE
\r
109 Copyright 2006 by Tatsuhiko Miyagawa and Brian Cassidy
\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
117 my( $class, $url, $agent ) = @_;
\r
119 croak( "No OpenSearch Description url provided" ) unless $url;
\r
121 my $self = $class->SUPER::new;
124 require LWP::UserAgent;
125 $agent = LWP::UserAgent->new( agent => join( '/', ref $self, $VERSION ) );
128 $self->description_url( $url );
\r
129 $self->agent( $agent );
\r
131 $self->fetch_description;
\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
142 unless( $response->is_success ) {
\r
143 croak "Error while fetching $url: " . $response->status_line;
\r
146 $self->description( WWW::OpenSearch::Description->new( $response->content ) );
\r
150 my( $self, $query, $params ) = @_;
\r
153 $params->{ searchTerms } = $query;
\r
154 _utf8_off( $params->{ searchTerms } );
\r
156 my $url = $self->description->get_best_url;
\r
157 return $self->do_search( $url->prepare_query( $params ), $url->method );
\r
161 my( $self, $url, $method ) = @_;
\r
163 $method = lc( $method ) || 'get';
\r
166 if( $method eq 'post' ) {
\r
167 $response = $self->agent->post( @$url );
\r
170 $response = $self->agent->$method( $url );
\r
173 return WWW::OpenSearch::Response->new( $self, $response );
\r