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

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

patch from ian beckwith to fix pod coverage

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