Biblio::Refbase

From refbase

Biblio::Refbase is a Perl module available at CPAN that implements an object-oriented interface to refbase sites.

The module is written and maintained by Henning Manske, Hamburg State and University Library.

1 Synopsis
2 Documentation
3 Author
4 Copyright and license

Synopsis

The sections gives a brief overview on how to query a refbase database and how to upload/import data to a refbase database. For a detailed description, please see the full module documentation. The "Examples" section includes a short tutorial and working code snippets.

Setup a new Biblio::Refbase instance:


 use Biblio::Refbase;

 $refbase = Biblio::Refbase->new(
   'url'      => 'http://beta.refbase.net/',
   'user'     => 'guest@refbase.net',
   'password' => 'guest',
 );

Search a refbase database (where the keywords field contains "baltic sea") and return found records as formatted citations using the "Chicago" citation style:


 $response = $refbase->search(
   'keywords' => 'baltic sea',  # Search in keywords.
   'style'    => 'Chicago',     # Set citation style.
 );
 if ($response->is_success) {   # All methods from
   if ($response->hits) {       # HTTP::Response
     print $response->content;  # available.
   }
   else {
     print 'Nothing found!';
   }
 }
 else {
   print 'An error occurred: ', $response->status_line;
 }
 print "\n\n";

Upload two records from arXiv.org via their arXiv IDs, and return the imported records in BibTeX format:


 $response = $refbase->upload(
   'user'       => 'user@refbase.net',  # Switch user for
   'password'   => 'user',              # this request.
   'show'       => 1,                   # Return records
   'format'     => 'BibTeX',            # in BibTeX format.
   'source_ids' => [                    # Upload records
     'arXiv:cs/0106057',                # from arXiv.org
     'arXiv:cond-mat/0210361',          # via source IDs.
   ],
 );
 if ($response->is_success) {
   print 'Number of records imported: ', $response->rows   , "\n";
   print 'ID range of records: '       , $response->records, "\n";
   print "Records:\n\n",  $response->content;
 }

Upload records by supplying a string of content (e.g. BibTeX data or any other supported import format):


 $response = $refbase->upload('content' => $content);
 if ($response->is_success) {
   print $response->content, "\n";
 }

[edit]

Documentation

Please see also the module's POD documentation at CPAN.

[edit]

Constructor

$refbase = Biblio::Refbase->new(%options);: Creates a new Biblio::Refbase instance and returns it.

Key/value pair arguments set up the initial state. All arguments are optional and define instance-wide default parameters for the method calls that follow. With the exception of 'ua' these defaults can be overridden on demand by method calls.

For missing parameters this module will either fall back to its own static default values or let the targeted refbase site decide.

These are the default values used by this module:


 Key        Default             Comment
 --------------------------------------------------------------
 url        http://localhost/   base URL of a refbase site
 user       user@refbase.net
 password   start
 relogin    1                   relogin if session gets invalid
 format     ASCII               output format
 ua         (create new)        LWP::UserAgent object for reuse

The other available keys are:


 Key        Comment
 ------------------------------------
 style      citation style
 order      sort order of records
 rows       maximum number of records
 records    selection of record IDs

See "Accessors" section for further description.

Unless the key 'ua' contains an instance of LWP::UserAgent, any additional entries in the %options hash will be passed unmodified to the constructor of LWP::UserAgent, which is used for performing the requests.

E.g. you can set your own user agent identification and specify a timeout this way:


 $refbase = Biblio::Refbase->new(
   'agent'   => 'My Refbase Client',
   'timeout' => 5,
 );

$refbase = Biblio::Refbase->new($url); $refbase = Biblio::Refbase->new($url, %options);: If the constructor is called with an uneven parameter list the first element will be taken as the base URL:


 $refbase = Biblio::Refbase->new('http://localhost:8000/');

[edit]

Accessors

The accessors are combined getter/setter methods. Used as setter the instance will be returned, so setters can be chained. Example:


 $refbase->format('atom')->style('chicago');

$refbase = $refbase->url($url);: Sets the default base URL of a refbase site. A trailing slash and the scheme will be automatically added if omitted, i.e. these calls will result in the same URL:


 $refbase->url('http://beta.refbase.net/');
 $refbase->url('http://beta.refbase.net');
 $refbase->url('beta.refbase.net');

The module's built-in default value for the base URL is 'http://localhost/'.
$url = $refbase->url;: Returns the current default base URL for this instance.
$refbase->user;: Returns/sets the default user name. The module's default user is 'user@refbase.net'.
$refbase->password;: Returns/sets the default password. The module's default password is 'start'.
$refbase->relogin;: Returns/sets the default value for automatic relogin. If a user session has expired, the instance will try to relogin for as many times as set via this accessor. A value of 0 disables the relogin feature. An undefined value lets the instance use the module's default value of 1.
$refbase->format;: Returns/sets the default output format. The actual availability of a format depends on the version of the targeted refbase installation.

This module should always know all output formats provided by the current refbase software release.

Setting an unknown format lets the module croak. The module's default format is 'ASCII'.

The known formats are:


  ADS
  ASCII
  Atom XML
  BibTeX
  Endnote
  HTML
  ISI
  LaTeX
  LaTeX .bbl
  Markdown
  MODS XML
  OAI_DC XML
  ODF XML
  PDF
  RIS
  RTF
  SRW_DC XML
  SRW_MODS XML
  Word XML

Case is ignored by the setter, the 'XML' appendices are optional and 'LaTeX .bbl' can also be written as 'LaTeX_bbl'. I.e. these statements set the same format:


 $refbase->format('MODS XML');
 $refbase->format('mods');

Calling the formats method returns a list of the known output formats.
$refbase->style;: Returns/sets the default citation style. The actual availability of a style depends on the version of the targeted refbase installation.

This module should always know all citation styles provided by the current refbase software release.

Setting an unknown style lets the module croak.

The known styles are:


 AMA
 Ann Glaciol
 APA
 Chicago
 Deep Sea Res
 Harvard 1
 Harvard 2
 Harvard 3
 J Glaciol
 Mar Biol
 MEPS
 MLA
 Polar Biol
 Text Citation
 Vancouver

Whitespace and case are ignored by the setter, i.e. these statements set the same style:


 $refbase->style('Deep Sea Res');
 $refbase->style('deepseares');

Calling the styles method returns a list of the known citation styles.
$refbase->order;: Returns/sets the default sort order for this instance.

refbase's internal default sort order is first by author fields, then year, then title. This order is changed if one of the following values is provided:


 Value           Sort order
 ------------------------------------------------------
 year            year, then author and title
 type            type and thesis type, then default way
 type-year       type, thesis, year, author, title
 creation-date   date of creation, date of modification

$refbase->rows;: Returns/sets the default value for the maximum number of records to be returned by a query.
$refbase->records;: Returns/sets the default record ID selection/range limiting subsequent queries. IDs are separated by non-digits. A minus sign between two IDs defines a range. The following statement sets a default selection of record ID 1 and all IDs from 5 to 8:


 $refbase->records('1,5-8');

$refbase->ua;: Returns/sets the LWP::UserAgent object used by this instance for performing HTTP requests.

[edit]

Methods

$response = $refbase->search(%args);: Searches a refbase database.

With the exception of 'ua' each instance-wide configurable value can also be defined on a per-request basis (and thus will override any given default).

See "Accessors" section for further description of these arguments:


 url        relogin   order
 user       format    rows
 password   style     records

The following keys correspond to fields in the refbase database:


 author            Author
 title             Title
 type              Type
 year              Year
 publication       Publication
 abbrev_journal    Abbreviated Journal
 keywords          Keywords
 abstract          Abstract
 thesis            Thesis
 area              Area
 notes             Notes
 location          Location
 serial            Serial (ID)
 date              Creation date
 contribution_id   Contribution ID

The 'date' key requires a date string in the format 'YYYY-MM-DD'. The other fields can be searched with MySQL regular expressions. For further details look at section 'Search syntax' in the refbase documentation.

Field independent search arguments are:


 query       combination of searched fields: 'and' (default) or 'or'
 start       offset of the first search result, starting with 1

Special output options for ASCII/HTML format:


 showquery   show SQL statement if set to 1 (ASCII only)
 showlinks   don't show links column if set to 0 (HTML only)
 view        view type (HTML only): 'Web', 'Print' or 'Mobile'

Refer to "Examples" section for a short tutorial and working code snippets.
$response = $refbase->upload(%args);: Imports/uploads records to a refbase database.

As with the search method, all instance-wide configured values can be overriden on a per-request basis (except 'ua'). See search method and "Accessors" section.

The upload method requires one of these two keys to be present in the arguments hash:


 content      a string containing records in a format known by refbase
 source_ids   a string or list of record IDs recognized by refbase

The 'source_ids' can be supplied either as a string of IDs separated by blanks or as a reference to an array. If both keys are present, 'content' will be used and 'source_ids' will be ignored.

Optional keys are:


 skipbad   skip unrecognized records if set to a true value
 only      record numbers/range to be imported from the source
 show      immediate search for the records imported by this call
           if set to a true value

If 'show' is set to a true value or any search field parameters (see search method) are present, the method call will perform a search request after importing. The search request will automatically set the record selection to the new IDs of the freshly imported records (overridable by 'records' key) and the maximum number of records to the number of records that have been imported (overridable by 'rows' key). I.e. if 'show' is true and no search field parameters are set, the upload method will return all imported records (in the desired/default format and style).

Refer to "Examples" section for a short tutorial and working code snippets.
$response = $refbase->upload($content, %args);: If the constructor is called with an uneven arguments list the first element will be taken as 'content'.
$boolean = $refbase->ping;: Checks if configured base URL is accessible.

[edit]

Static methods

@formats = $refbase->formats; @formats = Biblio::Refbase->formats;: Returns a list of available output formats known by this module.
@styles = $refbase->styles; @styles = Biblio::Refbase->styles;: Returns a list of available citation styles known by this module.

[edit]

Response accessor methods

The search and upload methods return $response objects. A $response object is a formerly instance of HTTP::Response that has been re-blessed into the package Biblio::Refbase::Response. This package subclasses HTTP::Response and extends it by three fields and the corresponding accessors. No methods are overridden.

$response->hits;: Indicates the success of a search request:


   1     search has found some records
   0     search has found nothing
 undef   search has failed

$response->rows;: Returns the number of records that have been imported by an upload request.
$response->records;: Returns the record ID range of the imported records, i.e. the first ID and the last ID of the new records (joined by the minus sign). Or a single ID, if only one record has been imported.

See the documentation of HTTP::Response for the methods inherited from the base class.

[edit]

Examples

First, a very simple example that will just perform a search without applying any user parameters applied:


 $refbase  = Biblio::Refbase->new;   # create new instance
 $response = $refbase->search;       # search with defaults
 $content  = $response->content;     # store content

If there's an unmodified out-of-the-box installation of refbase at localhost, $content should now contain 5 records in ASCII format.

You should check the status of the $response object before processing the content. All accessors known from HTTP::Response are available plus the accessors added by this module:


 if ($response->is_success) {
   if ($response->hits) {            # hits is special to this module
     print "Found something!\n";
     $content = $response->content;
   }
   else {
     print "Found nothing!\n";
   }
 }
 else {
   print 'An error occurred: ', $response->status_line, "\n";
   $http_code = $response->code;
   $message   = $response->message;
 }

Let's provide the $refbase object with connection parameters to access the official beta refbase site:


 $refbase->url('http://beta.refbase.net/');
 $refbase->user('guest@refbase.net');
 $refbase->password('guest');

If you want you can chain the accessors:


 $refbase->url('http://beta.refbase.net/')
         ->user('guest@refbase.net')
         ->password('gest');

In the chained accessors example there was an intentional typo: The password is wrong. This module will 'cast' the original response from refbase (which redirects to a login page) to one having the appropriate UNAUTHORIZED status code set and a short message 'Login request denied':


 if (($response = $refbase->search)->is_error) {
   print 'An error occurred: ', $response->status_line, "\n";
 }

More examples will be included in the next releases of this module. Please refer to the "Synopsis" section for now.

[edit]

Bugs and limitations

This module is ALPHA status. Interface and features could change. Documentation and test suite are still incomplete. Some search options have been omitted in this release.

[edit]

Author

Henning Manske, Hamburg State and University Library.

[edit]

Copyright and license

This module is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html.

This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Retrieved from "http://www.refbase.net/index.php/Biblio::Refbase"

Categories: Usage

Biblio::Refbase

From refbase

Contents

Synopsis

Documentation

Constructor

Accessors

Methods

Static methods

Response accessor methods

Examples

Bugs and limitations

See also

Author

Copyright and license

Views

Personal tools

Search

Toolbox