ADSWWW PERL library

version 0.9 (20 Novermber 2001)

Please Notice: as of November 2001, support for this library has been discontinued, although the existing functionality is expected to work for the forseeable future. If possible, we suggest you use the Astro::ADS PERL module instead.

The adswww library provides a simple yet powerul set of PERL functions implementing an API allowing to easily acces the ADS services through the HTTP protocol. Please note that even though the library was designed to run under PERL 4.036, it will run under PERL 5 as well, provided that the PERL include files are available somewhere on your system (by default PERL 5 does not create nor install them). More functionality command-line interface options will be implemented based on our user's requests and as time permits.

The latest version can be downloaded by selecting this link. Please drop me a note if you start using this so I can keep track of who needs to be notified when things do change.

Description of library functions
Library changes
Application changes

Description of library functions

The current package includes the following functions:

abstract_fields: Returns an initialized associative array containing the search and auxiliary fields used by the ADS WWW/CGI interface. They consist of 5 basic search fields, 28 fields used to control the query logic and weighting, and 8 fields used to define search parameters such as date range, publication set, and database.
abstract_query: Performs a fielded free-text query to the ADS WWW abstract service and returns the resulting output (an HTML or plaintext document). The input parameter is an associative array containing keyword - value pairs for the fields used by the ADS abstract service.
bib_query: Performs a bibcode query to the ADS WWW abstract service and returns the resulting output (an HTML or plaintext document). The input parameter is an associative array containing keyword - value pairs for the fields used by the ADS bibcode query script.
data_query: Performs a data query to the ADS WWW abstract service, and returns the resulting output (an HTML or plaintext document). The input parameter is an associative array containing keyword - value pairs for the fields used by the ADS data query script.
parse_bib: Parses the results of a list of bibliographies in "refer"-like format, and returns the list of bibcodes found. If input paramenters are supplied, the subroutine will also set the contents of associative arrays for the different fields specified in the bibliographic entries.
parse_items: Parses the available items out of the generic tagged bibliographic format %I tag and returns an associative array containing the item tags as keys and the item descriptions as values. Useful for creating HTML documents with links to the different items that the ADS abstract service has available for its bibliographies.
wais2ads: Parses a (possibly fielded) WAIS query, throws away items which cannot be translated into an ADS fielded query (because they're not implemented), and translates the rest of the query into keyword-value pairs as used by the ADS abstract server.
html_encapsulate: Strips off header and footer markup from an HTML page and translates relative URLs embedded in the page into absolute ones so that the resulting document can be safely encapsulated into another HTML page.

Library Changes

Library changes since version 0.8

No new functionality introduced; the major change in version 0.9 is the use of the standard LWP library as the underlying WWW client interface. You can get the latest version of the LWP library from either the project's home page or from the CPAN archive.

Library changes since version 0.7

Localized some variables in subroutines that were left global by mistake. Changed HTTP method to a GET (was originally a POST) to allow increased logging on the server side (very useful when debugging problems).
Added default fields used in object queries, and increased version number to allow older versions of the library to be backwards compatible. Object queries are now by default resolved by both SIMBAD and NED.

Library changes since version 0.6

Removed obsolete query parameters for an abstract search and replaced with new ones selecting the logic to be used for the query.
Added comment field parameters in associative array used in abstract queries.
Localized library-specific functions into low-level routines so that we can prepare for the use of libwww-perl5 (or other PERL www library).
Implemented iterative URL retrieval upon redirection response from server.
Added parsing of tagged items returned by portable format via library function parse_items.

Library changes since version 0.5

Added new fields and settings into associative arrays used to compose an ADS query to reflect changes in hte query interface.
Reworked and improved loginc in function wais2ads by introducing use of true boolean operators within fields and between fields.
Introduced the name or ip address of the ADS server as a new parameter to be set at configuration time.
Introduced new parameter in the call to wais2ads allowing the user to specify the mapping between input wais fields and ads search fields.

Library changes since version 0.4

Global variables in the package containing the number of references selected, the number returned, and the starting reference sequence number are now set when the result of an abstract query is parsed by the function parse_bib. Please see application adsquery.pl for an example of how this information can be used (requested by Dave Denton, <dave@mom.spie.org>).
The code in function wais2ads was changed so that free-text (non-fielded) searches are translated into searches on the ADS author and abstract fields, providing better scoring in general and removing obsolete NASA/STI keywords queries.
Added parsing of new object tag in bib_parse, fixed eval statements in function to work under PERL5.
The library now includes the required packages from libwww-perl by default, so that applications need only contain the line
```
require 'adswww.pl';
```
at the beginning of the file.
The library user is now kindly asked to insert his/her email address in the $EMAIL variable on top of file adswww.pl during installation. This email address is inserted in all queries made to our server, so that we can keep track of who is making use of this code.
Note: we are not doing this to police or restrict access to our system, but rather to be able to keep statistics and information on who is using our library so that when something in our interface changes we can notify you.

Application changes

Applications changes since version 0.7

None.

Applications changes since version 0.6

cdsbib.pl: Added support for comment searches now that a comment index esists on the ADS server.
Generalized and cleaned up code dealing with mapping of parameters from the interface used at the CDS and the one used by the ADS search engine.
Implemented bibcode query.

citations.pl: Initial revision.

Applications changes since version 0.5

cdsbib.pl: First stab at the implementation of a CGI script that emulates the capabilities of the existing CDS bibliographic service. To be considered as a prototype demo only. To see how it works, follow this link.

Applications changes since version 0.4

adsquery.pl: Added loop to allow multiple retrievals of references by increasing a counter based on values returned in the $ads'ref_selected, $ads'ref_returned, and $ads'ref_start variables.
Added command line option -totref allowing the user to specify the number of references to be retrieved.
Added verbose comments, printouts to make the code developer-friendly.

bibquery.pl

Now passing an additional argument to ads'bib_query to return (astronomical) object names found in reference.
Fixed a different typo in call to ads'bib_query
bibquery.pl: Now passing an additional argument to ads'bib_query to return (astronomical) object names found in reference.
Fixed a different typo in call to ads'bib_query

Alberto Accomazzi
NASA Astrophysics Data System