Imported Upstream version 0.0602

[libwww-opensearch-perl.git] / lib / WWW / OpenSearch.pm

diff --git a/lib/WWW/OpenSearch.pm b/lib/WWW/OpenSearch.pm
new file mode 100644 (file)
index 0000000..5985929
--- /dev/null
+++ b/lib/WWW/OpenSearch.pm
@@ -0,0 +1,176 @@
+package WWW::OpenSearch;\r
+\r
+use strict;\r
+use warnings;\r
+\r
+use base qw( Class::Accessor::Fast );\r
+\r
+use Carp;\r
+use WWW::OpenSearch::Response;\r
+use WWW::OpenSearch::Description;\r
+use Encode qw( _utf8_off ); \r
+\r
+__PACKAGE__->mk_accessors( qw( description_url agent description ) );\r
+\r
+our $VERSION = '0.06_02';\r
+\r
+=head1 NAME\r
+\r
+WWW::OpenSearch - Search A9 OpenSearch compatible engines\r
+\r
+=head1 SYNOPSIS\r
+\r
+    use WWW::OpenSearch;\r
+    \r
+    my $url = "http://bulkfeeds.net/opensearch.xml";\r
+    my $engine = WWW::OpenSearch->new($url);\r
+    \r
+    my $name = $engine->description->ShortName;\r
+    my $tags = $engine->description->Tags;\r
+    \r
+    # Perform search for "iPod"\r
+    my $response = $engine->search("iPod");\r
+    for my $item (@{$response->feed->items}) {\r
+        print $item->{description};\r
+    }\r
+    \r
+    # Retrieve the next page of results\r
+    my $next_page = $response->next_page;\r
+    for my $item (@{$next_page->feed->items}) {\r
+        print $item->{description};\r
+    }\r
+\r
+=head1 DESCRIPTION\r
+\r
+WWW::OpenSearch is a module to search A9's OpenSearch compatible search engines. See http://opensearch.a9.com/ for details.\r
+\r
+=head1 CONSTRUCTOR\r
+\r
+=head2 new( $url [, $useragent] )\r
+\r
+Constructs a new instance of WWW::OpenSearch using the given\r
+URL as the location of the engine's OpenSearch Description\r
+document (retrievable via the description_url accessor). Pass any
+LWP::UserAgent compatible object if you wish to override the default
+agent.\r
+\r
+=head1 METHODS\r
+\r
+=head2 fetch_description( [ $url ] )\r
+\r
+Fetches the OpenSearch Descsription found either at the given URL\r
+or at the URL specified by the description_url accessor. Fetched\r
+description may be accessed via the description accessor.\r
+\r
+=head2 search( $query [, \%params] )\r
+\r
+Searches the engine for the given query using the given \r
+search parameters. Valid search parameters include:\r
+\r
+=over 4\r
+\r
+=item * startPage\r
+\r
+=item * totalResults\r
+\r
+=item * startIndex\r
+\r
+=item * itemsPerPage\r
+\r
+=back\r
+\r
+See http://opensearch.a9.com/spec/1.1/response/#elements for details.\r
+\r
+=head2 do_search( $url [, $method] )\r
+\r
+Performs a request for the given URL and returns a\r
+WWW::OpenSearch::Response object. Method defaults to 'GET'.\r
+\r
+=head1 ACCESSORS\r
+\r
+=head2 description_url( [$description_url] )\r
+\r
+=head2 agent( [$agent] )\r
+\r
+=head2 description( [$description] )\r
+\r
+=head1 AUTHOR\r
+\r
+=over 4\r
+\r
+=item * Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>\r
+\r
+=item * Brian Cassidy E<lt>bricas@cpan.orgE<gt>\r
+\r
+=back\r
+\r
+=head1 COPYRIGHT AND LICENSE\r
+\r
+Copyright 2006 by Tatsuhiko Miyagawa and Brian Cassidy\r
+\r
+This library is free software; you can redistribute it and/or modify\r
+it under the same terms as Perl itself. \r
+\r
+=cut\r
+\r
+sub new {\r
+    my( $class, $url, $agent ) = @_;\r
+    \r
+    croak( "No OpenSearch Description url provided" ) unless $url;\r
+    \r
+    my $self = $class->SUPER::new;
+
+    unless( $agent ) {
+        require LWP::UserAgent;
+        $agent = LWP::UserAgent->new( agent => join( '/', ref $self, $VERSION ) );
+    }
+\r
+    $self->description_url( $url );\r
+    $self->agent( $agent );\r
+\r
+    $self->fetch_description;\r
+    \r
+    return $self;\r
+}\r
+\r
+sub fetch_description {\r
+    my( $self, $url ) = @_;\r
+    $url ||= $self->description_url;\r
+    $self->description_url( $url );\r
+    my $response = $self->agent->get( $url );\r
+    \r
+    unless( $response->is_success ) {\r
+        croak "Error while fetching $url: " . $response->status_line;\r
+    }\r
+\r
+    $self->description( WWW::OpenSearch::Description->new( $response->content ) );\r
+}\r
+\r
+sub search {\r
+    my( $self, $query, $params ) = @_;\r
+\r
+    $params ||= { };\r
+    $params->{ searchTerms } = $query;\r
+    _utf8_off( $params->{ searchTerms } ); \r
+    \r
+    my $url = $self->description->get_best_url;\r
+    return $self->do_search( $url->prepare_query( $params ), $url->method );\r
+}\r
+\r
+sub do_search {\r
+    my( $self, $url, $method ) = @_;\r
+    \r
+    $method = lc( $method ) || 'get';\r
+    \r
+    my $response;\r
+    if( $method eq 'post' ) {\r
+        $response = $self->agent->post( @$url );\r
+    }\r
+    else {\r
+        $response = $self->agent->$method( $url );\r
+    }\r
+    \r
+    return WWW::OpenSearch::Response->new( $self, $response );    \r
+}\r
+\r
+1;\r