response.pm

yahoo api,包括各版本的

package Yahoo::Search::Response;
use strict;
use Yahoo::Search::Result;

our $VERSION = "20070320.002"; # just to make CPAN happy

=head1 NAME

Yahoo::Search::Response -- Container object for the result set of one query
to the Yahoo! Search API.
(This package is included in, and automatically loaded by, the Yahoo::Search package.)

=head1 Package Use

You never need to C<use> this package directly -- it is loaded
automatically by Yahoo::Search.

=head1 Object Creation

C<Response> objects are created by the C<Fetch()> method of a C<Request>
(Yahoo::Search::Request) object, e.g. by

  my $Response = Yahoo::Search->new(...)->Request()->Fetch();

or by shortcuts to the same, such as:

  my $Response = Yahoo::Search->Query(...);

=cut

##
## Called from Request.pm after grokking the xml returned as the results of
## a specific Request.
##
sub new
{
    my $class = shift;
    my $Response = shift; # hashref of info

    ## We have the data; now bless it
    bless $Response, $class;

    ## Initialize iterator for NextResult() method
    $Response->{_NextIterator} = 0;

    ## But do a bit of cleanup and other preparation....
    if (not $Response->{firstResultPosition}) {
        ## Y! server bug -- this is sometimes empty
        $Response->{firstResultPosition} = 1;
    }

    ##
    ## Fix up and bless each internal "Result" item -- turn into a Result
    ## object. Set the ordinal to support the i() and I() methods.
    ##
    for (my $i = 0; $i < @{$Response->{Result}}; $i++)
    {
        my $Result = $Response->{Result}->[$i];

        $Result->{_ResponseOrdinal} = $i;
        $Result->{_Response} = $Response;

        ##
        ## Something like
        ##     <Channels></Channels>
        ## ends up being a ref to an empty hash. We'll remove those.
        ##
        for my $key (keys %$Result)
        {
            if (ref($Result->{$key}) eq "HASH"
                and
                not keys %{$Result->{$key}})
            {
                delete $Result->{$key};
            }
        }

        bless $Result, "Yahoo::Search::Result";
    }

    return $Response;
}


=head1 Methods

A C<Response> object has the following methods:

=over 4

=cut


###########################################################################

=item $Response->Count()

Returns the number of C<Result> objects available in this C<Response>. See
Yahoo::Search::Result for details on C<Result> objects.

=cut

sub Count
{
    my $Response = shift; #self;
    return scalar @{$Response->{Result}};
}




###########################################################################
sub _commaize($$)
{
    my $num = shift;
    my $comma = shift; # "," (English), "." (European), undef.....

    if ($comma) {
        $num =~ s/(?<=\d)(?=(?:\d\d\d)+$)/$comma/g;
    }
    return $num;
}
###########################################################################

=item $Response->FirstOrdinal([ I<separator> ])

Returns the index of the first C<Result> object (e.g. the "30" of I<results
30 through 40 out of 5,329>). This is the same as the C<Start> arg of the
C<Request> that generated this C<Response>.

If an optional argument is given and is true, it is used as a separator
every three digits. In the US, one would use

   $Response->FirstOrdinal(',')

to return, say, "1,230" instead of the "1230" that

   $Response->FirstOrdinal()

might return.

=cut

sub FirstOrdinal
{
    my $Response = shift; #self;
    my $Comma = shift; # optional

    ## do the '-1' to convert from Y!'s 1-based system to our 0-based system
    return _commaize(($Response->{firstResultPosition}||0) - 1, $Comma);
}



###########################################################################

=item $Response->CountAvail([ I<separator> ])

Returns an approximate number of total search results available, were you
to ask for them all (e.g. the "5329" of the I<results 30 through 40 out of
5329>).

If an optional argument is given and is true, it is used as a separator
every three digits. In the US, one would use

   $Response->CountAvail(',')

to return, say, "5,329" instead of the "5329" that

   $Response->CountAvail()

might return.

=cut

sub CountAvail
{
    my $Response = shift; #self;
    my $Comma = shift; # optional
    return _commaize($Response->{totalResultsAvailable} || 0, $Comma)
}



###########################################################################

=item $Response->Links()

Returns a list of links from the response (one link per result):

  use Yahoo::Search;
  if (my $Response = Yahoo::Search->Query(Doc => 'Britney'))
  {
      for my $link ($Response->Links) {
          print "<br>$link\n";
      }
  }

This prints one

  <br><a href="...">title of the link</a>

line per result returned from the query.

(I<Not appropriate for B<Spell> and B<Related> search results>)

=cut

sub Links
{
    my $Response = shift; #self;
    return map { $_->Link } $Response->Results;
}




###########################################################################

=item $Response->Terms()

(I<Appropriate for B<Spell> and B<Related> search results>)

Returns a list of text terms.

=cut

sub Terms
{
    my $Response = shift; #self;
    return map { $_->Terms } $Response->Results;
}




###########################################################################

=item $Response->Results()

Returns a list of Yahoo::Search::Result C<Result> objects representing
all the results held in this C<Response>. For example:

  use Yahoo::Search;
  if (my $Response = Yahoo::Search->Query(Doc => 'Britney'))
  {
      for my $Result ($Response->Results) {
         printf "%d: %s\n", $Result->I, $Result->Url;
      }
  }

This is not valid for I<Spell> and I<Related> searches.

=cut

sub Results
{
    my $Response = shift; #self;
    return @{$Response->{Result}};
}




###########################################################################

=item $Response->NextResult(options)

Returns a C<Result> object, or nothing. (On error, returns nothing and sets
C<$@>.)

The first time C<NextResult> is called for a given C<Response> object, it
returns the C<Result> object for the first result in the set. Returns
subsequent C<Result> objects for subsequent calls, until there are none
left, at which point what is returned depends upon whether the
auto-continuation feature is turned on (more on that in a moment).

The following produces the same results as the C<Results()> example above:

 use Yahoo::Search;
 if (my $Response = Yahoo::Search->Query(Doc => 'Britney')) {
     while (my $Result = $Response->NextResult) {
         printf "%d: %s\n", $Result->I, $Result->Url;
     }
 }

B<Auto-Continuation>

If auto-continuation is turned on, then upon reaching the end of the result
set, C<NextResult> automatically fetches the next set of results and
returns I<its> first result.

This can be convenient, but B<can be very dangerous>, as it means that a
loop which calls C<NextResult>, unless otherwise exited, will fetch results
from Yahoo! until there are no more results for the query, or until you
have exhausted your access limits.

Auto-continuation can be turned on in several ways:

=over 3

=item *

On a per C<NextResult> basis by calling as

 $Response->NextResult(AutoContinue => 1)

as with this example

 use Yahoo::Search;
 ##
 ## WARNING:   DANGEROUS DANGEROUS DANGEROUS
 ##
 if (my $Response = Yahoo::Search->Query(Doc => 'Britney')) {
     while (my $Result = $Response->NextResult(AutoContinue => 1)) {
         printf "%d: %s\n", $Result->I, $Result->Url;
     }
 }


=item *

By using

  AutoContinue => 1

when creating the request (e.g. in a Yahoo::Search->Query call), as
with this example:

 use Yahoo::Search;
 ##
 ## WARNING:   DANGEROUS DANGEROUS DANGEROUS
 ##
 if (my $Response = Yahoo::Search->Query(Doc => 'Britney',
                                              AutoContinue => 1))
 {
     while (my $Result = $Response->NextResult) {
        printf "%d: %s\n", $Result->I, $Result->Url;
     }
 }

=item *

By creating a query via a search-engine object created with

  AutoContinue => 1

as with this example:

 use Yahoo::Search;
 ##