File Coverage

blib/lib/Net/Google.pm

Criterion	Covered	Total	%
statement	35	42	83.3
branch	4	10	40.0
condition			n/a
subroutine	9	11	81.8
pod	5	7	71.4
total	53	70	75.7

{

=head1 NAME

Net::Google - simple OOP-ish interface to the Google SOAP API

=head1 SYNOPSIS

 use Net::Google;
 use constant LOCAL_GOOGLE_KEY => "********************************";

 my $google = Net::Google->new(key=>LOCAL_GOOGLE_KEY);
 my $search = $google->search();

 # Search interface

 $search->query(qw(aaron straup cope));
 $search->lr(qw(en fr));
 $search->starts_at(5);
 $search->max_results(15);

 map { print $_->title()."\n"; } @{$search->results()};

 # or...

 foreach my $r (@{$search->response()}) {
   print "Search time :".$r->searchTime()."\n";

   # returns an array ref of Result objects
   # the same as the $search->results() method
   map { print $_->URL()."\n"; } @{$r->resultElements()};
 }

 # Spelling interface

 print $google->spelling(phrase=>"muntreal qwebec")->suggest(),"\n";

 # Cache interface

 my $cache = $google->cache(url=>"http://search.cpan.org/recent");
 print $cache->get();

=head1 DESCRIPTION

Provides a simple OOP-ish interface to the Google SOAP API

=head1 ENCODING

According to the Google API docs :

 "In order to support searching documents in multiple languages
 and character encodings the Google Web APIs perform all requests
 and responses in the UTF-8 encoding. The parameters  and
  are required in client requests but their values are ignored.
 Clients should encode all request data in UTF-8 and should expect
 results to be in UTF-8."

(This package takes care of setting both parameters in requests.)

=cut

use strict;

package Net::Google;
use base qw (Net::Google::tool);

use Carp;

$Net::Google::VERSION     = '1.0';

$Net::Google::QUERY_LIMIT = 1000;
$Net::Google::KEY_QUERIES = {};

=head1 PACKAGE METHODS

=cut

=head2 __PACKAGE__->new(\%args)

Valid arguments are :

=over 4

=item *

B

I. A Google API key.

=item *

B

I. A URL for proxy-ing HTTP requests.

=item *

B

Valid options are:

=over 4

=item *

I

If true prints debugging information returned by SOAP::Lite
to STDERR

=item *

I.

Your own subroutine for munging the debugging information
returned by SOAP::Lite.

=back

=back

Note that prior to version 0.60, arguments were not passed
by reference. Versions >= 0.60 are backwards compatible.

Returns an object. Woot!

=cut

sub new {
  my $pkg = shift;

  my $self = {};
  bless $self,$pkg;

  if (! $self->init(@_)) {
    return undef;
  }

  return $self;
}

sub init {
  my $self = shift;
  my $args = (ref($_[0]) eq "HASH") ? shift : {@_};

  $self->{'_debug'}      = $args->{'debug'};
  $self->{'_key'}        = $args->{'key'};
  $self->{'_http_proxy'} = $args->{'http_proxy'};

  # Do *not* call parent
  # class' init() method.

  return 1;
}

=head1 OBJECT METHODS

=cut

=head2 $obj->key($string)

Get/set the Google API key for this object.

=cut

# Defined in Net::Google::tool

=head2 $obj->http_proxy($url)

Get/set the HTTP proxy for this object.

Returns a string.

=cut

# Note we subclass the method normally inherited
# from ::tool.pm. Since this is just a wrapper
# module, we don't have a SOAP thingy to actually
# set the proxy for so we'll just cache it for
# later.

sub http_proxy {
  my $self = shift;
  my $uri  = shift;

  if ($uri) {
    $self->{'_http_proxy'} = $uri;
  }

  return $self->{'_http_proxy'};
}

=head2 $obj->search(\%args)

Valid arguments are :

=over 4

=item *

B

I. A Google API key.

If none is provided then the key passed to the parent
I object will be used.

=item *

B

I. First result number to display.

Default is 0.

=item *

B

I. Number of results to return.

Default is 10.

=item *

B

I or I. Language restrictions.

=item *

B

I.

=item *

B

I.

=item *

B

I. A URL for proxy-ing HTTP requests.


=item *

B

Valid options are:

=over 4

=item *

I

If true prints debugging information returned by SOAP::Lite
to STDERR

=item *

I

Your own subroutine for munging the debugging information
returned by SOAP::Lite.

=back

=back

Note that prior to version 0.60, arguments were not passed
by reference. Versions >= 0.60 are backwards compatible.

Returns a I object. Woot!

Returns undef if there was an error.

=cut

sub search {
  my $self = shift;
  require Net::Google::Search;
  return Net::Google::Search->new($self->_parse_args(@_));
}

=head2 $obj->spelling(\%args)

Valid arguments are:

=over 4

=item *

B

I. A Google API key.

If none is provided then the key passed to the parent
I object will be used.

=item *

B

I or I.

=item *

B

I. A URL for proxy-ing HTTP requests.

=item *

B

=over 4

=item *

B

Prints debugging information returned by SOAP::Lite to STDERR

=item *

B

Your own subroutine for munging the debugging information
returned by SOAP::Lite.

=back

If no option is defined then the debug argument passed to the parent
I object will be used.

=back

Note that prior to version 0.60, arguments were not passed
by reference. Versions >= 0.60 are backwards compatible.

Returns a I object. Woot!

Returns undef if there was an error.

=cut

sub spelling {
  my $self = shift;
  require Net::Google::Spelling;
  return Net::Google::Spelling->new($self->_parse_args(@_));
}

# Small things are good because you can
# fit them in your hand *and* your mouth.

sub speling { return shift->spelling(@_); }

=head2 $obj->cache(\%args)

Valid arguments are :

=over 4

=item *

B

String. Google API key.

If none is provided then the key passed to the parent I
object will be used.

=item *

B

I

=item *

B

I. A URL for proxy-ing HTTP requests.

=item *

B

Valid options are:

=over 4

=item *

I

If true, prints debugging information returned by SOAP::Lite
to STDERR

=item *

I

Your own subroutine for munging the debugging information
returned by SOAP::Lite.

=back

If no option is defined then the debug argument passed to the parent
I object will be used.

=back

Note that prior to version 0.60, arguments were not passed
by reference. Versions >= 0.60 are backwards compatible.

Returns a I object. Woot!

Returns undef if there was an error.

=cut

sub cache {
  my $self = shift;
  require Net::Google::Cache;
  return Net::Google::Cache->new($self->_parse_args(@_));
}

=head2 $obj->queries_exhausted()

Returns true or false depending on whether or not the current in-memory
B has exhausted the Google API 1000 query limit.

=cut

# Defined in Net::Google::tool

#

sub _parse_args {
  my $self = shift;
  my $args = (ref($_[0]) eq "HASH") ? shift : {@_};

  foreach my $el ("key","debug","http_proxy") {
    next if (defined($args->{$el}));
    $args->{$el} = $self->{"_$el"};
  }

  return $args;
}

=head1 VERSION

1.0

=head1 DATE

$Date: 2005/03/26 20:49:03 $

=head1 AUTHOR

Aaron Straup Cope

=head1 CONTRIBUTORS

Marc Hedlund

=head1 SEE ALSO

http://www.google.com/apis

L

L

L

L

L

http://aaronland.info/weblog/archive/4231

=head1 TO DO

=over 4

=item *

Tickle the tests so that they will pass on systems without
Test::More.

=item *

Add tests for filters.

=item *

Add some sort of functionality for managing multiple keys.
Sort of like what is describe here :

http://aaronland.net/weblog/archive/4204

This will probably happen around the time Hell freezes over
so if you think you can do it faster, go nuts.

=back

=head1 BUGS

Please report all bugs via http://rt.cpan.org

=head1 LICENSE

Copyright (c) 2002-2005, Aaron Straup Cope. All Rights Reserved.

This is free software, you may use it and distribute it under the
same terms as Perl itself.

=cut

return 1;

}