Unix Man page/Perldoc/Info page, English-Chinese Dictionary,
Chinese-English Dictionary
Unix Man page/Perldoc/Info page, English-Chinese Dictionary,
Chinese-English Dictionary
Yahoo::Search::ResponsUsermContributed Perl DocumeYahoo::Search::Response(3pm)
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.)
Package Use
You never need to "use" this package directly -- it is loaded automati-
cally by Yahoo::Search.
Object Creation
"Response" objects are created by the "Fetch()" method of a "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(...);
Methods
A "Response" object has the following 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 sepa-
rator 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 sepa-
rator 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 represent-
ing 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:
* On a per "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;
}
}
* 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;
}
}
* By creating a query via a search-engine object created with
AutoContinue => 1
as with this example:
use Yahoo::Search;
##
## WARNING: DANGEROUS DANGEROUS DANGEROUS
##
my $SearchEngine = Yahoo::Search->new(AutoContinue => 1);
if (my $Response = $SearchEngine->Query(Doc => 'Britney')) {
while (my $Result = $Response->NextResult) {
printf "%d: %s\n", $Result->I, $Result->Url;
}
}
* By creating a query when Yahoo::Search had been loaded via:
use Yahoo::Search AutoContinue => 1;
as with this example:
use Yahoo::Search AutoContinue => 1;
##
## WARNING: DANGEROUS DANGEROUS DANGEROUS
##
if (my $Response = Yahoo::Search->Query(Doc => 'Britney')) {
while (my $Result = $Response->NextResult) {
printf "%d: %s\n", $Result->I, $Result->Url;
}
}
All these examples are dangerous because they loop through results,
fetching more and more, until either all results that Yahoo! has
for the query at hand have been fetched, or the Yahoo! Search
server access limits have been reached and further access is
denied. So, be sure to rate-limit the accesses, or explicitly break
out of the loop at some appropriate point.
$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.
Copyright
Copyright (C) Yahoo! Inc
Author
Copyright (C) 2005 Yahoo! Inc.
$Id: Response.pm 3 2005-01-28 04:29:54Z jfriedl $
perl v5.8.7 2005-03-31 Yahoo::Search::Response(3pm)
|