Perl Wrapper for the Connotea Web API

The current version is www-connotea-perl-0.1.

Download from SourceForge.

Note: this library will be added to CPAN in the near future.

These modules are required by Connotea.pm

The README information is copied here:

WWW::Connotea v0.1

Perl Wrapper for the Connotea Web API
(c) Nature Publishing Group 2006
connotea@nature.com

License

This code is made available under the terms of the GNU General Public License:

http://www.gnu.org/copyleft/gpl.html

About

WWW::Connotea implements the Connotea Web API (http://www.connotea.org/wiki/WebAPI)

All classes are defined in 'lib/WWW/Connotea.pm'.

There are some sample scripts that use this library in 'sample':

• post_something.pl -- adds a bookmark to your library
• remove_it.pl -- deletes the bookmark
• my_tags.pl -- prints a list of all the tags you've used
• related_articles.pl -- implements a very basic related articles algorithm using shared tags

Before any of the sample code will run, you'll need to edit the files to enter
your own Connotea username and passsword

Usage

use lib 'path/to/lib';
use WWW::Connotea;

my $c = WWW::Connotea->new(  user => 'your_username', password => 'your_password' );
$c->authenticate;   ###  dies if log-in credentials are incorrect

# query and post using the WWW::Connotea object. See class details below
foreach my $post ($c->posts_for( tag => 'connotea')) {
  print $post->title, "\n";
}

my $new_post = WWW::Connotea->new;
$new_post->link('http://www.example.com');
$new_post->tags('My Examlpe Tag', 'and_another_one');
$c->create($new_post);

WWW::Connotea

Methods

new(
            user => 'username',
            password => 'password',
            location => 'http://www.connotea.org/',
            realm => 'Connotea'
      )

location and realm are optional, and need only be specified it you are querying a private instance of Connotea Code.

bookmarks_for( 
                    user => 'name of a connotea user'
                    tag   => 'name of a tag'
                    date  => 'yyyy-mm-dd -- just for posts on a certain date'
                    uri    => 'a URL'
                    hash => 'MD5 hash of URL -- alternative to :uri'
                    q      => 'Search string'
                    num => 'number of results -- default is 1000'
                    start => 'result number to start from'
               ) 

Returns a list of WWW::Connotea::Boookmark objects.

All parameters for the query are optional, excepting that there must be at least one parameter that is not 'start'.

posts_for( 
                    user => 'name of a connotea user'
                    tag   => 'name of a tag'
                    date  => 'yyyy-mm-dd -- just for posts on a certain date'
                    uri    => 'a URL'
                    hash => 'MD5 hash of URL -- alternative to :uri'
                    q      => 'Search string'
                    num => 'number of results -- default is 1000'
                    start => 'result number to start from'
                ) 

Returns a list of WWW::Connotea::Post objects.

All parameters for the query are optional, excepting that there must be at least one parameter that is not 'start'.

tags_for( 
                    user => 'name of a connotea user'
                    tag   => 'name of a tag'
                    date  => 'yyyy-mm-dd -- just for posts on a certain date'
                    uri    => 'a URL'
                    hash => 'MD5 hash of URL -- alternative to :uri'
                    q      => 'Search string'
                    num => 'number of results -- default is 1000'
                    start => 'result number to start from'
                ) 

Returns a list of WWW::Connotea::Tag objects.

All parameters for the query are optional, excepting that there must be at least one parameter that is not :start.

create($p)

Where $p is a WWW::Connotea::Post object. Creates a new post in your library. The post object must have both a link and at least one tag in the tags array.

update($p)

Where p is a WWW::Connotea::Post object. Whichever of the post's attributes are not undef will be overwritten. Those that are undef will remain unchanged.

remove($p)

Where $p is a WWW::Connotea::Post object. Removes a post from your library. The post object need only have a link.

WWW::Connotea::Bookmark

Represents a bookmark in the Connotea database. A bookmark is any URL that has been added to Connotea.

Accessors

link

The bookmark URL.

title

The raw title for the bookmark. This will mostly have been extracted from the HTML.

tags

An array ref of all the tags used on this bookmark by all users. Note that it is an arrray of strings, not ConnoteaTag? objects.

posted_by

An array ref of names of all the users who have posted this bookmark.

posted_by_count

Number of users who posted this bookmark.

hash

The MD5 hash of the URL.

created

The date the URL was first added to the Connotea database.

updated

Date the bookmark was last modified.

first_user

Name of the first user to post this bookmark.

citation

Returns a WWW::Connotea::Citation object

WWW::Connotea::Post

Represents an entry in a user's collection.

Accessors

title

The title of the post. Note this is the title the user assigned, so may be different from the corresponding bookmark title.

link

The URL of this post's bookmark. Same as $p->bookmark->link.

tags

An array ref of the tags assigned by the user who made this post. Note that it is an arrray of strings, not Connotea::Tag? objects.

description

The user's description for the post.

user

The name of the user who made this post.

private

0 if the post is public, 1 if private.

created

Date the post was made.

updated

Date post was last modified.

bookmark

Returns the WWW::Connotea::Bookmark object for this post.

WWW::Connotea::Tag

Represents a tag used in Connotea. Only returned via tags_for() queries.

Accessors

label

The name of the tag.

post_count

The number of times the tag has been used in the context of the current query.

usage_score

The usage score for the tag (in the context of the current query). Takes into account both how often and how recently the tag was used.

WWW::Connotea::Citation

Represents the citation information for a bookmark. Not all bookmarks will have a citation object -- only those for which Connotea can automatically identify bibliographic information, or which were uploaded to Connotea in an RIS file.

Attributes

title

The article or book title.

authors

An array of Connotea::Author? objects.

publication_date

The date the article or book was published.

publication_name

The name of the journal the article was published in.

volume

The journal volume number

issue

The journal issue number.

start_page

The starting page number for the article

end_page

The ending page number for the article.

doi

The article DOI

pmid

The PubMed ID for the article.

WWW::Connotea::Author

Represents a citation author.

Accessors

name

Returns the name of the author.

WWW::Connotea::Response

Represents a reponse message generated by the Connotea Web API. This will be returned by create, update and remove operations, and if there is an error on any other operation.

Accessors

code

The HTTP status code for this response.

message

A human readable message explaining an errror.

is_success

Returns 1 if the operation was successful, and nil if not.

is_failure

Returns 1 if the operation failed, and nil if not.