NAME

VERSION

Package Use

Object Creation

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

or by shortcuts to the same, such as:

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

Methods

$Response->Count()

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

$Response->FirstOrdinal([ separator ])

Returns the index of the first "Result" object (e.g. the "30" of results 30 through 40 out of 5,329). This is the same as the "Start" arg of the "Request" that generated this "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.

$Response->CountAvail([ separator ])

Returns an approximate number of total search results available, were you to ask for them all (e.g. the "5329" of the 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.

$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.

(Not appropriate for Spell and Related search results)

$Response->Terms()

(Appropriate for Spell and Related search results)

Returns a list of text terms.

$Response->Results()

Returns a list of Yahoo::Search::Result "Result" objects representing all the results held in this "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 Spell and Related searches.

$Response->NextResult(options)

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

The first time "NextResult" is called for a given "Response" object, it returns the "Result" object for the first result in the set. Returns subsequent "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 "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;
     }
 }
    

Auto-Continuation

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

This can be convenient, but can be very dangerous, as it means that a loop which calls "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:

$Response->Reset()

Rests the iterator so that the next "NextResult" returns the first of the "Response" object's "Result" objects.

$Response->Request()

Returns the "Request" object from which this "Response" object was derived.

$Response->NextRequest()

Returns a "Request" object which will fetch the subsequent set of results (e.g. if the current "Response" object represents the first 10 query results, "NextRequest()" returns a "Request" object that represents a query for the next 10 results.)

Returns nothing if there were no results in the current "Response" object (thereby eliminating the possibility of there being a next result set). On error, sets $@ and returns nothing.

$Response->NextResponse()

Like "NextRequest", but goes ahead and calls the "Request" object's "Fetch" method to return the "Result" object for the next set of results.

$Response->Uri()

Returns the "URI::http" object that was fetched to create this response. It is the same as:

  $Response->Request->Uri()
    

$Response->Url()

Returns the url that was fetched to create this response. It is the same as:

  $Response->Request->Url()
    

$Response->RawXml()

Returns a string holding the raw xml returned from the Yahoo! Search servers.

$Response->MapUrl()

Valid only for a Local search, returns a url to a map showing all results. (This is the same as each "Result" object's "AllMapUrl" method.)

$Response->RelatedRequest

$Response->RelatedResponse

Perform a Related request for search terms related to the query phrase of the current request, returning the new "Request" or "Response" object, respectively.

Both return nothing if the current request is already for a Related search.

For example:

  print "Did you mean ", join(" or ", $Response->RelatedResponse->Terms()), "?";
    

$Response->SpellRequest

$Response->SpellResponse

Perform a Spell request for a search term that may reflect proper spelling of the query phrase of the current request, returning the new "Request" or "Response" object, respectively.

Both return nothing if the current request is already for a Spell search.

Author