# perldoc > WWW::Search

---
type: CommandReference
command: WWW::Search
mode: perldoc
section: 
source: perldoc
---

## Quick Reference

- `my $oSearch = new WWW::Search('AltaVista')` — create a new search object for a backend
- `$oSearch->native_query(WWW::Search::escape_query($query))` — specify a query
- `$oSearch->login($user, $password)` — login if needed
- `while (my $oResult = $oSearch->next_result()) { print $oResult->url, "\n" }` — iterate results
- `my @results = $oSearch->results()` — get all results (may be slow)
- `$oSearch->maximum_to_retrieve(100)` — limit number of hits
- `$oSearch->timeout(120)` — set timeout
- `my $escaped = WWW::Search::escape_query('+hi +mom')` — escape query string

## Name

Virtual base class for WWW searches

## Synopsis

perl
use WWW::Search;
my $sEngine = 'AltaVista';
my $oSearch = new WWW::Search($sEngine);
## Methods for Searchers

- `new('SearchEngineName')` — create a new search object. Defaults to `Null::Empty` if no engine given.
- `version` — returns `$VERSION` of the backend engine
- `maintainer` — returns `$MAINTAINER` of the backend engine
- `installed_engines` — returns list of all installed backend names
- `native_query($query, \%options)` — specify a query (escaped) and optional options. Does not start retrieval until `results()` or `next_result()` is called. Generic options: `search_url`, `search_debug`, `search_parse_debug`, `search_to_file FILE`, `search_from_file FILE`.
- `gui_query($query, \%options)` — same as `native_query` but uses engine's default options (as if typed in browser)
- `cookie_jar($filename_or_HTTP::Cookies)` — set/get cookie jar. If no argument, returns current jar.
- `date_from($date)` — set/get start date for date range limiting (backend-dependent)
- `date_to($date)` — set/get end date for date range limiting (backend-dependent)
- `env_proxy($bool)` — enable/disable proxy from environment variables (`http_proxy`, `http_proxy_user`, `http_proxy_pwd`). Must be called before first retrieval.
- `http_proxy($protocols => $url)` — set up HTTP proxy. Takes same arguments as `LWP::UserAgent::proxy()`.
- `http_proxy_user($username)` — set/get HTTP proxy username
- `http_proxy_pwd($password)` — set/get HTTP proxy password
- `maximum_to_retrieve($n)` — set maximum hits to return (default 500). Synonym: `maximum_to_return`.
- `timeout($seconds)` — set maximum time per request portion (default 60)
- `login($user, $password)` — login to search engine (if backend supports). Returns nonzero on success.
- `logout` — logout from search engine (if backend supports)
- `approximate_result_count` — returns estimated number of results (or undef if not available). Alias: `approximate_hit_count`.
- `results` — return all results as array of `WWW::SearchResult` objects. May take time retrieving all pages.
- `next_result` — return each result as a `WWW::SearchResult` object. Returns undef when no more results or error.
- `seek_result($offset)` — set which result to return next by `next_result` (0 replays from beginning). Does not re-issue query.
- `response` — returns `HTTP::Response` object from most recent query. Check `is_success` for errors.
- `submit(@args)` — submit URLs to search engine for indexing (backend-dependent). Returns `HTTP::Response`.
- `opaque($data)` — store/get an opaque data element (or reference) for client-specific information.

## Functions

- `WWW::Search::escape_query($string)` — escape a query string: all non-alphanumeric characters are escaped, spaces become `+`. Not a method.
- `WWW::Search::unescape_query($string)` — unescape a query string. Not a method.
- `WWW::Search::strip_tags($string)` — remove HTML tags from a string. Not a method.

## Methods for Backend Programmers

- `reset_search` — reset internal data structures for a new search on the same engine
- `is_http_proxy` — returns true if proxy information is available
- `is_http_proxy_auth_data` — returns true if all authentication data (proxy URL, username, password) are available
- `agent_name($name)` — set the user-agent name (trick browser detection)
- `agent_email($email)` — set the user-agent email
- `user_agent($non_robot)` — create/replace user-agent object. If `$non_robot` is true, uses `LWP::UserAgent` instead of `LWP::RobotUA`. If `$ENV{WWW_SEARCH_USERAGENT}` is set, uses that class.
- `http_referer($url)` — get/set HTTP_REFERER for the search object
- `http_method($method)` — get/set HTTP method (`GET` or `POST`, default `GET`)
- `http_request($method, $url)` — submit HTTP request, handle cookies, redirects. Requires `http_referer` if needed.
- `next_url($url)` — get/set URL for next backend request (useful for state preservation between sessions)
- `split_lines($lines_ref, $data)` — split data into lines OS-independently. Optional first argument is array ref of delimiters.
- `generic_option($option)` — check if option is generic (starts with `search_`). Not a method.
- `_native_setup_search($query)` — backend-specific initialization called with same args as `native_query`
- `setup_search` — generic setup, calls `_native_setup_search`
- `need_to_delay` — override to control whether `user_agent_delay` is called before next HTTP request
- `user_agent_delay` — called between requests to avoid overloading servers
- `absurl($base, $url)` — convert relative URL to absolute URL; returns a `URI` object
- `retrieve_some` — internal routine that calls `_native_retrieve_some`, checks for overflow
- `_native_retrieve_some` — fetch next page of results, parse, prepare for next page. Full control of fetch/parse. Alternatively, define `_parse_tree` instead.
- `_parse_tree($tree)` — called with an `HTML::TreeBuilder` object, returns number of results found on this page. Must set `$self->next_url` for continuation.
- `preprocess_results_page($html)` — filter raw HTML before parsing (e.g., correct known problems)
- `result_as_HTML($result)` — format a `WWW::SearchResult` object as HTML
- `test_cases` (DEPRECATED) — returns `$TEST_CASES` of backend
- `hash_to_cgi_string(\%hash)` (DEPRECATED) — construct CGI parameter string from hash

## Implementing New Backends

- Backend must define `_native_setup_search()` and either `_native_retrieve_some()` or `_parse_tree()`.
- `_native_setup_search` is invoked before the search with the escaped native query.
- `_native_retrieve_some` fetches URLs, returns number of hits found or undef when done.
- Alternatively, define `_parse_tree` which receives an `HTML::TreeBuilder` object. Set `$self->next_url` for next page.
- Use `$self->{_prev_url}` to get URL of current page.
- For custom `HTML::TreeBuilder`, set `$self->{'_treebuilder'}` before retrieval.
- See `WWW::Search::AltaVista` and `WWW::Search::Ebay` for examples.

## See Also

- [WWW::Search::TheEngineName](https://perldoc.perl.org/WWW::Search::TheEngineName) — documentation for specific search engines
- [WWW::SearchResult](https://perldoc.perl.org/WWW::SearchResult) — details about search results
- [LWP::UserAgent](https://perldoc.perl.org/LWP::UserAgent)
- [LWP::RobotUA](https://perldoc.perl.org/LWP::RobotUA)
- [HTTP::Cookies](https://perldoc.perl.org/HTTP::Cookies)
- [HTML::TreeBuilder](https://perldoc.perl.org/HTML::TreeBuilder)