NAME

WWW::Tumblr - Perl interface for the Tumblr API

SYNOPSIS

 use WWW::Tumblr;
 
 # read method
 my $t = WWW::Tumblr->new;
 
 # Will read http://juanito.tumblr.com/api/read
 $t->user('juanito');

 # Will read http://log.damog.net/api/read
 $t->url('http://log.damog.net');

 # Pass Tumblr API read arguments to the read() method
 $t->read(
        start => 2,
        num     => 10,
        ...
 );

 # Will get you JSON back
 # Same arguments as read, as defined by the API
 $t->read_json(
        ...
 );
 
 # write
 # Object initialization
 my $t = WWW::Tumblr->new;

 # The email you use to log in to Tumblr        
 $t->email('pepito@chistes.com');
 $t->password('foobar');
 
 # You will always have to pass a type to write() and the additional
 # args depend on that type and the requests by the Tumblr API
 $t->write(
        type => 'regular',
        body => 'My body text',
        ...

        type => 'quote',
        quote => 'I once had a girlfriend...',
        ...

        type => 'conversation',
        title => 'On the subway...',
        conversation => 'Meh, meh, meh.',
        ...

        # File uploads:
        type => 'audio',
        data => '/tmp/my.mp3',
        ...
 );
 
 # other actions
 $t->authenticate or die $t->errstr;
 $t->check_audio or die $t->errstr;

 my $vimeo = $t->check_vimeo or die $t->errstr;

All options passed to read, read_json and write are all of the parameters specified on http://www.tumblr.com/api and you simple have to pass them as key => values argument pairs.

The Tumblr API is not really long or difficult and this implementation covers it fully.

METHODS

new

 new(
        user => $user,
        email => $email,
        password => $password,
        url => $url,
 );

Initilizes a class instance.

All arguments are optional, you can specify most of them here on each of the method calls anyway.

email

 email(
        $email
 );

If $email is specified, it sets the email class variable, otherwise, the previous value is returned. This is the email that users use to log in to Tumblr.

password

 password(
        $password
 );

If $password is specified, it sets the password class variable, otherwise the previous value is returned. This is the password used by users to log in to Tumblr.

user

 user(
        $user
 );

If $user is specified, it sets the user class variable, otherwise the previous value is returned. This is the user portion of the tumblr.com URL (ie. maria.tumblr.com).

url

 url(
        $url
 );

If $url is specified, it sets the url class variable. Otherwise, the previous value is returned. This is the URL that some people might use for their Tumblelogs instead of user.tumblr.com (in my case, http://log.damog.net).

read_json

 read_json(
        # read params
        ...
 );

Returns the JSON version of c<read>, it accepts the same Tumblr API arguments. It returns the JSON version of read.

read

 read(
        # read args
        ...
 );

You should have specified the user or url to use this method. Parameters to be passed are the ones specified on the Tumblr API, such as id, num, type, etc. It returns an XML string containing the output.

If the option auth => 1 is passed, an authenticated read request is being made in order to retrieve the private posts as well. See Tumblr's API for details.

write

 write(
        type => $type,
        ...
        # other write args
 );

Posts a type item with the needed arguments from the Tumblr API. The type argument is mandatory. email and password should have been specified before too. In success, it returns true, otherwise, it returns undef. For file uploads, just specify the filename on the data argument.

edit

 edit(
   'post-id' => 123,
   type => 'regular',
   title => 'This has changed!',
   ...
 );

Edits the post idenfied with post-id. The same parameters as those used with write can be used, but post-id has to be specified.

delete

 delete(
   'post-id' => 123,
 );

Deletes the post idenfied with the post-id id.

check_audio

 check_audio();

This method has been deprecated on this implementation since it was also on the Tumblr API.

Checks if the user can upload an audio file. Returns true or undef.

check_vimeo

 check_vimeo();

Deprecated as the Tumblr API discontinued it.

Checks if the user is logged in on Vimeo, as specified by the Tumblr API. Returns the maximum number of bytes available for the user to upload in case the user is logged in, otherwise it returns undef.

authenticate

 authenticate();

Checks if the email and password specified are correct. If they are, it returns true, otherwise, undef.

errstr

 errstr();

It returns the error string for the last operation, so you can see why other methods failed.

_POST_request

 _POST_request($string);

Internal method to post $string to Tumblr. You shouldn't be using it anyway.

SEE ALSO

http://tumblr.com, http://tumblr.com/api. See also the sample scripts on the examples/ dir.

This and other interesting modules and hacks are posted by the author on his blog Infinite Pig Theorem, http://damog.net.

The code is actively maintained at http://github.com/damog/www-tumblr.

AUTHOR

David Moreno Garza, <david@axiombox.com>

THANKS

You know who (http://maggit.net).

COPYRIGHT AND LICENSE

Copyright (C) 2008 by David Moreno Garza - Axiombox

http://axiombox.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

DISCLAIMER

I'm not a worker nor affiliated to Tumblr in any way, and this is a separated implementation of their own public API.

cpanm WWW::Tumblr

perl -MCPAN -e shell
install WWW::Tumblr