File Coverage

blib/lib/Yahoo/Search.pm

Criterion	Covered	Total	%
statement	87	143	60.8
branch	38	82	46.3
condition	7	30	23.3
subroutine	11	16	68.7
pod	9	9	100.0
total	152	280	54.2

package Yahoo::Search;
BEGIN {
  $Yahoo::Search::VERSION = '1.11.3';
}
use strict;
use Carp;
use Yahoo::Search::Request;

##
## This is the interface to Yahoo!'s web search API.
## Written by Jeffrey Friedl
##
## Master source:
##
##   http://search.cpan.org/search?mode=module&n=1&query=Yahoo::Search
##

##
## CLASS OVERVIEW
##
##      The main class
##        Yahoo::Search
##      begets
##        Yahoo::Search::Request
##      which begets
##        Yahoo::Search::Response
##      which begets a bunch of
##        Yahoo::Search::Result
##      which beget urls, summaries, etc.
##
## There are plenty of "convenience functions" which appear to bypass some
## of these steps as far as the user's view is concerned.
##

##
## Configuration details for each search space (Doc, Images, Video, ## etc.)...
##
my %Config =
(
  ######################################################################
  # Normal web search
  #
  Doc =>
  {
   Url        => 'http://search.yahooapis.com/WebSearchService/V1/webSearch',
   ContextUrl => 'http://search.yahooapis.com/WebSearchService/V1/contextSearch',

   MaxCount => 50,

   ## The 'Defaults' keys indicate the universe of allowable arguments,
   ## while the values are the defaults for those arguments.
   Defaults => {
                Mode         => undef,
                Context      => undef,
                Count        => 10,
                Start        => 0,
                Type         => 'any',
                AllowAdult   => 0,
                AllowSimilar => 0,
                Language     => undef,
                Country      => undef,
                License      => undef,
                Region       => undef,
               },

   QueryOptional => 1,

   AllowedLicense => {
                      any           => 1, #default
                      cc_any        => 1,
                      cc_commercial => 1,
                      cc_modifiable => 1,
                        },

   AllowedMode => {
                   all    => 1,
                   any    => 1,
                   phrase => 1,
                  },

   AllowedType => {
                     all    => 1, # deprecated
                     any    => 1,

                     html   => 1,
                     msword => 1,
                     pdf    => 1,
                     ppt    => 1,
                     rss    => 1,
                     txt    => 1,
                     xls    => 1,
                    },
  },


  ######################################################################
  # Image search
  #
  Image =>
  {
   Url => 'http://search.yahooapis.com/ImageSearchService/V1/imageSearch',
   MaxCount => 50,

   Defaults => {
                Mode       => undef,
                Count      => 10,
                Start      => 0,
                Type       => 'any',
                AllowAdult => 0,
                Color      => undef,
               },

   AllowedMode => {
                   all    => 1,
                   any    => 1,
                   phrase => 1,
                  },

   AllowedType => {
                     all  => 1, # deprecated
                     any  => 1,

                     bmp  => 1,
                     gif  => 1,
                     jpeg => 1,
                     png  => 1,
                    },

   AllowedColor => {
                    any   => 1, # default
                    color => 1,
                    bw    => 1,
                   }

  },

  ######################################################################
  # Video file search
  #
  Video =>
  {
   Url => 'http://search.yahooapis.com/VideoSearchService/V1/videoSearch',

   MaxCount => 50,

   Defaults => {
                Mode       => undef,
                Count      => 10,
                Start      => 0,
                Type       => 'any',
                AllowAdult => 0,
               },

   AllowedMode => {
                   all    => 1,
                   any    => 1,
                   phrase => 1,
                  },

   AllowedType => {
                     all       => 1, # deprecated
                     any       => 1,

                     avi       => 1,
                     flash     => 1,
                     mpeg      => 1,
                     msmedia   => 1,
                     quicktime => 1,
                     realmedia => 1,
                    },
  },


  ######################################################################
  # "Y! Local" (like Yellow Pages) search
  #
  Local =>
  {
   Url => 'http://local.yahooapis.com/LocalSearchService/V1/localSearch',

   MaxCount => 20,

   Defaults => {
                Count      => 10,
                Start      => 0,
                Mode       => undef,
                Radius     => undef,
                Street     => undef,
                City       => undef,
                State      => undef,
                PostalCode => undef,
                Location   => undef,
                Lat        => undef,
                Long       => undef,
                Sort       => undef,
               },

   AllowedSort => {
                   relevance => 1,
                   distance  => 1,
                   rating    => 1,
                   title     => 1
                  }
  },


  ######################################################################
  # News search
  #
  News =>
  {
   Url => 'http://search.yahooapis.com/NewsSearchService/V1/newsSearch',

   MaxCount => 50,

   Defaults => {
                Mode     => undef,
                Count    => 10,
                Start    => 0,
                Sort     => undef,
                Language => undef,
               },

   AllowedMode => {
                   all    => 1,
                   any    => 1,
                   phrase => 1,
                  },

   AllowedSort => {
                   rank   => 1,
                   date   => 1,
                  },
  },


  Terms =>
  {
   Url => 'http://search.yahooapis.com/ContentAnalysisService/V1/termExtraction',

   Defaults => {
                Context => undef,
               },
   Required => {
                Context => 1,
               },
   QueryOptional => 1,
  },

  Spell =>
  {
   Url => 'http://search.yahooapis.com/WebSearchService/V1/spellingSuggestion',
  },

  Related =>
  {
   Url => 'http://search.yahooapis.com/WebSearchService/V1/relatedSuggestion',
   Defaults => {
                Count => 10,
               },
  },
);

our $UseXmlSimple = $ENV{YAHOO_SEARCH_XMLSIMPLE}; ## used in Search/Request.pm
our $RecentRequestUrl; ## filled in Search/Request.pm


##
## These args are allowed for any Query()
##
my @ExtraQueryArgs = qw[AutoContinue Debug AppId];

##
## Global defaults -- this list may be modified via import()
## and Default();
##
my %GlobalDefault =
(
 ##
 ## Debug is a string with any of: url   (show the url as fetched)
 ##                                xml   (show the resulting xml)
 ##                                hash  (show the resulting hash)
 ##                                stdout (show to stdout instead of stderr)
 ## e.g. "url hash stdout"
 Debug => "",

 ##
 ## if AutoCarp is true (as it is by default), carp on programming errors
 ## (but not 404s, etc.)
 ##
 AutoCarp => 1,

 AutoContinue => 0,

 PreRequestCallback => undef,
);

##
## Helper function to set $@ and, if needed, carp.
##
sub _carp_on_error($)
{
    $@ = shift;
    if ($GlobalDefault{AutoCarp}) {
        carp $@;
    }

    return ();
}


##
## The following private subs are used to validate arguments. They are
## generally called with two args: the search space (Doc, Image, etc.), and
## the text to validate.
##
## If called without the "text to validate" arg, they return a description
## of what args are allowed (tailored to the search space, if appropriate).
##
## Otherwise, they return ($valid, $value).
##
my $allow_positive_integer = sub
{
    my $space = shift; # unused
    if (not @_) {
        return "positive integer";
    }
    my $val = shift;

    if (not $val =~ m/^\d+$/) {
        return (0); # invalid: not a number
    } elsif ($val == 0) {
        return (0); # invalid: not positive
    } else {
        return (1, $val);
    }
};

my $allow_nonnegative_integer = sub
{
    my $space = shift; # unused
    if (not @_) {
        return "non-negative integer";
    }
    my $val = shift;

    if (not $val =~ m/^\d+$/) {
        return (0); # invalid: not a number
    } else {
        return (1, $val);
    }
};

my $allow_positive_float = sub
{
    my $space = shift; # unused
    if (not @_) {
        return "positive number";
    }
    my $val = shift;

    if (not $val =~ m/^(?:  \d+(?: \.\d* )?$ | \.\d+$ )/x) {
        return (0); # invalid: not a number
    } elsif ($val == 0) {
        return (0); # invalid: not positive
    } else {
        return (1, $val);
    }
};

my $allow_float = sub
{
    my $space = shift; # unused
    if (not @_) {
        return "number";
    }
    my $val = shift;

    if (not $val =~ m/^-? (?:  \d+(?: \.\d* )?$ | \.\d+$ )/x) {
        return (0); # invalid: not a number
    } else {
        return (1, $val);
    }
};

my $allow_country_code = sub
{
    my $space = shift; # unused
    if (not @_) {
        return "country code";
    }
    my $val = shift;

    if (not $val =~ m/^(?: [a-z][a-z]$ | default$ )/x) {
        return (0); # not a country code and not "default"
    } else {
        return (1, $val);
    }
};

my $allow_language_code = sub
{
    my $space = shift; # unused
    if (not @_) {
        return "language code";
    }
    my $val = shift;

    if (not $val =~ m/^(?: [a-z][a-z][a-z]?$ | default$ )/x) {
        return (0); # not a language code and not "default"
    } else {
        return (1, $val);
    }
};


##
## This has different args than the others: it has two args ($allow_multi
## and $hashref) prepended before $space
##
my $allow_from_hash = sub
{
    my $allow_multi = shift;
    my $hashref = shift; #hash in which to check
    my $space   = shift; #unused

    if (not @_) {
        return join '|', sort keys %$hashref;
    }
    my $val = shift;

    if (not $hashref) {
        return (1, $val); # can't tell, so say it's valid
    }

    if (not defined($val) or not length($val))
    {
        return (0); # not valid
    }

    if (not $allow_multi)
    {
        if ($hashref->{$val}) {
            return (1, $val); # is specifically valid
        } else {
            return (0); # not valid
        }
    }
    else
    {
        my @items = split /[+,\s]+/, $val;
        if (not @items) {
            return (0); # not valid
        }

        for my $item (@items)
        {
            if (not $hashref->{$item}) {
                return (0); # not valid
            }
        }
        return (1, $val); # valid
    }
};

my $allow_boolean = sub
{
    my $space = shift; #unused
    if (not @_) {
        return "true or false";
    }
    my $val = shift;
    return (1, $val ? 1 : 0);
};

my $allow_any = sub
{
    my $space = shift; #unused
    if (not @_) {
        return "any value";
    }
    my $val = shift;
    return (1, $val);
};

my $allow_postal_code = sub
{
    my $space = shift; #unused
    ## only U.S. Zone Improvement Program codes allowed
    if (not @_) {
        return "a US ZIP code"
    }

    my $val = shift;
    if ($val =~ m/^\d\d\d\d\d(?:-?\d\d\d\d)?$/) {
        return (1, $val);
    } else {
        return (0);
    }
};

my $allow_coderef = sub
{
    my $space = shift; #unused
    my $val = shift;
    if (ref($val) eq 'CODE') {
        return (1, $val);
    } else {
        return (0);
    }
};

my $allow_appid = sub
{
    my $space = shift; #unused

    if (not @_) {
        return "something which matches /^[- A-Za-z0-9_()[\\]*+=,.:\@\\\\]{8,}\$/";
    }

    my $val = shift;
    if ($val =~ m/^[- A-Za-z0-9_()\[\]*+=,.:\@\\]{8,}$/) {
        return (1, $val);
    } else {
        return (0);
    }
};

our %KnownLanguage =
(
 default => 'any/all languages',

 ar  =>  'Arabic',
 bg  =>  'Bulgarian',
 ca  =>  'Catalan',
 szh =>  'Chinese (simplified)',
 tzh =>  'Chinese (traditional)',
 hr  =>  'Croatian',
 cs  =>  'Czech',
 da  =>  'Danish',
 nl  =>  'Dutch',
 en  =>  'English',
 et  =>  'Estonian',
 fi  =>  'Finnish',
 fr  =>  'French',
 de  =>  'German',
 el  =>  'Greek',
 he  =>  'Hebrew',
 hu  =>  'Hungarian',
 is  =>  'Icelandic',
 it  =>  'Italian',
 ja  =>  'Japanese',
 ko  =>  'Korean',
 lv  =>  'Latvian',
 lt  =>  'Lithuanian',
 no  =>  'Norwegian',
 fa  =>  'Persian',
 pl  =>  'Polish',
 pt  =>  'Portuguese',
 ro  =>  'Romanian',
 ru  =>  'Russian',
 sk  =>  'Slovak',
 sl  =>  'Slovenian',
 es  =>  'Spanish',
 sv  =>  'Swedish',
 th  =>  'Thai',
 tr  =>  'Turkish',
);

our %KnownCountry =
(
 default => "any/all countries",

 ar => 'Argentina',
 au => 'Australia',
 at => 'Austria',
 be => 'Belgium',
 br => 'Brazil',
 ca => 'Canada',
 cn => 'China',
 cz => 'Czech Republic',
 dk => 'Denmark',
 fi => 'Finland',
 fr => 'France',
 de => 'Germany',
 it => 'Italy',
 jp => 'Japan',
 kr => 'Korea',
 nl => 'Netherlands',
 no => 'Norway',
 pl => 'Poland',
 rf => 'Russian Federation',
 es => 'Spain',
 se => 'Sweden',
 ch => 'Switzerland',
 tw => 'Taiwan',
 uk => 'United Kingdom',
 us => 'United States',
);


##
## Mapping from arg name to value validation routine.
##
my %ValidateRoutine =
(
 Count        => $allow_positive_integer,
 Start        => $allow_nonnegative_integer,

 Radius       => $allow_positive_float,

 AllowAdult   => $allow_boolean,
 AllowSimilar => $allow_boolean,

 Context      => $allow_any,

 Street       => $allow_any,
 City         => $allow_any,
 State        => $allow_any,
 Location     => $allow_any,
 Lat          => $allow_float,
 Long         => $allow_float,

 PostalCode   => $allow_postal_code,
 Language     => $allow_language_code,
 Country      => $allow_country_code,
 Region       => $allow_country_code,

 Mode      => sub { $allow_from_hash->(0, $Config{$_[0]}->{AllowedMode}, @_) },
 Sort      => sub { $allow_from_hash->(0, $Config{$_[0]}->{AllowedSort}, @_) },
 Type      => sub { $allow_from_hash->(0, $Config{$_[0]}->{AllowedType}, @_) },
 License   => sub { $allow_from_hash->(1, $Config{$_[0]}->{AllowedLicense}, @_) },
 Color     => sub { $allow_from_hash->(0, $Config{$_[0]}->{Color}, @_) },

 Debug        => $allow_any,
 AutoContinue => $allow_boolean,
 AutoCarp     => $allow_boolean,

 AppId        => $allow_appid,

 PreRequestCallback => $allow_coderef,
);

##
## returns ($newvalue, $error);
##
sub _validate($$$;$)
{
    my $global   = shift; # true if for a global setting
    my $space    = shift; # Doc, Image, etc.
    my $key      = shift; # "Count", "State", etc.
    my $have_val = @_ ? 1 : 0;
    my $val      = shift;

    if (not $ValidateRoutine{$key}) {
        return (undef, "unknown argument '$key'");
    }

    if (not $global and $key eq 'AutoCarp') {
        return (undef, "AutoCarp is a global setting which can not be used in this context");
    }

    if (not $have_val) {
        return (1);
    }

    my ($valid, $newval) = $ValidateRoutine{$key}->($space, $val);

    if ($valid) {
        return ($newval, undef);
    }

    my $expected = $ValidateRoutine{$key}->($space);
    if ($space) {
        return (undef, "invalid value \"$val\" for $space\'s \"$key\" argument, expected: $expected");
    } else {
        return (undef, "invalid value \"$val\" for \"$key\" argument, expected: $expected");
    }
}


##
## 'import' accepts key/value pairs:
##
sub import
{
    my $class = shift;

    if (@_ % 2 != 0) {
        Carp::confess("bad number of args to 'use $class'");
    }
    my %Args = @_;

    while (my ($key, $val) = each %Args)
    {
        my ($newval, $error) = _validate(1, undef, $key, $val);
        if ($error) {
            Carp::confess("$error, in 'use $class'");
        } else {
            $GlobalDefault{$key} = $newval;
        }
    }
}


##
## Get (or set) one of the default global values. They can be set this way
## (either as Yahoo::Search->Default or $SearchEngine->Default), or via
## Yahoo::Search->new(), or on the 'use' line.
##
## When used with a $SearchEngine object, the value returned is the value
## in effect, which is the global one if the $SearchEngine does not have
## one itself.
##
sub Default
{
    my $class_or_obj = shift; # Yahoo::Search->Default or $SearchEngine->Default
    my $key          = shift;
    my $have_val     = @_ ? 1 : 0;
    my $val          = shift;

    my $global = not ref $class_or_obj;

    my $old;
    if ($global or not exists $class_or_obj->{$key}) {
        $old = $GlobalDefault{$key};
    } else {
        $old = $class_or_obj->{$key};
    }

    if ($have_val)
    {
        my ($newval, $error) = _validate($global, undef, $key, $val);
        if ($error) {
            return _carp_on_error($error);
        }

        if (ref $class_or_obj) {
            $class_or_obj->{$key} = $newval;
        } else {
            $GlobalDefault{$key} = $newval;
        }
    }
    else
    {
        my ($okay, $error) = _validate($global, undef, $key);
        if ($error) {
            return _carp_on_error($error);
        }
    }

    return $old;
}



##
## Maps Yahoo::Search->Query arguments to Y! API parameters.
##
my %ArgToParam =
(
 AllowAdult   => 'adult_ok',
 AllowSimilar => 'similar_ok',
 AppId        => 'appid',
 City         => 'city',
 Context      => 'context',
 Count        => 'results',
 Country      => 'country',
 Color        => 'coloration',
 Language     => 'language',
 Lat          => 'latitude',
 License      => 'license',
 Location     => 'location',
 Long         => 'longitude',
 Mode         => 'type',
 PostalCode   => 'zip',
 Radius       => 'radius',
 Region       => 'region',
 Sort         => 'sort',
 Start        => 'start',
 State        => 'state',
 Street       => 'street',
 Type         => 'format',
);


##
## The search-engine constructor.
##
## No args are needed, but any of %ValidateRoutine keys except AutoCarp are
## allowed (they'll be used as the defaults when queries are later
## constructed via this object).
##
sub new
{
    my $class = shift;

    if (@_ % 2 != 0) {
        return _carp_on_error("wrong arg count to $class->new");
    }

    my $SearchEngine = { @_ };

    for my $key (keys %$SearchEngine)
    {
        my ($newval, $error)  = _validate(0, undef, $key, $SearchEngine->{$key});
        if ($error) {
            return _carp_on_error("$error, in call to $class->new");
        }
        $SearchEngine->{$key} = $newval;
    }

    return bless $SearchEngine, $class;
}

##
## Request method (can also be called like a constructor).
## Specs to a specific query are provided, and a Request object is returned.
##
sub Request
{
    my $SearchEngine = shift; # self
    my $SearchSpace  = shift; # "Doc", "Image", "News", etc..
    my $QueryText    = shift; # "Briteny", "egregious compensation semel", etc.

    if (@_ % 2 != 0) {
        return _carp_on_error("wrong arg count");
    }

    my %Args = @_;

    if (not defined $SearchSpace or not $Config{$SearchSpace}) {
        my $list = join '|', sort keys %Config;
        return _carp_on_error("bad search-space identifier, expecting one of: $list");
    }

    ##
    ## Ensure that required args are there
    ##
    if (my $ref = $Config{$SearchSpace}->{Required})
    {
        for my $arg (keys %$ref)
        {
            if (not defined($Args{$arg}) or not length($Args{$arg})) {
                return _carp_on_error("argument '$arg' required");
            }
        }
    }


    ##
    ## %Param holds the key/vals we'll send in the request to Yahoo!
    ##
    my %Param;

    ##
    ## Special case for some searches: query not required
    ##
    if (not defined($QueryText) or length($QueryText) == 0)
    {
        if ($Args{Context} and $Config{$SearchSpace}->{QueryOptional}) {
            ## query text not required
        } else {
            return _carp_on_error("missing query");
        }
    }
    else
    {
        ## normal query
        $Param{query} = $QueryText;
    }


    ##
    ## This can be called as a constructor -- if so, $SearchEngine will be
    ## the class name, and we'll want to turn into an object.
    ##
    if (not ref $SearchEngine) {
        $SearchEngine = $SearchEngine->new();
    }

    my %OtherRequestArgs;

    ##
    ## Go through most allowed args, taking the value from this call's arg
    ## list if provided, from the defaults that were registered with the
    ## SearchEngine, or failing those, the defaults for this type of query.
    ##
    for my $key (keys %{ $Config{$SearchSpace}->{Defaults} }, @ExtraQueryArgs)
    {
        ##
        ## Isolate the value we'll use for this request: from our args,
        ## from the defaults registered with the search-engine, or from
        ## the search-space defaults.
        ##
        my $val;
        if (exists $Args{$key}) {
            $val = delete $Args{$key};
        } elsif (exists $SearchEngine->{$key}) {
            $val = $SearchEngine->{$key};
        } elsif (exists $GlobalDefault{$key}) {
            $val = $GlobalDefault{$key};
        } elsif (exists $Config{$SearchSpace}->{Defaults}->{$key}) {
            $val = $Config{$SearchSpace}->{Defaults}->{$key};
        } else {
            $val = undef;
        }

        if (defined $val)
        {
            my ($newval, $error) = _validate(0, $SearchSpace, $key, $val);

            if ($error) {
                return _carp_on_error($error);
            }

            if (my $param = $ArgToParam{$key}) {
                $Param{$param} = $newval;
            } else {
                $OtherRequestArgs{$key} = $newval;
            }
        }
    }

    ##
    ## Any leftover args are bad
    ##
    if (%Args) {
        my $list = join(', ', keys %Args);
        return _carp_on_error("unknown args for '$SearchSpace' query: $list");
    }

    ##
    ## An AppId is required for all calls
    ##
    if (not $Param{'appid'})
    {
        return _carp_on_error("an AppId is required -- please make one up");
    }

    ##
    ## Do some special per-arg-type processing
    ##

    ##
    ## If we're doing a Doc context search, be sure to use the proper
    ## action url
    ##
    my $ActionUrl = $Config{$SearchSpace}->{Url};

    if ($Param{context} and $Config{$SearchSpace}->{ContextUrl}) {
        $ActionUrl = $Config{$SearchSpace}->{ContextUrl};
    }

    ##
    ## Ensure that the Count, if given, is not over max
    ## No longer enforced here. MaxCount is only advisory now.
    #if (defined $Param{count} and $Param{count} > $Config{$SearchSpace}->{MaxCount}) {
    #    return _carp_on_error("maximum allowed Count for a $SearchSpace search is $Config{$SearchSpace}->{MaxCount}");
    #}

    ##
    ## If License is given, it an have multiple values (space, comma, or
    ## plus-separated).
    ##
    if ($Param{license}) {
        $Param{license} = [ split /[+,\s]+/, $Param{license} ];
    }

    ##
    ## In Perl universe, Start is 0-based, but the Y! API's "start" is 1-based.
    ##
    $Param{start}++;

    # 'Local' has special required parameters
    if ($SearchSpace eq 'Local'
        and not
        ## the following are the allowed parameter sets... if one is there,
        ## we're okay
        ($Param{location}
         or
         $Param{'zip'}
         or
         ($Param{'state'} and $Param{'city'})
         or
         (defined($Param{'latitude'}) and defined($Param{'longitude'}))
        ))
    {
        ##
        ## The diff between $Param{} references in the if() above, and
        ## the arg names in the error below, is the %ArgToParam mapping
        ##
        return _carp_on_error("a 'Local' query must have at least Lat+Long, Location, PostalCode, or City+State");
    }

    ##
    ## Okay, we have everything we need to make a specific request object.
    ## Make it and return.
    ##
    return Yahoo::Search::Request->new(
                                       SearchEngine => $SearchEngine,
                                       Space  => $SearchSpace,
                                       Action => $ActionUrl,
                                       Params => \%Param,
                                       %OtherRequestArgs,
                                      );
}

##
## A way to bypass an explicit Request object, jumping from a SearchEngine
## (or nothing) directly to a Response object.
##
sub Query
{
    my $SearchEngine = shift;
    ##
    ## Can be called as a constructor -- if so, $SearchEngine will be the
    ## class name
    ##
    if (not ref $SearchEngine) {
        $SearchEngine = $SearchEngine->new();
    }

    if (my $Request = $SearchEngine->Request(@_)) {
        return $Request->Fetch();
    } else {
        # $@ already set
        return ();
    }
}


##
## A way to bypass explicit Request and Response objects, jumping from a
## SearchEngine (or nothing) directly to a list of Result objects.
##
sub Results
{
    my $Response = Query(@_);

    if (not $Response) {
        # $@ already set
        return ();
    }
    return $Response->Results;
}

##
## A way to bypass explicit Request and Response objects, jumping from a
## SearchEngine (or nothing) directly to a list of links.
##
sub Links
{
    return map { $_->Link } Results(@_);
}


##
## A way to bypass explicit Request and Response objects, jumping from a
## SearchEngine (or nothing) directly to a bunch of html results.
##
sub HtmlResults
{
    return map { $_->as_html } Results(@_);
}

##
## A way to bypass explicit Request and Response objects, jumping from a
## SearchEngine (or nothing) directly to a list of terms
## (For Spell, Related, and Terms searches)
##
sub Terms
{
    return map { $_->Term } Results(@_);
}


sub MaxCount
{
    if (@_) {
        ##
        ## We'll use only the last arg -- it can be called as either
        ## Yahoo::Search::MaxCount($SearchSpace) or
        ## Yahoo:Search->MaxCount($SearchSpace) and we don't care which.
        ## In either case, the final arg is the search space.
        ##
        my $SearchSpace = $_[-1];
        if ($Config{$SearchSpace} and $Config{$SearchSpace}->{MaxCount}) {
            return $Config{$SearchSpace}->{MaxCount};
        }
    }
    return (); # bad/missing arg
}



1;
__END__