table of contents
FirstGov(3pm) | User Contributed Perl Documentation | FirstGov(3pm) |
NAME¶
WWW::Search::FirstGov - class for searching http://www.firstgov.govSYNOPSIS¶
use WWW::Search; my $search = new WWW::Search('FirstGov'); # cAsE matters my $query = WWW::Search::escape_query("uncle sam"); $search->native_query($query); while (my $result = $search->next_result()) { print $result->url, "\n"; }
DESCRIPTION¶
Class specialization of WWW::Search for searching http://www.firstgov.gov. FirstGov.gov can return up to 100 hits per page. This class exports no public interface; all interaction should be done through WWW::Search objects.OPTIONS¶
The following search options can be activated by sending a hash as the second argument to native_query().Result Set Partitioning¶
- { 'begin_at' => '100' }
- Retrieve results starting at 100th match.
- { 'offset' => '100' }
- If 'act.next.x' and 'act.next.y' options are set, retrive
results starting at the 100th plus 1 plus the value of the 'nr' option. If
'act.prev.x' and 'act.prev.y' options are set, retrive results starting at
the 100th plus 1 less the value of the 'nr' option.
- { 'act.next.x' => '1', 'act.next.y' => '1' }
- Retrieve next set of results, starting at the value of the
'offset' option plus 1 plus the value of the 'nr' option.
- { 'act.prev.x' => '1', 'act.prev.y' => '1' }
- Retrieve previous set of results, starting at the value of
the 'offset' option plus 1 less the value of the 'nr' option.
- { 'nr' => '40' }
- Retrieve 40 results.
Query Terms¶
From FirstGov.gov documentation: You may have noticed many parameters are suffixed by the number zero (0). This number essentially groups a set of search parameters sharing the same suffix number together to form a query statement. It is possible to link two or more such statements together. You might have guessed that this is accomplished by creating another set of search parameters, this time suffixed by the number one (1) or higher. Just be careful to keep track of parameters and follow the same guidelines as outline above. For example if you have an mw0, have corresponding ms0, mt0, etc. parameters. For each mw1, set its own corresponding ms1, mt1, etc. parameters. Be forewarned that the more complicated the query, the longer it may take to process.- { 'mw0' => 'uncle sam' }
- Return results that contain the words 'uncle' and 'sam'.
- { 'mt0' => 'all' }
- { 'mt0' => 'any' }
- { 'mt0' => 'phrase' }
- WWW::Search::FirstGov defaults the mt0 option to 'all'.
- { 'ms0' => 'should' }
- { 'ms0' => 'mustnot' }
- { 'ms0' => 'must' }
- WWW::Search::FirstGov defaults the ms0 option to 'must'.
- { 'in0' => 'any' }
- { 'in0' => 'title' }
- { 'in0' => 'url' }
- Note: The value 'anywhere' was used in place of 'any' in a
past version of FirstGov.gov's search engine. The value 'home' used in a
past version of FirstGov.gov's search engine is obsolete.
- { 'in0' => 'domain', 'dom0' => 'doc.gov noaa.gov', 'domToggle' => ' +(' }
- { 'in0' => 'domain', 'dom0' => 'doc.gov noaa.gov', 'domToggle' => ' -(' }
- The query is limited to searching the doc.gov and noaa.gov
domains when the doToggle option is set to ' +(' (note leading space). The
query is limited to searching all but the doc.gov and noaa.gov domains
when the doToggle option is set to ' -(' (note leading space).
- { 'rs' => '1' }
- Results will include variations (example: vote, voting).
- { 'doc' => '' }
- { 'doc' => 'text/html' }
- { 'doc' => 'application/pdf' }
- { 'doc' => 'text/xml' }
- { 'doc' => 'application/msword' }
- { 'doc' => 'application/vnd.ms-excel' }
- { 'doc' => 'application/vnd.ms-powerpoint' }
- { 'doc' => 'text/plain' }
- Restrict results to a type of document.
- { 'age' => 'any' }
- { 'age' => '1m' }
- { 'age' => '3m' }
- { 'age' => '6m' }
- { 'age' => '9m' }
- { 'age' => '1y' }
- Restrict results to date document was updated.
- { 'sop' => '<', 'siz' => '512', 'byt' => 'b' }
- Restrict results to documents less than 512 bytes.
- { 'lang' => '' }
- The query is not limited by language.
Specifying Federal and/or State Government Databases¶
- { 'db' => 'www' }
- Note: The db and st options have been merged into the the
db option in the current version of FirstGov.gov's search engine. The
value 'states' now specifies searches against all states.
Result Presentation¶
- { 'rn' => '2' }
- Request FirstGov.gov to return pages using affiliate #2's
page format.
- { 'srt' => '' }
- Sort results by relevance (FirstGov.gov's default).
- { 'dsc' => 'det' }
- { 'dsc' => 'sum' }
- Whether ('det') or not ('sum') to highlight search terms in result summaries.
Other Options¶
- { 'parsed' => 'true' }
- The default behavior for FirstGov.gov's search engine is to parse all search requests, and, if any options are missing or deprecated, rewrite the options and redirect the browser back to FirstGov.gov. When the parsed option is set to "true", FirstGov.gov does not perform this action.
- { 'sp' => '1' }
- Check spelling of the query terms. FirstGov.gov will return
a message and a resubmit buttion if it finds misspelled query terms.
- { 'submit' => 'Search' }
- Submit button.
- { 'md' => 'adv' }
- Function is unknown.
SEE ALSO¶
To make new back-ends, see WWW::Search, or the specialized AltaVista searches described in options. An email list is for notifying users of updates to Perl's WWW::Search::FirstGov module is avilalable at http://two.pairlist.net/mailman/listinfo/www-search-firstgov . It is meant to be a very low volume list that only notifies users when there is a new version of the module available, and possibly when changes to the FirstGov search engine have broken the latest version of the module.HOW DOES IT WORK?¶
"native_setup_search" is called before we do anything. It initializes our private variables (which all begin with underscores) and sets up a URL to the first results page in "{_next_url}". "native_retrieve_some" is called (from "WWW::Search::retrieve_some") whenever more hits are needed. It calls the LWP library to fetch the page specified by "{_next_url}". It parses this page, appending any search hits it finds to "{cache}". If it finds a ``next'' button in the text, it sets "{_next_url}" to point to the page for the next set of results, otherwise it sets it to undef to indicate we're done.SUPPORT¶
Send questions, comments, suggestions, and bug reports to <dsutch@doc.gov>. To be notified of updates to WWW::Search::FirstGov, subscribe to the update notification list at http://two.pairlist.net/mailman/listinfo/www-search-firstgovAUTHOR¶
"WWW::Search::FirstGov" is written and maintained by Dennis Sutch - <dsutch@doc.gov>.LEGALESE¶
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.BUGS¶
None reported.VERSION HISTORY¶
1.14 2003-04-08 - Updated parsing.Documented new search parameters. 1.13 2002-06-04 - Updated Makefile.PL to reflect requirement for WWW::Search version 2.33.
Rewrote tests to use WWW::Search::Test. 1.12 2002-06-03 - Updated to reflect changes to FirstGov (on 2002 Jun 03 they switched to a new search engine built by Fast Search & Transfer of Oslo, Norway).
* The native_query options 'fr' and 'st' are obsolete.
* the native_query option 'in0' now accepts the value 'any' instead of 'anywhere', and the value of 'home' is obsolete.
Removed redefined WWW::Search functionality. 1.11 2002-03-13 - Upated to reflect changed FirstGov search engine parameters.
approximate_result_count() now returns 1 more than the result count when FirstGov's result count is "more than X relevant results".
Changed test case 4 (in test.pl) to finish sooner. 1.10 2002-03-05 - Updated to handle new FirstGov search engine format and to use HTML::TreeBuilder.
Fixed problem that caused one too many searches against FirstGov.gov.
Documented additional options, including adding notes from FirstGov.gov documentation. 1.04 2001-07-16 - Fixed parsing problem. 1.03 2001-03-01 - Removed 'require 5.005_62;'. 1.02 2001-03-01 - Removed 'my' declarations for package variables. 1.01 2001-02-26 - Fixed problem with quoted sring on MSWin.
Removed 'our' declarations. 1.00 2001-02-23 - First publicly-released version.
2011-11-02 | perl v5.12.4 |