oracular (3) WWW::SearchResult.3pm.gz

NAME

       WWW::SearchResult - class for results returned from WWW::Search

SYNOPSIS

           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();

DESCRIPTION

       A framework for returning the results of "WWW::Search".

SEE ALSO

       WWW::Search

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.)

METHODS AND FUNCTIONS

   new
       To create a new WWW::SearchResult, call

           $result = new WWW::SearchResult();

   url
       Returns the primary URL.  Note that there may be a list of urls, see also methods "urls" and "add_url".
       Nothing special is guaranteed about the primary URL other than that it is the first one returned by the
       back end.

       Every result is required to have at least one URL.

   add_url
       Add a URL to the list.

   urls
       Return a reference to the list of urls.  There is also a primary URL ("url").

   add_related_url
       Add a URL to the related_url list.

   related_urls
       Return a reference to the list of related urls.

   add_related_title
       Add a title to the list or related titles.

   related_titles
       Return a reference to the list of related titles.

   title, description, score, change_date, index_date, size, raw
       Set or get attributes of the result.

       None of these attributes is guaranteed to be provided by a given backend.  If an attribute is not
       provided its method will return "undef".

       Typical contents of these attributes:

       title   The title of the hit result (typically that provided by the 'TITLE' HTML tag).

       description
               A brief description of the result, as provided (or not) by the search engine.  Often the first
               few sentences of the document.

       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, 'CNN' or 'http://www.cnn.com' if the search result
               page said "found at CNN.com".

               This value is backend-specific; in fact very few backends set this value.

       add_sources
               Same meaning as source above, for adding sources in case there are potentially multiple sources.

       sources Returns a reference to the list of sources.

       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.

       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.

               This is not really implemented since no one has created an backend-independent ranking algorithm.

       change_date
               When the result was last changed.  Typically this is the modification time of the destination web
               page.

       index_date
               When the search engine indexed the result.

       size    The approximate size of the result, in bytes.  This is only an approximation because search
               backends often report the size as "18.4K"; the best we can do with that number is return it as
               the value of 18.4 * 1024.

       raw     The raw HTML for the entire result.  Raw should be exactly the raw HTML 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.

       as_HTML Convert the search result to a human-readable form, decorated with HTML for pretty-printing.

   Others
       More attributes of the result.  Backend-specific.  Refer to the documentation of each backend for
       details.

       bid_amount
       bid_count
       bidder
       category
       company
       end_date
       image_url
       item_number
       location
       question_count
       seller
       shipping
       sold
       start_date
       thumb_url
       watcher_count

AUTHOR

       WWW::SearchResult was written by John Heidemann.  WWW::SearchResult is maintained by Martin Thurn.