root/WWW-OpenSearch/branches/WWW-OpenSearch-rewrite/lib/WWW/OpenSearch.pm

Revision 1887 (checked in by bricas, 14 years ago)

added option to override the user agent

Line 
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.06_02';
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         my %form = $url->query_form;
168         $url->query_form( { } );
169         $response = $self->agent->post( $url, \%form );
170     }
171     else {
172         $response = $self->agent->$method( $url );
173     }
174    
175     return WWW::OpenSearch::Response->new( $self, $response );   
176 }
177
178 1;
Note: See TracBrowser for help on using the browser.