.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "WWW::SearchResult 3pm"
.TH WWW::SearchResult 3pm "2020-09-10" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
WWW::SearchResult \- class for results returned from WWW::Search
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    require WWW::Search;
\&    require WWW::SearchResult;
\&    $search = new WWW::Search;
\&    $search\->native_query(WWW::Search::escape_query($query));
\&    # Get first result:
\&    $result = $search\->next_result();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A framework for returning the results of \f(CW\*(C`WWW::Search\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
WWW::Search
.SH "REQUIRED RESULTS"
.IX Header "REQUIRED RESULTS"
The particular fields returned in a result are backend\- (search
engine\-) dependent.  However, all search engines are required to
return a url and title.  (This list may grow in the future.)
.SH "METHODS AND FUNCTIONS"
.IX Header "METHODS AND FUNCTIONS"
.SS "new"
.IX Subsection "new"
To create a new WWW::SearchResult, call
.PP
.Vb 1
\&    $result = new WWW::SearchResult();
.Ve
.SS "url"
.IX Subsection "url"
Returns the primary \s-1URL.\s0  Note that there may be a list of urls, see
also methods \f(CW\*(C`urls\*(C'\fR and \f(CW\*(C`add_url\*(C'\fR.  Nothing special is guaranteed
about the primary \s-1URL\s0 other than that it is the first one returned by
the back end.
.PP
Every result is required to have at least one \s-1URL.\s0
.SS "add_url"
.IX Subsection "add_url"
Add a \s-1URL\s0 to the list.
.SS "urls"
.IX Subsection "urls"
Return a reference to the list of urls.
There is also a primary \s-1URL\s0 (\f(CW\*(C`url\*(C'\fR).
.SS "add_related_url"
.IX Subsection "add_related_url"
Add a \s-1URL\s0 to the related_url list.
.SS "related_urls"
.IX Subsection "related_urls"
Return a reference to the list of related urls.
.SS "add_related_title"
.IX Subsection "add_related_title"
Add a title to the list or related titles.
.SS "related_titles"
.IX Subsection "related_titles"
Return a reference to the list of related titles.
.SS "title, description, score, change_date, index_date, size, raw"
.IX Subsection "title, description, score, change_date, index_date, size, raw"
Set or get attributes of the result.
.PP
None of these attributes is guaranteed to be provided by 
a given backend.  If an attribute is not provided
its method will return \f(CW\*(C`undef\*(C'\fR.
.PP
Typical contents of these attributes:
.IP "title" 8
.IX Item "title"
The title of the hit result (typically that provided by the '\s-1TITLE\s0'
\&\s-1HTML\s0 tag).
.IP "description" 8
.IX Item "description"
A brief description of the result, as provided (or not) by the search engine.
Often the first few sentences of the document.
.IP "source" 8
.IX Item "source"
Source is either the base url for this result (as listed on the search
engine's results page) or another copy of the full url path of the
result.  It might also indicate the source site name or address whence
the result came, for example, '\s-1CNN\s0' or 'http://www.cnn.com' if the
search result page said \*(L"found at \s-1CNN\s0.com\*(R".
.Sp
This value is backend-specific; in fact very few backends set this
value.
.IP "add_sources" 8
.IX Item "add_sources"
Same meaning as source above, for adding sources in case there are
potentially multiple sources.
.IP "sources" 8
.IX Item "sources"
Returns a reference to the list of sources.
.IP "score" 8
.IX Item "score"
A backend specific, numeric score of the search result.
The exact range of scores is search-engine specific.
Usually larger scores are better, but this is no longer required.
See normalized_score for a backend independent score.
.IP "normalized_score" 8
.IX Item "normalized_score"
This is intended to be a backend-independent score of the search
result.  The range of this score is between 0 and 1000.  Higher values
indicate better quality results.
.Sp
This is not really implemented since no one has created an
backend-independent ranking algorithm.
.IP "change_date" 8
.IX Item "change_date"
When the result was last changed.  Typically this is the modification
time of the destination web page.
.IP "index_date" 8
.IX Item "index_date"
When the search engine indexed the result.
.IP "size" 8
.IX Item "size"
The approximate size of the result, in bytes.  This is only an
approximation because search backends often report the size as
\&\*(L"18.4K\*(R"; the best we can do with that number is return it as the value
of 18.4 * 1024.
.IP "raw" 8
.IX Item "raw"
The raw \s-1HTML\s0 for the entire result.  Raw should be exactly the raw
\&\s-1HTML\s0 for one entry.  It should not include list or table setup
commands (like ul or table tags), but it may include list item or
table data commands (like li, tr, or td).  Whether raw contains a list
entry, table row, br-separated lines, or plain text is search-engine
dependent.  In fact, many backends do not even return it at all.
.IP "as_HTML" 8
.IX Item "as_HTML"
Convert the search result to a human-readable form,
decorated with \s-1HTML\s0 for pretty-printing.
.SS "Others"
.IX Subsection "Others"
More attributes of the result.  Backend-specific.
Refer to the documentation of each backend for details.
.IP "bid_amount" 4
.IX Item "bid_amount"
.PD 0
.IP "bid_count" 4
.IX Item "bid_count"
.IP "bidder" 4
.IX Item "bidder"
.IP "category" 4
.IX Item "category"
.IP "company" 4
.IX Item "company"
.IP "end_date" 4
.IX Item "end_date"
.IP "image_url" 4
.IX Item "image_url"
.IP "item_number" 4
.IX Item "item_number"
.IP "location" 4
.IX Item "location"
.IP "question_count" 4
.IX Item "question_count"
.IP "seller" 4
.IX Item "seller"
.IP "shipping" 4
.IX Item "shipping"
.IP "sold" 4
.IX Item "sold"
.IP "start_date" 4
.IX Item "start_date"
.IP "thumb_url" 4
.IX Item "thumb_url"
.IP "watcher_count" 4
.IX Item "watcher_count"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
WWW::SearchResult was written by John Heidemann.
WWW::SearchResult is maintained by Martin Thurn.