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.

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.

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

Returns a true value if we're currently logged in.

    if ( $plurk->is_logged_in ) {
        $plurk->add_plurk( content => 'w00t!' );
    }

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

    # $some_user isa WWW::Plurk::Friend
    my @friends = $plurk->friends_for( $some_user );

Returns a list of WWW::Plurk::Friend objects.

Return the current user's friends. This

    my @friends = $plurk->friends;

is equivalent to

    my @friends = $plurk->friends_for( $self->uid );

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.

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:

  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.

no_comments should be true to lock the Plurk preventing comments from being made.

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:

    my $msg = $plurk->add_plurk(
        content => 'Hi chums',
        limited_to => [ $plurk->friends ]
    );

Returns a WWW::Plurk::Message representing the new Plurk.

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.

Return a list of unread Plurks for the current user.

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

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:

* content - the message content

* qualifier - the qualifier string ('is', 'says' etc)

* lang - the (human) language for this Plurk

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

* state - the state of this object (init or login)

* trace - set true to enable HTTP query tracing

* display_name - the user's display name

* full_name - the user's full name

* gender - the user's gender

* has_profile_image - has a profile image?

* id - appears to be a synonym for uid

* is_channel - unknown; anyone know?

* karma - user's karma score

* location - user's location

* nick_name - user's nick name

* page_title - unknown; anyone know?

* relationship - married, single, etc

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

Andy Armstrong <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.