AutoSearch -- a web-searching application
AutoSearch [-n QueryName] [-q query] [-f FilterRegexp] [-s] qid
AutoSearch qid
AutoSearch performs a web-based search and puts the results set in qid/index.html. Subsequent searches (i.e., the second form above) AutoSearch determine the changes (if any) there were to the results set. These incremental changes are recorded in qid/YYYYMMDD.html. AutoSearch is amenable to be run as a cron job because all the input parameters are saved in the web pages. AutoSearch can act as a automated query agent for a particular search. The output files are designed to be a set of web pages to easily display the results set with a web browser.
The query identifer specifies the directory directory in which all the files that relate to this query and search results will live.
-s
Show search statistics: the query string, number of hits, number of filtered hits, filter string, number of suspended (deleted) hits, previous set size, current set size.
-n
Specify the query name. The query name is used to construct the web page. The query name is used as a heading for the web pages and should be a 'nice' looking version of the query string.
-q
Specify the query string. The query string is the character string which will be submitted to the search engine. You may include special characters to group or to qualify the search.
-f
Specify the URL filter regular expression. This option specifies a regular expression of URLs to remove from the results. If the results pages are publically available (and indexed), they should be filtered out of the results with this option.
AutoSearch submits a query to a search engine, produces HTML pages that reflect the set of 'hits' (filtered search results) returned by the search engine, and tracks these results over time. The URL and title are displayed in the qid/index.html, the URL, the title, and description are displayed in the 'weekly' files.
To organize these results, each search result is placed in a query information directory (qid). The directory becomes the search results 'handle', an easy way to track a set of results. Thus a qid of /usr/local/htdocs/lsam/autosearch/load_balancing might locate the results on your web server at http://www.isi.edu/lsam/autosearch/load_balancing.
/usr/local/htdocs/lsam/autosearch/load_balancing
http://www.isi.edu/lsam/autosearch/load_balancing
Inside the qid directory you will find files relating to this query. The primary file is index.html, which reflects the latest search results. Every not-filtered hit for every search is stored in index.html. When a hit is no longer found by the search engine they a removed from index.html. As new results for a search are returned from the search engine they are placed in index.html.
At the bottom of index.html, there is a heading "Weekly Search Results", which is updated each time the search is submitted (see "AUTOMATED SEARCHING"). The list of search runs is stored in reverse chronological order. Runs which provide no new information are identified with
No Unique Results found for search on <date>
Runs which contain changes are identified by
Web search results for search on <date>
which will be linked a page detailing the changes from that run.
Detailed search results are noted in weekly files. These files are named YYYYMMDD.html and are stored in the qid directory. The weekly files include THE URL, title, and a the description (if available). The title is a link to the original web page.
Cron(1) may be used to establish periodic searches and the web pages will be maintained by AutoSearch. To establish the first search, use the first example under SYNOPSIS. You must specify the qid, query name and query string. If any of the items are missing, you will be interactively prompted for the missing item(s).
Once the first search is complete you can re-run the search with the second form under SYNOPSIS. A cron entry like:
0 3 * * 1 /nfs/u1/wls/AutoSearch.pl /www/div7/lsam/autosearch/caching
might be used to run the search each Monday at 3:00 AM. The query name and query string may be repeated; but they will not be used. This means that with a cron line like:
0 3 * * 1 /nfs/u1/wls/AutoSearch.pl /www/div7/lsam/autosearch/caching -n caching -q caching
a whole new search series can be originated by
rm -r /www/div7/lsam/autosearch/caching
However, the only reason to start a new search series would be to throw away the old weekly files.
We don't recommend running searches more than once per day, but if so the per-run files will be updated in-place. Any changes are added to the page with a comment that "These were recently added:"; and deletions are marked with "These were recently suspended:."
The basic format of these two pages is simple and customizable. The only requirement is that the basic structure remain unchanged. HTML comments are used to identify sections of the document. Almost everything can be changed except for the strings which identify the section starts and ends.
Noteworthy tags and their meaning:
The text contained within this tag is placed at the top of the output page. If the text contains AutoSearch WEB Searching, then the query name will replace it. If the text does not contain this magic string and it is the first ever search, the user will be asked for a query name.
The text contained between the braces is the query string. This is how AutoSearch maintains the query string. You may edit this string to change the query string; but only in qid/index.html. The text ask user is special and will force AutoSearch to to request the search string from the user.
The text contained between the braces is the URL filter. This is how AutoSearch maintains the filter. Again you may edit this string to change the query string; but only in qid/index.html. The text ask user is special and will force AutoSearch to ask the user (STDIN) for the query string. When setting up the first search, you must edit first_index.html, not qid/index.html. The URL filter is a standard perl5 regular expression. URLs which do not match will be kept.
The text contained within this tag is placed at the bottom of the output page. There is no magic string in the bottom text. It's just a place to locate navigation, page owner information, etc.
The remainder of the tags fall into a triplet of ~Heading, ~Template, and ~. Where ~ is Summary, Weekly, Appended, and Suspended. The sub-sections appear in the order given. To produce a section AutoSearch outputs the heading, the template, the section, n copies of the formatted data, and an /section. The tags and their function are:
The heading tag identifies the heading for a section of the output file. The SummaryHeading is for the summary portion, etc. The section may be empty (e.g., Suspended) and thus no heading is output.
The template tag identifies how each item is to be formatted. Simple text replacement is used to change the template into the actual output text. The text to be replaced is noted in ALLCAPS.
This tag is used to locate the section (Summary, Weekly, etc.). This section represents the actual n-items of data.
You can edit these values in the qid/index.html page of an existing search. The file first_index.html (in the directory above qid) will be used as a default template for new queries.
optional file to determine the default format of the index.html file of a new query.
optional file to determine the default format of the YYYYMMDD.html file for a new query.
latest search results and reverse chronological list of periodic searches.
file used as a template for the YYYYMMDD.html files.
summary of changes for a particular date (AKA 'Weekly' file).
Optional files first_index.html and first_date.html are used for the initial search as a template for qid/index.html and date.html, respectively. If either of these files does not exist; a default-default template is stored within the AutoSearch source. The intention of these two files is to permit a user to establish a framework for a group of search sets which have a common format. By leaving the default query name and query string alone, they will be overridden by command line inputs.
For the library, see WWW::Search, for the perl regular expressions, see perlre.
Wm. L. Scheding
AutoSearch is a re-implementation of an earlier version written by Kedar Jog.
There are no bugs, so don't look for them.
1 POD Error
The following errors were encountered while parsing the POD:
Deleting unknown formatting code U<>
To install WWW::Search, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Search
CPAN shell
perl -MCPAN -e shell install WWW::Search
For more information on module installation, please visit the detailed CPAN module installation guide.