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