WWW::Plurk - Unoffical plurk.com API
This document describes WWW::Plurk version 0.02
use WWW::Plurk; my $plurk = WWW::Plurk->new; $plurk->login( 'username', 'password' ); my $msg = $plurk->add_plurk( content => 'Hello, World' );
This is an unofficial API for plurk.com. It uses the same interfaces that plurk itself uses internally which are not published and not necessarily stable. When Plurk publish a stable API this module will be updated to take advantage of it. In the mean time use with caution.
Ryan Lim did the heavy lifting of reverse engineering the API. His PHP implementation can be found at http://code.google.com/p/rlplurkapi/.
If you'd like to lend a hand supporting the bits of Plurk that this API doesn't yet reach please feel free to send me a patch. The Plurk API Wiki at http://plurkwiki.badchemicals.net/ is a good source of information.
All methods throw errors in the event of any kind of failure. There's no need to check return values but you might want to wrap calls in an eval block.
eval
new
Create a new WWW::Plurk. Optionally accepts two arguments (username, password). If they are supplied it will attempt to login to Plurk. If no arguments are supplied login must be called before attempting to access the service.
WWW::Plurk
login
# Create and login my $plurk = WWW::Plurk->new( 'user', 'pass' ); # Create then login afterwards my $plurk = WWW::Plurk->new; $plurk->login( 'user', 'pass' );
Attempt to login to a Plurk account. The two mandatory arguments are the username and password for the account to be accessed.
my $plurk = WWW::Plurk->new; $plurk->login( 'user', 'pass' );
is_logged_in
Returns a true value if we're currently logged in.
if ( $plurk->is_logged_in ) { $plurk->add_plurk( content => 'w00t!' ); }
friends_for
Return a user's friends.
my @friends = $plurk->friends_for( $uid );
Pass the user id as either
an integer
my @friends = $plurk->friends_for( 12345 );
an object that has a method called uid
uid
# $some_user isa WWW::Plurk::Friend my @friends = $plurk->friends_for( $some_user );
Returns a list of WWW::Plurk::Friend objects.
friends
Return the current user's friends. This
my @friends = $plurk->friends;
is equivalent to
my @friends = $plurk->friends_for( $self->uid );
add_plurk
Post a new plurk.
$plurk->add_plurk( content => 'Hello, World' );
Arguments are supplied as a number of key, value pairs. The following arguments are recognised:
content - the message content
qualifier - the qualifier string ('is', 'says' etc)
lang - the (human) language for this Plurk
no_comments - true to disallow comments
limited_to - limit visibility
The only mandatory argument is content which should be a string of 140 characters or fewer.
content
qualifier is first word of the message - which has special significance that you will understand if you have looked at the Plurk web interface. The following qualifiers are supported:
qualifier
asks feels gives has hates is likes loves says shares thinks wants was will wishes
If omitted qualifier defaults to ':' which signifies that you are posting a free-form message with no qualifier.
lang is the human language for this Plurk. It defaults to 'en'. Apologies to those posting in languages other than English.
lang
no_comments should be true to lock the Plurk preventing comments from being made.
no_comments
limited_to is an array of user ids (or objects with a method called uid). If present the Plurk will only be visible to those users. To limit visibility of a Plurk to friends use:
limited_to
my $msg = $plurk->add_plurk( content => 'Hi chums', limited_to => [ $plurk->friends ] );
Returns a WWW::Plurk::Message representing the new Plurk.
plurks
Get a list of recent Plurks for the logged in user. Returns an array of WWW::Plurk::Message objects.
my @plurks = $plurk->plurks;
Any arguments must be passed as key => value pairs. The following optional arguments are recognised:
uid - the user whose messages we want
date_from - the start date for retrieved messages
date_offset - er, not sure what this does :)
As you may infer from the explanation of date_offset, I'm not entirely sure how this interface works. I cargo-culted the options from the PHP version. If anyone can explain date_offset please let me know and I'll update the documentation.
date_offset
unread_plurks
Return a list of unread Plurks for the current user.
responses_for
Get the responses for a Plurk. Returns a list of WWW::Plurk::Message objects. Accepts a single argument which is the numeric ID of the Plurk whose responses we want.
my @responses = $plurk->responses_for( $msg->plurk_id );
respond_to_plurk
Post a response to an existing Plurk. The first argument must be the ID of the Plurk to respond to. Additional arguments are supplied as a number of key => value pairs. The following arguments are recognised:
See add_plurk for details of how these arguments are interpreted.
my $responce = $plurk->respond_to_plurk( $plurk_id, content => 'Nice!' );
Returns an WWW::Plurk::Message representing the newly posted response.
The following accessors are available:
info - the user info hash
info
state - the state of this object (init or login)
state
trace - set true to enable HTTP query tracing
trace
display_name - the user's display name
display_name
full_name - the user's full name
full_name
gender - the user's gender
gender
has_profile_image - has a profile image?
has_profile_image
id - appears to be a synonym for uid
id
is_channel - unknown; anyone know?
is_channel
karma - user's karma score
karma
location - user's location
location
nick_name - user's nick name
nick_name
page_title - unknown; anyone know?
page_title
relationship - married, single, etc
relationship
star_reward - ???
star_reward
uid - the user's ID
WWW::Plurk requires no configuration files or environment variables.
None.
None reported.
No bugs have been reported.
Please report any bugs or feature requests to bug-www-plurk@rt.cpan.org, or through the web interface at http://rt.cpan.org.
bug-www-plurk@rt.cpan.org
Andy Armstrong <andy.armstrong@messagesystems.com>
<andy.armstrong@messagesystems.com>
http://www.plurk.com/user/AndyArmstrong
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
Copyright (c) 2008, Message Systems, Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name Message Systems, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
To install WWW::Plurk, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Plurk
CPAN shell
perl -MCPAN -e shell install WWW::Plurk
For more information on module installation, please visit the detailed CPAN module installation guide.