{
    "content": [
        {
            "type": "text",
            "text": "# WWW::Search::FirstGov (perldoc)\n\n## NAME\n\nWWW::Search::FirstGov - class for searching http://www.firstgov.gov\n\n## SYNOPSIS\n\nuse WWW::Search;\nmy $search = new WWW::Search('FirstGov'); # cAsE matters\nmy $query = WWW::Search::escapequery(\"uncle sam\");\n$search->nativequery($query);\nwhile (my $result = $search->nextresult()) {\nprint $result->url, \"\\n\";\n}\n\n## DESCRIPTION\n\nClass specialization of WWW::Search for searching http://www.firstgov.gov.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OPTIONS** (5 subsections)\n- **SEE ALSO**\n- **SUPPORT**\n- **AUTHOR**\n- **LEGALESE**\n- **BUGS**\n- **VERSION HISTORY** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "WWW::Search::FirstGov",
        "section": "",
        "mode": "perldoc",
        "summary": "WWW::Search::FirstGov - class for searching http://www.firstgov.gov",
        "synopsis": "use WWW::Search;\nmy $search = new WWW::Search('FirstGov'); # cAsE matters\nmy $query = WWW::Search::escapequery(\"uncle sam\");\n$search->nativequery($query);\nwhile (my $result = $search->nextresult()) {\nprint $result->url, \"\\n\";\n}",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "OPTIONS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "native_query",
                        "lines": 1
                    },
                    {
                        "name": "Result Set Partitioning",
                        "lines": 38
                    },
                    {
                        "name": "Query Terms",
                        "lines": 149
                    },
                    {
                        "name": "Result Presentation",
                        "lines": 26
                    },
                    {
                        "name": "Other Options",
                        "lines": 18
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 19,
                "subsections": []
            },
            {
                "name": "SUPPORT",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "LEGALESE",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "VERSION HISTORY",
                "lines": 9,
                "subsections": [
                    {
                        "name": "approximate_result_count",
                        "lines": 16
                    }
                ]
            }
        ],
        "sections": {
            "NAME": {
                "content": "WWW::Search::FirstGov - class for searching http://www.firstgov.gov\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use WWW::Search;\nmy $search = new WWW::Search('FirstGov'); # cAsE matters\nmy $query = WWW::Search::escapequery(\"uncle sam\");\n$search->nativequery($query);\nwhile (my $result = $search->nextresult()) {\nprint $result->url, \"\\n\";\n}\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "Class specialization of WWW::Search for searching http://www.firstgov.gov.\n\nFirstGov.gov can return up to 100 hits per page.\n\nThis class exports no public interface; all interaction should be done through WWW::Search\nobjects.\n",
                "subsections": []
            },
            "OPTIONS": {
                "content": "The following search options can be activated by sending a hash as the second argument to",
                "subsections": [
                    {
                        "name": "native_query",
                        "content": ""
                    },
                    {
                        "name": "Result Set Partitioning",
                        "content": "{ 'beginat' => '100' }\nRetrieve results starting at 100th match.\n\nThis option is not passed to FirstGov.gov. Instead, this option is used to set 'offset',\n'act.next.x' and 'act.next.y' options to obtain results starting the requested starting\npoint.\n\n{ 'offset' => '100' }\nIf 'act.next.x' and 'act.next.y' options are set, retrieve results starting at the 100th\nplus 1 plus the value of the 'nr' option. If 'act.prev.x' and 'act.prev.y' options are set,\nretrieve results starting at the 100th plus 1 less the value of the 'nr' option.\n\nNote: Do not use this option. Use the 'beginat' option instead.\n\nNote: This option was named 'fr' in a past version of FirstGov.gov's search engine.\n\n{ 'act.next.x' => '1', 'act.next.y' => '1' }\nRetrieve next set of results, starting at the value of the 'offset' option plus 1 plus the\nvalue of the 'nr' option.\n\nNote: Do not use this option.\n\n{ 'act.prev.x' => '1', 'act.prev.y' => '1' }\nRetrieve previous set of results, starting at the value of the 'offset' option plus 1 less\nthe value of the 'nr' option.\n\nNote: Do not use this option.\n\n{ 'nr' => '40' }\nRetrieve 40 results.\n\nFirstGov.gov returns no more than 100 results at a time.\n\nFrom FirstGov.gov documentation:\n\nThe Number of Results parameter (nr) allows you or the user to set how many search \"hits\"\nappear on each search results page. If this parameter is not used, nr is defaulted to 10.\n"
                    },
                    {
                        "name": "Query Terms",
                        "content": "From FirstGov.gov documentation:\n\nYou may have noticed many parameters are suffixed by the number zero (0). This number\nessentially groups a set of search parameters sharing the same suffix number together to form a\nquery statement. It is possible to link two or more such statements together. You might have\nguessed that this is accomplished by creating another set of search parameters, this time\nsuffixed by the number one (1) or higher. Just be careful to keep track of parameters and follow\nthe same guidelines as outline above. For example if you have an mw0, have corresponding ms0,\nmt0, etc. parameters. For each mw1, set its own corresponding ms1, mt1, etc. parameters. Be\nforewarned that the more complicated the query, the longer it may take to process.\n\n{ 'mw0' => 'uncle sam' }\nReturn results that contain the words 'uncle' and 'sam'.\n\nThe nativequery() method sets this option.\n\nWWW::Search::FirstGov defaults the mw0 option to an empty string.\n\nNote: Do not use the 'mw0' option, instead use the nativequery() method and the 'mw1',\n'mw2', ... options.\n\nFrom FirstGov.gov documentation:\n\nThe Main Words parameter is represented by the input field named mw0. This is a text input\nfield that allows a user to enter the word or words they would like to search for.\n\n{ 'mt0' => 'all' }\n{ 'mt0' => 'any' }\n{ 'mt0' => 'phrase' }\nWWW::Search::FirstGov defaults the mt0 option to 'all'.\n\nFrom FirstGov.gov documentation:\n\nThe Main Type field (mt0) is used to specify how you want to search for the words entered in\nthe mw0 field. You can search for documents containing all the words provided, any of the\nwords provided, or documents containing the exact phrase in the order the words are entered.\nThis is done by setting the mt0 field to \"all\", \"any\", or \"phrase\". If this field is not\nprovided, it is defaulted to \"all\".\n\n{ 'ms0' => 'should' }\n{ 'ms0' => 'mustnot' }\n{ 'ms0' => 'must' }\nWWW::Search::FirstGov defaults the ms0 option to 'must'.\n\nFrom FirstGov.gov documentation:\n\nMain Sign field (ms0) further specifies your search. It can be used to specify whether words\nshould or must not be present in the document. This is done by setting the ms0 field to\n\"should\" or \"mustnot\". If this field is not provided, it is defaulted to \"should\".\n\n{ 'in0' => 'any' }\n{ 'in0' => 'title' }\n{ 'in0' => 'url' }\nNote: The value 'anywhere' was used in place of 'any' in a past version of FirstGov.gov's\nsearch engine. The value 'home' used in a past version of FirstGov.gov's search engine is\nobsolete.\n\nFrom FirstGov.gov documentation:\n\nThe In parameter (in0) can be implemented to tell the search engine where specifically to\nsearch. Setting in0 to \"anywhere\" searches the complete web page of all web pages in a\nparticular database. [...] Setting in0 to \"title\" searches only the Titles of web pages of a\nparticular database.\n\n{ 'in0' => 'domain', 'dom0' => 'doc.gov noaa.gov', 'domToggle' => ' +(' }\n{ 'in0' => 'domain', 'dom0' => 'doc.gov noaa.gov', 'domToggle' => ' -(' }\nThe query is limited to searching the doc.gov and noaa.gov domains when the doToggle option\nis set to ' +(' (note leading space). The query is limited to searching all but the doc.gov\nand noaa.gov domains when the doToggle option is set to ' -(' (note leading space).\n\nFrom the FirstGov.gov documentation:\n\nSetting in0 to \"domain\" allows you to search only a certain domain or domains, or\ndomain/path combinations. Use of this attribute also requires an additional parameter, the\nDomain parameter (dom0). The Domain parameter (dom0), when used with in0=\"domain\", allows\nsearching of specific domains or domain/path combinations as described above. This is useful\nif you want a \"site search\" for your website. To do this, you could set in0 to domain and\nthen dom0 to yourdomain.com. This would ensure that users are only searching web pages\nwithin your domain. In fact, you may specify as many domain or domain/path combinations up\nto 20 that you would like to limit your searches to. You can use any combination of domains\nor domain/path elements as long as they are separated by a comma or a space.\n\n{ 'rs' => '1' }\nResults will include variations (example: vote, voting).\n\n{ 'doc' => '' }\n{ 'doc' => 'text/html' }\n{ 'doc' => 'application/pdf' }\n{ 'doc' => 'text/xml' }\n{ 'doc' => 'application/msword' }\n{ 'doc' => 'application/vnd.ms-excel' }\n{ 'doc' => 'application/vnd.ms-powerpoint' }\n{ 'doc' => 'text/plain' }\nRestrict results to a type of document.\n\n{ 'age' => 'any' }\n{ 'age' => '1m' }\n{ 'age' => '3m' }\n{ 'age' => '6m' }\n{ 'age' => '9m' }\n{ 'age' => '1y' }\nRestrict results to date document was updated.\n\n{ 'sop' => '<', 'siz' => '512', 'byt' => 'b' }\nRestrict results to documents less than 512 bytes.\n\nThe attribute sop may be set to '<' or '>'. The attribute 'byt' may be set to 'b', 'kb', or\n'mb'.\n\n{ 'lang' => '' }\nThe query is not limited by language.\n\nTo limit a query to documents of a specific language, set this option to one of FirstGov's\nlanguage abbreviations (an empty string denotes \"Any language\"): af - Afrikaans, sq -\nAlbanian, ar - Arabic, eu - Basque, be - Byelorussian, bg - Bulgarian, ca - Catalan, tzh -\nChinese (trad), szh - Chinese (simp), hr - Croatian, cs - Czech, da - Danish, nl - Dutch, en\n- English, et - Estonian, fo - Faeroese, fi - Finnish, fr - French, fy - Frisian, gl -\nGalician, de - German, el - Greek, he - Hebrew, hu - Hungarian, is - Icelandic, id -\nIndonesian, it - Italian, ja - Japanese, ko - Korean, la - Latin, lv - Latvian, lt -\nLithuanian, ms - Malay, no - Norwegian, pl - Polish, pt - Portuguese, ro - Romanian, ru -\nRussian, sk - Slovak, sl - Slovenian, es - Spanish, sv - Swedish, th - Thai, tr - Turkish,\nuk - Ukrainian, vi - Vietnamese, cy - Welsh\n\nSpecifying Federal and/or State Government Databases\n{ 'db' => 'www' }\nNote: The db and st options have been merged into the the db option in the current version\nof FirstGov.gov's search engine. The value 'states' now specifies searches against all\nstates.\n\nFrom FirstGov.gov documentation:\n\nThe Database field (db) allows you to specify if a search should query Federal Government\nwebsites, State Government websites, or both. This is done by setting db to \"www\" for a\nFederal Search, setting db to \"states\" for a State Search, or \"www-fed-all\" to search both.\n[...] If the db field is not provided, it is defaulted to Federal.\n\nList of State and Territory Abbreviations for FirstGov Searching: AS - All States, AL -\nAlabama, AK - Alaska, AZ - Arizona, AR - Arkansas, CA - California, CO - Colorado, CT -\nConnecticut, DC - D.C., DE - Delaware, FL - Florida, GA - Georgia, HI - Hawaii, ID - Idaho,\nIL - Illinois, IN - Indiana, IA - Iowa, KS - Kansas, KY - Kentucky, LA - Louisiana, ME -\nMaine, MD - Maryland, MA - Massachusetts, MI - Michigan, MN - Minnesota, MS - Mississippi,\nMO - Missouri, MT - Montana, NE - Nebraska, NV - Nevada, NH - New Hampshire, NJ - New\nJersey, NM - New Mexico, NY - New York, NC - North Carolina, ND - North Dakota, OH - Ohio,\nOK - Oklahoma, OR - Oregon, PA - Pennsylvania, RI - Rhode Island, SC - South Carolina, SD -\nSouth Dakota, TN - Tennessee, TX - Texas, UT - Utah, VT - Vermont, VA - Virginia, WA -\nWashington, WV - West Virginia, WI - Wisconsin, WY - Wyoming, SA - American Samoa, GU -\nGuam, MP - Mariana Islands, MH - Marshall Islands, FM - Micronesia, PR - Puerto Rico, VI -\nVirgin Islands.\n"
                    },
                    {
                        "name": "Result Presentation",
                        "content": "{ 'rn' => '2' }\nRequest FirstGov.gov to return pages using affiliate #2's page format.\n\nThis option is used by FirstGov.gov to return result pages customized with headers and\nfooters for the affiliate as identified by the 'rn' option.\n\nWhen not set, FirstGov.gov currently sets the 'rn' parameter to '2'.\n\nNote: It is suggested that this option not be used (since this class was developed using\nresults returned with the 'rn' option not set).\n\nFrom FirstGov.gov documentation:\n\nThe Referrer Name (rn) field is used to uniquely identify your affiliate. Each Affiliate,\nupon registration, is assigned a referrer ID that corresponds to it.\n\n{ 'srt' => '' }\nSort results by relevance (FirstGov.gov's default).\n\nAdditional values are: 8 (Date - ascending), 7 (Date - descending), 6 (Size - ascending),\nand 5 (Size - descending).\n\n{ 'dsc' => 'det' }\n{ 'dsc' => 'sum' }\nWhether ('det') or not ('sum') to highlight search terms in result summaries.\n"
                    },
                    {
                        "name": "Other Options",
                        "content": "{ 'parsed' => 'true' }\nThe default behavior for FirstGov.gov's search engine is to parse all search requests, and,\nif any options are missing or deprecated, rewrite the options and redirect the browser back\nto FirstGov.gov. When the parsed option is set to \"true\", FirstGov.gov does not perform this\naction.\n\n{ 'sp' => '1' }\nCheck spelling of the query terms. FirstGov.gov will return a message and a resubmit buttion\nif it finds misspelled query terms.\n\nNote: WWW::Search::FirstGov does not parse the results for this option.\n\n{ 'submit' => 'Search' }\nSubmit button.\n\n{ 'md' => 'adv' }\nFunction is unknown.\n"
                    }
                ]
            },
            "SEE ALSO": {
                "content": "To make new back-ends, see WWW::Search, or the specialized AltaVista searches described in\noptions.\n\nAn email list is for notifying users of updates to Perl's WWW::Search::FirstGov module is\navilalable at http://two.pairlist.net/mailman/listinfo/www-search-firstgov . It is meant to be a\nvery low volume list that only notifies users when there is a new version of the module\navailable, and possibly when changes to the FirstGov search engine have broken the latest\nversion of the module.\n\nHOW DOES IT WORK?\n\"nativesetupsearch\" is called before we do anything. It initializes our private variables\n(which all begin with underscores) and sets up a URL to the first results page in \"{nexturl}\".\n\n\"nativeretrievesome\" is called (from \"WWW::Search::retrievesome\") whenever more hits are\nneeded. It calls the LWP library to fetch the page specified by \"{nexturl}\". It parses this\npage, appending any search hits it finds to \"{cache}\". If it finds a ``next'' button in the\ntext, it sets \"{nexturl}\" to point to the page for the next set of results, otherwise it sets\nit to undef to indicate we're done.\n",
                "subsections": []
            },
            "SUPPORT": {
                "content": "Send questions, comments, suggestions, and bug reports to <dsutch@doc.gov>.\n\nTo be notified of updates to WWW::Search::FirstGov, subscribe to the update notification list at\nhttp://two.pairlist.net/mailman/listinfo/www-search-firstgov\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "\"WWW::Search::FirstGov\" is written and maintained by Dennis Sutch - <dsutch@doc.gov>.\n",
                "subsections": []
            },
            "LEGALESE": {
                "content": "THIS SOFTWARE IS PROVIDED \"AS IS\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,\nWITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR\nPURPOSE.\n",
                "subsections": []
            },
            "BUGS": {
                "content": "None reported.\n",
                "subsections": []
            },
            "VERSION HISTORY": {
                "content": "1.14 2003-04-08 - Updated parsing. Documented new search parameters. 1.13 2002-06-04 - Updated\nMakefile.PL to reflect requirement for WWW::Search version 2.33. Rewrote tests to use\nWWW::Search::Test. 1.12 2002-06-03 - Updated to reflect changes to FirstGov (on 2002 Jun 03 they\nswitched to a new search engine built by Fast Search & Transfer of Oslo, Norway). * The\nnativequery options 'fr' and 'st' are obsolete. * the nativequery option 'in0' now accepts the\nvalue 'any' instead of 'anywhere', and the value of 'home' is obsolete. Removed redefined\nWWW::Search functionality.\n\n1.11 2002-03-13 - Updated to reflect changed FirstGov search engine parameters.",
                "subsections": [
                    {
                        "name": "approximate_result_count",
                        "content": "is \"more than X relevant results\". Changed test case 4 (in test.pl) to finish sooner.\n\n1.10 2002-03-05 - Updated to handle new FirstGov search engine format and to use\nHTML::TreeBuilder. Fixed problem that caused one too many searches against FirstGov.gov.\nDocumented additional options, including adding notes from FirstGov.gov documentation.\n\n1.04 2001-07-16 - Fixed parsing problem.\n\n1.03 2001-03-01 - Removed 'require 5.00562;'.\n\n1.02 2001-03-01 - Removed 'my' declarations for package variables.\n\n1.01 2001-02-26 - Fixed problem with quoted sring on MSWin. Removed 'our' declarations.\n\n1.00 2001-02-23 - First publicly-released version.\n"
                    }
                ]
            }
        }
    }
}