root/WWW-OpenSearch/trunk/lib/WWW/OpenSearch.pm

Revision 2188 (checked in by bricas, 13 years ago)

update changes. bump version

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::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.11';
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 =over 4
101
102 =item * Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
103
104 =item * Brian Cassidy E<lt>bricas@cpan.orgE<gt>
105
106 =back
107
108 =head1 COPYRIGHT AND LICENSE
109
110 Copyright 2007 by Tatsuhiko Miyagawa and Brian Cassidy
111
112 This library is free software; you can redistribute it and/or modify
113 it under the same terms as Perl itself.
114
115 =cut
116
117 sub new {
118     my( $class, $url ) = @_;
119    
120     croak( "No OpenSearch Description url provided" ) unless $url;
121    
122     my $self = $class->SUPER::new;
123
124     $self->description_url( $url );
125     $self->agent( WWW::OpenSearch::Agent->new() );
126
127     $self->fetch_description;
128    
129     return $self;
130 }
131
132 sub fetch_description {
133     my( $self, $url ) = @_;
134     $url ||= $self->description_url;
135     $self->description_url( $url );
136     my $response = $self->agent->get( $url );
137    
138     unless( $response->is_success ) {
139         croak "Error while fetching $url: " . $response->status_line;
140     }
141
142     $self->description( WWW::OpenSearch::Description->new( $response->content ) );
143 }
144
145 sub search {
146     my( $self, $query, $params, $url ) = @_;
147
148     $params ||= { };
149     $params->{ searchTerms } = $query;
150     Encode::_utf8_off( $params->{ searchTerms } );
151    
152     $url ||= $self->description->get_best_url;
153     return $self->agent->search( WWW::OpenSearch::Request->new( $url, $params ) );
154 }
155
156 1;
Note: See TracBrowser for help on using the browser.