@node WWW/Search, WWW/Search/AltaVista, WWW/RobotRules/AnyDBM_File, Module List
@unnumbered Virtual base class for WWW searches


@unnumberedsec NAME

WWW::Search - Virtual base class for WWW searches

@unnumberedsec DESCRIPTION

This class is the parent for all access method supported by the
@code{WWW::Search} library.

Search results are limited and there is a pause between each request 
for results to avoid overloading either the client or the server.

@unnumberedsubsec Sample program

Using the library should be straightforward:
Here@'s a sample program:

@example
my($search) = new WWW::Search::AltaVista;
$search->native_query(WWW::Search::escape_query($query));
my($result);
while ($result = $search->next_result()) @{
	print $result->url, "\n";
@};
@end example

Results are objects of @code{WWW::SearchResult}
(see @xref{WWW/SearchResult,WWW/SearchResult},) .

@unnumberedsec SEE ALSO

For more details see @xref{LWP,LWP},.

@unnumberedsec METHODS AND FUNCTIONS

@unnumberedsubsec new

To create a new WWW::Search, call
    $search = new WWW::Search::SearchEngineName();
where SearchEngineName is replaced with a particular search engine.
For example:
    $search = new WWW::Search::AltaVista();

The next step is usually:
    $search->native_query(@'search-engine-specific query string@');

@unnumberedsubsec native_query

Specify a query to the current search object.
The query must be escaped; call @samp{escape_query}, @xref{WWW/Search,WWW/Search},
to escape a plain query.
Doesn@'t actually begin the search until results or
next_result is called.

Example:
    $search->native_query(@'search-engine-specific query string@');

The next step is usually:

@example
@@results = $search->results();
@end example

or

@example
while ($result = $search->next_result()) @{
	# do_something;
@};
@end example

@unnumberedsubsec results

Return all the results of a query as a reference to array 
of SearchResult objects.

Example:
    @@results = $search->results();
    foreach $result (@@results) @{
        print $result->url(), "\n";
    @};

@unnumberedsubsec next_result

Return each result of a query as a SearchResult object.

Example:
    while ($result = $search->next_result()) @{
	print $result->url(), "\n";
    @};

@unnumberedsubsec @code{seek_result($offset)}

Set which result next_result should return
(like lseek in Unix).
Results are zero-indexed.

The only guaranteed valid offset is 0
which will replay the results from the beginning.
In particular, seeking past the end of the current cached
results probably won@'t do what you might think it should.

Results are cached, so this doesn@'t re-issue the query
or cause IO (unless you go off the end of the results).
To re-do the query, create a new search object.

Example:
    $search->seek_result(0);

@unnumberedsubsec maximum_to_retrieve

The maximum number of hits to return (approximately).
Queries resulting in more than this many hits will return
the first hits, up to this limit.

Defaults to 500.

Example:
    $max = $seach->maximum_to_retrieve(100);

@unnumberedsubsec escape_query

Escape a query.
Before queries are made special characters must be escaped
so that a proper URL can be formed.

This is like escaping a URL
but "+" is a protected character
and spaces are converted to "+"@'s.

Example:
    $escaped = Search::escape_query(@'+lsam +replication@');
(Returns "%22lsam+replication%22").

See also unescape_query.

@unnumberedsubsec unescape_query

Unescape a query.
See escape_query for details.

Example:
    $unescaped = Search::unescape_query(@'%22lsam+replication%22@');
(Returns "+lsam +replication").

See also unescape_query.

@unnumberedsubsec setup_search (PRIVATE)

This internal routine does generic Search setup.
It calls @code{native_setup_search} to do back-end specific setup.

@unnumberedsubsec setup_user_agent (PRIVATE, NOT A METHOD)

This internal routine does setup for a user-agent
for dervived classes that use the web.

@unnumberedsubsec user_agent_delay (PRIVATE)

Derived classes should call this between requests to remote
servers to avoid overloading them with many, fast back-to-back requests.

@unnumberedsubsec retrieve_some (PRIVATE)

An internal routine to interface with @code{native_retrieve_some}.
Checks for overflow.

@unnumberedsec IMPLEMENTING NEW BACK-ENDS

@code{WWW::Search} supports back-ends to separate search engines.
Each back-end is implemented as a subclass of @code{WWW::Search}.
@xref{WWW/Search/AltaVista,WWW/Search/AltaVista}, provides a good sample back-end.

A back-end usually has two routines,
@code{native_retrieve_some} and @code{native_setup_search}.

@code{native_retrieve_some} is the core of a back-end.
It will be called periodically to fetch URLs.
Each call it should fetch a page with about 10 or so hits
and add them to the cache.  It should return the number
of hits found or undef when there are no more hits.

Internally, @code{native_retrieve_some} typically
will parse the HTML, extract the links and descriptions,
then find the @`@`next@'@' button and save the URL.
See the code for the AltaVista implementation for an example.

@code{native_setup_search} is invoked before the search.
It is passed a single argument:  the escaped, native version
of the query.

The front- and back-ends share a single object (a hash)
The back-end can change any hash element beginning with underscore,
and @code{@{response@}} (an @code{HTTP::Response} code) and @code{@{cache@}}
(the array of @code{WWW::SearchResult} objects caching all results).

If you implement a new back-end, please let the authors know.

@unnumberedsec AUTHOR

@code{WWW::Search} is written by John Heidemann, <johnh@@isi.edu>.

@unnumberedsec COPYRIGHT

Copyright (c) 1996 University of Southern California.
All rights reserved.                                            
                                                               
Redistribution and use in source and binary forms are permitted
provided that the above copyright notice and this paragraph are
duplicated in all such forms and that any documentation, advertising
materials, and other materials related to such distribution and use
acknowledge that the software was developed by the University of
Southern California, Information Sciences Institute.  The name of the
University may not be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

