search.pm

Yahoo！search API. 用于搜索引擎接口

   Lat  =>  39.224079  # 39 deg 13 min 26.686 sec North
   Long => -98.541807, # 98 deg 32 min 30.506 sec West

(which happens to be the location of the "Medes Ranch" triangulation
station, upon which all country, state, etc., boundaries in North America
were originally based)

C<Street> is the street address, e.e. "701 First Ave". C<PostalCode> is a
US 5-digit or 9-digit ZIP code (e.g. "94089" or "94089-1234").

If C<Location> is provided, it supersedes the others. It should be a string
along the lines of "701 First Ave, Sunnyvale CA, 94089". The following forms
are recognized:

  city state
  city state zip
  zip
  street, city state
  street, city state zip
  street, zip

Searches that include a street address (either in the C<Location>, or if
C<Location> is empty, in C<Street>) provide for a more detailed epicenter
specification.

=item Radius

For B<Local> searches, indicates how wide an area around the epicenter to
search. The value is the radius of the search area, in miles. The default
radius depends on the search location (urban areas tend to have a smaller
default radius).

=item AutoContinue

A boolean (default off). If true, turns on the B<potentially dangerous>
auto-continuation, as described in the docs for C<NextResult> in
Yahoo::Search::Response.

=item Debug

C<Debug> is a string (defaults to an empty string). If the substring
"C<url>" is found anywhere in the string, the url of the Yahoo! request is
printed on stderr. If "C<xml>", the raw xml received is printed to stderr.
If "C<hash>", the raw Perl hash, as converted from the XML, is Data::Dump'd
to stderr.

Thus, to print all debugging, you'd set C<Debug> to a value such as "C<url
xml hash>".

=item PreRequestCallback

This is for debugging (I needed it for my own regression-test script). If
defined, it should be a code ref which accepts a single
Yahoo::Search::Request object argument. It is called just before Yahoo!'s
servers are contacted, and if it returns false, the call to Yahoo! is
aborted (be sure to set C<$@>).

=back

=head1 Class Hierarchy Details

The Y! Search API class system supports the following objects (all loaded
as needed via Yahoo::Search):

  Yahoo::Search
  Yahoo::Search::Request
  Yahoo::Search::Response
  Yahoo::Search::Result

Here is a summary of them:

=over 10

=item  Yahoo::Search

A "search engine" object which can hold user-specified default values for
search-query arguments. Often not used explicitly.

=item  Yahoo::Search::Request

An object which holds the information needed to make one search-query
request. Often not used explicitly.

=item  Yahoo::Search::Response

An object which holds the results of a query (including a bunch of
C<Result> objects).

=item  Yahoo::Search::Result

An object representing one query result (one image, web page, etc., as
appropriate to the original search space).

=back

=head1 "The Long Way", and Common Practice

The explicit way to perform a query and access the results is to first
create a "Search Engine" object:

  my $SearchEngine = Yahoo::Search->new();

Optionally, you can provide C<new> with key/value pairs as described in the
I<Query arguments> section above. Those values will then be available as
default values during subsequent request creation. (More on this later.)

You then use the search-engine object to create a request:

  my $Request = $SearchEngine->Request(Doc => Britney);

You then actually make the request, getting a response:

  my $Response = $Request->Fetch();

You can then access the set of C<Result> objects in a number of ways,
either all at once

  my @Results = $Response->Results();

or iteratively:


  while (my $Result = $Response->NextResult) {
               :
               :
  }

B<In Practice....>

In practice, one often does not need to go through all these steps
explicitly. The only reason to create a search-engine object, for example,
is to hold default overrides (to be made available to subsequent requests
made via the search-engine object). For example:

   use Yahoo::Search;
   my $SearchEngine = Yahoo::Search->new(AppId      => "Bobs Fish Mart",
                                         Count      => 25,
                                         AllowAdult => 1,
                                         PostalCode => 95014);

Now, calls to the various query functions (C<Query>, C<Results>) via this
C<$SearchEngine> will use these defaults (B<Image> searches, for example,
will be with C<AllowAdult> set to true, and B<Local> searches will be
centered at ZIP code 95014.) All will return up to 25 results.

In this example:

   my @Results = $SearchEngine->Results(Image => "Britney",
                                        Count => 20);

The query is made with C<AppId> as 'C<Bobs_Fish_Mart>' and C<AllowAdult>
true (both via C<$SearchEngine>), but C<Count> is 20 because explicit args
override the default in C<$SearchEngine>. The C<PostalCode> arg does not
apply too an B<Image> search, so the default provided from C<SearchEngine>
is not needed with this particular query.

B<Defaults on the 'use' line>

You can also provide the same defaults on the C<use> line. The following
example has the same result as the previous one:

   use Yahoo::Search AppId      => 'Bobs Fish Mart',
                     Count      => 25,
                     AllowAdult => 1,
                     PostalCode => 95014;

   my @Results = Yahoo::Search->Results(Image => "Britney",
                                        Count => 20);

=head1 Functions and Methods

Here, finally, are the functions and methods provided by Yahoo::Search.
In all cases, "...args..." are any of the key/value pairs listed in the
I<Query arguments> section of this document (e.g. "Count => 20")


=over 4

=item $SearchEngine = Yahoo::Search->new(...args...)

Creates a search-engine object (a container for defaults).
On error, sets C<$@> and returns nothing.



=item $Request = $SearchEngine->Request($space => $query, ...args...)

=item $Request = Yahoo::Search->Request($space => $query, ...args...)

Creates a C<Request> object representing a search of the named search space
(B<Doc>, B<Image>, etc.) of the given query string.

On error, sets C<$@> and returns nothing.

B<Note>: all arguments are in key/value pairs, but the C<$space>/C<$query>
pair (which is required) is required to appear first.




=item $Response = $SearchEngine->Query($space => $query, ...args...)

=item $Response = Yahoo::Search->Query($space => $query, ...args...)

Creates an implicit C<Request> object, and fetches it, returning the
resulting C<Response>.

On error, sets C<$@> and returns nothing.

B<Note>: all arguments are in key/value pairs, but the C<$space>/C<$query>
pair (which is required) is required to appear first.





=item @Results = $SearchEngine->Results($space => $query, ...args...)

=item @Results = Yahoo::Search->Results($space => $query, ...args...)

Creates an implicit C<Request> object, then C<Response> object,
in the end returning a list of C<Result> objects.

On error, sets C<$@> and returns nothing.

B<Note>: all arguments are in key/value pairs, but the C<$space>/C<$query>
pair (which is required) is required to appear first.




=item @links = $SearchEngine->Links($space => $query, ...args...)

=item @links = Yahoo::Search->Links($space => $query, ...args...)

A super shortcut which goes directly from the query args to a list of

  <a href=...>...</a>

links. Essentially,

    map { $_->Link } Yahoo::Search->Results($space => $query, ...args...);

or, more explicitly:

    map { $_->Link } Yahoo::Search->new()->Request($space => $query, ...args...)->Fetch->Results(@_);

See C<Link> in the documentation for Yahoo::Search::Result.

B<Note>: all arguments are in key/value pairs, but the C<$space>/C<$query>
pair (which is required) is required to appear first.





=item @links = $SearchEngine->Terms($space => $query, ...args...)

=item @links = Yahoo::Search->Terms($space => $query, ...args...)

A super shortcut for B<Spell>, B<Related>, and B<Terms> search spaces,
returns the list of spelling suggestions, related-search suggestions, or
important search terms, respectively.

B<Note>: all arguments are in key/value pairs, but the C<$space>/C<$query>
pair (which is required) is required to appear first. For a B<Terms>
search, the C<$query> may be C<undef> (and in in any case, a B<Terms>
search requires a C<Context> argument).


For example,

   use Yahoo::Search AppId => "YahooDemo";
   for my $term (Yahoo::Search->Terms(Related => "Tivo")) {
       print $term , "\n";
   }

displays something along the lines of:

   directv tivo
   hd tivo
   tivo community
   tivo forum
   tivo upgrade
   tivo rebate
   dvd recorder tivo
   direct tv tivo
   tivo to go
   hdtv tivo


Here's an example with the B<Terms> search space:

   use Yahoo::Search AppId => "YahooDemo";

   my $Context = << '*END*';
   We the People of the United States, in Order to form a more perfect
   Union, establish Justice, insure domestic Tranquility, provide for the
   common defence, promote the general Welfare, and secure the Blessings of
   Liberty to ourselves and our Posterity, do ordain and establish this
   Constitution for the United States of America.
   *END*

   for my $term (Yahoo::Search->Terms(Terms => undef, Context => $Context)) {
       print $term, "\n";
   }

displays something along the lines of:

  insure domestic tranquility
  promote the general welfare
  domestic tranquility
  united states
  states of america
  united states of america
  posterity
  blessings
  constitution
  perfect union

Note that a B<Spell> search returns at most one term.




=item @html = $SearchEngine->HtmlResults($space => $query, ...args...)

=item @html = Yahoo::Search->HtmlResults($space => $query, ...args...)

Like C<Links>, but returns a list of html strings (one representing each
result). See C<as_html> in the documentation for Yahoo::Search::Result.

A simple result display might look like

   print join "<p>", Yahoo::Search->HtmlResults(....);

or, perhaps

   if (my @HTML = Yahoo::Search->HtmlResults(....))
   {
      print "<ul>";
      for my $html (@HTML) {
         print "<li>", $html;
      }
      print "</ul>";
   }

As an example, here's a complete CGI which shows results from an
image-search, where the search term is in the 'C<s>' query string:

   #!/usr/local/bin/perl -w
   use CGI;
   my $cgi = new CGI;
   print $cgi->header();

   use Yahoo::Search AppId => 'my-search-app';
   if (my $term = $cgi->param('s')) {
       print join "<p>", Yahoo::Search->HtmlResults(Image => $term);
   }

The results, however, do look better with some style-sheet attention, such
as:

  <style>
    .yResult { display: block; border: #CCF 3px solid ; padding:10px }
    .yLink   { }
    .yTitle  { display:none }
    .yImg    { border: solid 1px }
    .yUrl    { display:none }
    .yMeta   { font-size: 80% }
    .ySrcUrl { }
    .ySum    { font-family: arial; font-size: 90% }
  </style>


B<Note>: all arguments are in key/value pairs, but the C<$space>/C<$query>
pair (which is required) is required to appear first.



=item $num = $SearchEngine->MaxCount($space)

=item $num = Yahoo::Search->MaxCount($space)

Returns the maximum allowed C<Count> query-argument for the given search space.



=item $SearchEngine->Default($key [ => $val ]);

If a new value is given, update the <$SearchEngine>'s value for the named
C<$key>.

In either case, the old value for C<$key> in effect is returned. If the
C<$SearchEngine> had a previous value, it is returned. Otherwise, the
global value in effect is returned.

As always, the key is from among those mentioned in the I<Query arguments>
section above.

The old value is returned.


=item Yahoo::Search->Default($key [ => $val ]);

Update or, if no new value is given, check the global default value for the
named argument. The key is from among those mentioned in the I<Query
examples> section above, as well as C<AutoCarp> (discussed below).

=back


=head1 Defaults and Default Overrides

All key/value pairs mentioned in the I<Query arguments> section may appear
on the C<use> line, in the call to the C<new> constructor, or in requests
that create a query explicitly or implicitly (C<Request>, C<Query>,
C<Results>, C<Links>, or C<HtmlResults>).

Each argument's value takes the first of the following which applies
(listed in order of precedence):

=over 6

=item 4)

The actual arguments to a function which creates (explicitly or implicitly)
a request.

=item 3)

Search-engine default overrides, set when the Yahoo::Search C<new>
constructor is used to create a search-engine object, or when that object's
C<Default> method is called.

=item 2)

Global default overrides, set on the C<use> line or via

 Yahoo::Search->Default()

=item 1)

Defaults hard-coded into these packages (e.g. C<Count> defaults to 10).

=back

It's particularly convenient to put the C<AppId> on the C<use> line,
e.g.

   use Yahoo::Search AppId => 'just testing';

=head1 AutoCarp

By default, detected errors that would be classified as programming errors
(e.g. use of incorrect args) are automatically spit out to stderr besides
being returned via C<$@>. This can be turned off via

  use Yahoo::Search AutoCarp => 0;

or

 Yahoo::Search->Default(AutoCarp => 0);

The default of true is somewhat obnoxious, but hopefully helps create
better programs by forcing the programmer to actively think about error
checking (if even long enough to turn off error reporting).


=head1 Global Variables

The following are globally available:

=over 5

=item C<%Yahoo::Search::KnownCountry>

A hash with the known (as of this writing) country codes supported by
Yahoo! for the C<Country> argument.

=item C<%Yahoo::Search::KnownLanguage>

A hash with the known (as of this writing) language codes supported by
Yahoo! for the C<Language> argument.

=item C<$Yahoo::Search::RecentRequestUrl>

The most recent REST url actually fetched from Yahoo! (perhaps useful for
debugging). It does I<not> reflect the fact that a request is changed to a
POST when request is sufficiently large. Thus, there are times when the url
on C<$Yahoo::Search::RecentRequestUrl> is not actually fetchable from the
Yahoo! servers.

=item C<$Yahoo::Search::UseXmlSimple>

If you set this to a true value, the XML returned by Yahoo! will be parsed
with B<XML::Simple> (if installed on your system) rather than with
Yahoo::Search::XML, a simple XML parser included as part of this package.
XML::Simple uses XML::Parser under the hood, and at least on the systems
I've tested it, XML::Parser suffers from a crippling memory leak that makes
it very undesirable.

However, if Yahoo! changes the XML they return in a way that my simple
parser can't handle, it tries parsing it with XML::Simple. If XML::Simple
is installed and can parse the XML, C<$Yahoo::Search::UseXmlSimple> is
automatically set to true and a warning generated suggesting that a bug
report be filed for Yahoo::Search::XML.

If you encounter a situation where Yahoo::Search::XML can't grok Yahoo!'s
XML, please submit a bug report. In the mean time, you can ensure that
XML::Simple is installed, set C<$Yahoo::Search::UseXmlSimple>, and at least
have things work until you run out of memory.

The default value of C<$Yahoo::Search::UseXmlSimple> is taken from the
environment variable C<YAHOO_SEARCH_XMLSIMPLE> if present, and otherwise
defaults to false.

=item C<$Yahoo::Search::Version>

A string in "X.Y.Z" format. The first number, the major version, increments
with large and/or backwards major incompatible changes. The second number
(minor version) updates with notable feature additions/changes. The third
number updates with every new release (and is the only one updated for
small bug- and typo fix releases).

=back

=head1 Environment

If C<YAHOO_SEARCH_XMLSIMPLE> is set to a true (nonempty, non-"0") value,
C<$Yahoo::Search::UseXmlSimple> defaults to true. See above.

Yahoo::Search uses LWP to communicate with Yahoo!'s servers; LWP uses
environment variables such as C<http_proxy> and C<no_proxy>. See the
perldoc for LWP for more.

=head1 Copyright

Copyright 2007 Yahoo! Inc.

=head1 Author

Jeffrey Friedl ([e-mail])

=cut