NAME
WWW::Search::FirstGov - class for searching http://www.firstgov.gov
SYNOPSIS
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.
This option is not passed to FirstGov.gov. Instead, this option is used to set 'fr', 'act.next.x' and 'act.next.y' options to obtain results starting the requested starting point.
- { 'fr' => '100' }
-
Retrieve results starting at the 100th match, when 'act.next.x' and 'act.next.y' options are set. Otherwise results start at the 100th less the value of the 'nr' option.
Note: Do not use this option. Use the 'begin_at' option instead.
- { 'act.next.x' => '1', 'act.next.y' => '1' }
-
Retrieve next set of results, starting at the value of the 'fr' option plus the value of the 'nr' option.
Note: Do not use this option.
- { 'act.prev.x' => '1', 'act.prev.y' => '1' }
-
Retrieve previous set of results, starting at the value of the 'fr' option less the value of the 'nr' option.
Note: Do not use this option.
- { 'nr' => '40' }
-
Retrieve 40 results.
FirstGov.gov returns no more than 100 results at a time. In addition, when the 'nr' option is set to 100, FirstGov.gov treats the 'de' paramater as if it is set to 'brief', returning results without descriptions.
From FirstGov.gov documentation:
The Number of Results parameter (nr) allows you or the user to set how many search "hits" appear on each search results page. If this parameter is not used, nr is defaulted to 10.
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'.
The native_query() method sets this option.
Note: Do not use the 'mw0' option, instead use the native_query() method and the 'mw1', 'mw2', ... options.
From FirstGov.gov documentation:
The Main Words parameter is represented by the input field named mw0. This is a text input field that allows a user to enter the word or words they would like to search for.
- { 'mt0' => 'all' } =item { 'mt0' => 'any' } =item { 'mt0' => 'phrase' }
-
From FirstGov.gov documentation:
The Main Type field (mt0) is used to specify how you want to search for the words entered in the mw0 field. You can search for documents containing all the words provided, any of the words provided, or documents containing the exact phrase in the order the words are entered. This is done by setting the mt0 field to "all", "any", or "phrase". If this field is not provided, it is defaulted to "all".
- { 'ms0' => 'should' } =item { 'ms0' => 'mustnot' }
-
From FirstGov.gov documentation:
Main Sign field (ms0) further specifies your search. It can be used to specify whether words should or must not be present in the document. This is done by setting the ms0 field to "should" or "mustnot". If this field is not provided, it is defaulted to "should".
- { 'in0' => 'anywhere' } =item { 'in0' => 'home' } =item { 'in0' => 'title' }
-
From FirstGov.gov documentation:
The In parameter (in0) can be implemented to tell the search engine where specifically to search. Setting in0 to "anywhere" searches the complete web page of all web pages in a particular database. Setting in0 to "home" searches only the home pages of websites in a particular database. Setting in0 to "title" searches only the Titles of web pages of a particular database.
- { 'in0' => 'title', 'dom0' => 'doc.gov' }
-
The query is limited to searching the doc.gov domain.
From the FirstGov.gov documentation:
Setting in0 to "domain" allows you to search only a certain domain or domains, or domain/path combinations. Use of this attribute also requires an additional parameter, the Domain parameter (dom0). The Domain parameter (dom0), when used with in0="domain", allows searching of specific domains or domain/path combinations as described above. This is useful if you want a "site search" for your website. To do this, you could set in0 to domain and then dom0 to yourdomain.com. This would ensure that users are only searching web pages within your domain. In fact, you may specify as many domain or domain/path combinations up to 20 that you would like to limit your searches to. You can use any combination of domains or domain/path elements as long as they are separated by a comma or a space.
- { 'pl' => 'domain', 'domain' => 'osec.doc.gov+itd.doc.gov' }
-
The query is limited to searching the domains osec.doc.gov and itd.doc.gov.
These parameters are no longer used by FirstGov.gov. FirstGov.gov currently accepts these parameters, but converts them to 'in0' and 'dom0' parameters in the forms of returned pages.
Note: It is suggested that these options not be used. Use the 'in0' and 'dom0' options instead.
Specifying Federal and/or State Government Databases
- { 'db' => 'www' }
-
From FirstGov.gov documentation:
The Database field (db) allows you to specify if a search should query Federal Government websites, State Government websites, or both. This is done by setting db to "www" for a Federal Search, setting db to "states" for a State Search, or "www-fed-all" to search both. If you are using the Database field, and allowing the State Search option, it is highly recommended you also provide a State Field. If the db field is not provided, it is defaulted to Federal.
- { 'st' => 'NY' }
-
From FirstGov.gov documentation:
The State field (st) allows you to search for government websites of a specific state or territory. If you are a state agency and want users to only search your state's web pages, set this field to your state's abbreviation from the list provided below. (Be sure to have set the db field to states!) If a state is not selected it will default to search All States (AS). List of State and Territory Abbreviations for FirstGov Searching: AS - All States, AL - Alabama, AK - Alaska, AZ - Arizona, AR - Arkansas, CA - California, CO - Colorado, CT - Connecticut, DC - D.C., DE - Delaware, FL - Florida, GA - Georgia, HI - Hawaii, ID - Idaho, IL - Illinois, IN - Indiana, IA - Iowa, KS - Kansas, KY - Kentucky, LA - Louisiana, ME - Maine, MD - Maryland, MA - Massachusetts, MI - Michigan, MN - Minnesota, MS - Mississippi, MO - Missouri, MT - Montana, NE - Nebraska, NV - Nevada, NH - New Hampshire, NJ - New Jersey, NM - New Mexico, NY - New York, NC - North Carolina, ND - North Dakota, OH - Ohio, OK - Oklahoma, OR - Oregon, PA - Pennsylvania, RI - Rhode Island, SC - South Carolina, SD - South Dakota, TN - Tennessee, TX - Texas, UT - Utah, VT - Vermont, VA - Virginia, WA - Washington, WV - West Virginia, WI - Wisconsin, WY - Wyoming, SA - American Samoa, GU - Guam, MP - Mariana Islands, MH - Marshall Islands, FM - Micronesia, PR - Puerto Rico, VI - Virgin Islands.
Format of Returned Results
- { 'de' => 'detailed' }
-
Request FirstGov.gov to return detailed results.
This option may be set to either 'detailed' or 'brief'. Detailed results contain result numbers, URLs, page titles, and descriptions. Brief results contain result numbers, URLs, and page titles.
When the 'nr' option is set to '100', FirstGov.gov treats the 'de' paramater as if it is set to 'brief', returning results without descriptions.
Note: It is suggested that this option not be used (since this class was developed using detailed results.
From FirstGov.gov documentation:
The Results Format parameter (de) allows you or the user to specify how results will be displayed. Results can be returned with a title and brief summary of the content, or just listing the title of the web page. Use: Simply set the de parameter to "brief" or "detailed". If this parameter is not used, de is defaulted to "detailed".
- { 'rn' => '2' }
-
Request FirstGov.gov to return pages using affiliate #2's page format.
This option is used by FirstGov.gov to return result pages customized with headers and footers for the affiliate as identified by the 'rn' option.
When not set, FirstGov.gov currently sets the 'rn' parameter to '2'.
Note: It is suggested that this option not be used (since this class was developed using results returned with the 'rn' option not set).
From FirstGov.gov documentation:
The Referrer Name (rn) field is used to uniquely identify your affiliate. Each Affiliate, upon registration, is assigned a referrer ID that corresponds to it.
SEE ALSO
To make new back-ends, see WWW::Search, or the specialized AltaVista searches described in options.
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.
AUTHOR
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.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.