The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Biblio-Refbase-0.04
River stage zero No dependents
++
/ Biblio::Refbase

NAME

Biblio::Refbase - Perl interface to refbase bibliographic manager

VERSION

This is Biblio::Refbase version 0.0.2, tested against refbase 0.9.5.

SYNOPSIS

  use Biblio::Refbase;

  my $refbase = Biblio::Refbase->new(
    url      => 'http://beta.refbase.net/',
    user     => 'guest@refbase.net',
    password => 'guest',
  );
  my $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";

  $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:
  # $response = $refbase->upload( content => $content );

DESCRIPTION

Biblio::Refbase is an object-oriented interface to refbase Web Reference Database sites.

refbase (http://www.refbase.net/) is a web-based bibliographic manager which can import and export references in various formats (including BibTeX, Endnote, MODS and OpenOffice).

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/');

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.

For more details on the styles and examples refer to page 'Citation styles' (http://www.refbase.net/index.php/Citation_styles) in the refbase documentation.

$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.

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   institutional abbreviation

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' (http://www.refbase.net/index.php/Searching#Search_syntax) in the refbase documentation. For an explanation of the database fields refer to page 'Table refs' (http://www.refbase.net/index.php/Table_refs).

Custom search conditions:

  where       code for SQL WHERE clause

The content of the 'where' key must be valid MySQL code which refbase will insert into the WHERE clause of its internally generated SQL query.

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 and HTML formats:

  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 overridden 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      immediately 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.

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.

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.

EXAMPLES

Searching

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

  $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";
  }

Uploading data to refbase

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

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.

SEE ALSO

AUTHOR

Henning Manske <hma@cpan.org>

ACKNOWLEDGEMENTS

Thanks to Matthias Steffens (info@refbase.net), the creator of refbase, for encouraging feedback, explaining many details, testing this module and commenting on the documentation.

COPYRIGHT AND LICENSE

Copyright (c) 2008-2010 Henning Manske. All rights reserved.

This module is free software. You can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/.

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.