NAME

Net::Twitter - Perl interface to twitter.com

VERSION

This document describes Net::Twitter version 1.05

SYNOPSIS

#!/usr/bin/perl

use Net::Twitter;

my $twit = Net::Twitter->new(username=>"myuser", password=>"mypass" );

$result = $twit->update("My current Status");

$twit->credentials("otheruser", "otherpass");

$result = $twit->update("Status for otheruser");

DESCRIPTION

http://www.twitter.com provides a web 2.0 type of ubiquitous presence. This module allows you to set your status, as well as the statuses of your friends.

You can view the latest status of Net::Twitter on it's own twitter timeline at http://twitter.com/net_twitter

INTERFACE

Net::Twitter exports the following methods.

new(...)

You must supply a hash containing the configuration for the connection.

Valid configuration items are:

username

Username of your account at twitter.com. This is usually your email address. REQUIRED.

password

Password of your account at twitter.com. REQUIRED.

useragent

OPTIONAL: Sets the User Agent header in the HTTP request. If omitted, this will default to "Net::Twitter/$Net::Twitter::Version (Perl)"

clientname

OPTIONAL: Sets the X-Twitter-Client-Name: HTTP Header. If omitted, this defaults to "Perl Net::Twitter"

clientver

OPTIONAL: Sets the X-Twitter-Client-Version: HTTP Header. If omitted, this defaults to the current Net::Twitter version, $Net::Twitter::VERSION.

clienturl

OPTIONAL: Sets the X-Twitter-Client-URL: HTTP Header. If omitted, this defaults to http://x4.net/Net-Twitter/meta.xml. By standard, this file should be in XML format, as at the default location.

apiurl

OPTIONAL. The URL of the API for twitter.com. This defaults to http://twitter.com/ if not set.

NOTICE: As of Net::Twitter 1.05 the default URL has changed from http://twitter.com/statuses to http://twitter.com/ to reflect the expansion of the API outside the /statuses area. If your code was written to Net::Twitter 1.04 or earlier, and you set apiurl, including /statuses in the URL, you will have to remove it. the top level "directory" for the API is now added individually in each method.

apihost

apirealm

OPTIONAL: If you do point to a different URL, you will also need to set apihost and apirealm so that the internal LWP can authenticate.

apihost defaults to www.twitter.com:80.

apirealm defaults to Twitter API.

credentials($username, $password, $apihost, $apiurl)

Change the credentials for logging into twitter. This is helpful when managing multiple accounts.

apirealm and apihost are optional and will default to the standard twitter versions if omitted.

update($status)

Set your current status. This returns a hashref containing your most recent status. Returns undef if an error occurs.

replies([$page])

Returns the 20 most recent replies (status updates prefixed with @username posted by users who are friends with the user being replied to) to the authenticating user.

Accepts an optional argument for page to retrieve, which will the 20 next most recent statuses from the authenticating user and that user's friends, eg "page=3"

featured()

This returns a hashref containing a list of the users currently featured on the site with their current statuses inline. Returns undef if an error occurs.

friends()

This returns a hashref containing the most recent status of those you have marked as friends in twitter. Returns undef if an error occurs.

friends_timeline(...)

This returns a hashref containing the timeline of those you have marked as friends in twitter. Returns undef if an error occurs.

Accepts an optional argument hashref:

User id or email address of a user other than the authenticated user, in order to retrieve that user's friends_timeline.

since

Narrows the returned results to just those statuses created after the specified HTTP-formatted date.

page

Gets the 20 next most recent statuses from the authenticating user and that user's friends, eg "page=3"

user_timeline(...)

This returns a hashref containing the timeline of the authenticating user. Returns undef if an error occurs.

Accepts an optional argument of a hashref:

id

ID or email address of a user other than the authenticated user, in order to retrieve that user's friends_timeline.

count

Narrows the returned results to a certain number of statuses. This is limited to 20.

since Narrows the returned results to just those statuses created after the specified HTTP-formatted date.

destroy_status($id)

Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status.

destroy_friend($id)

Discontinues friendship with the user specified in the ID parameter as the authenticating user. Returns the un-friended user in the requested format when successful.

show_status($id)

Returns status of a single tweet. The status' author will be returned inline.

The argument is the ID or email address of the twitter user to pull, and is REQUIRED.

show_user($id)

Returns extended information of a single user.

The argument is the ID or email address of the twitter user to pull, and is REQUIRED.

public_timeline([12345])

This returns a hashref containing the public timeline of all twitter users. Returns undef if an error occurs.

Accepts an optional argument containing a status ID, and limits responses to only statuses greater than this ID

followers()

This returns a hashref containing the timeline of those who follow your status in twitter. Returns undef if an error occurs.

direct_messages()

Returns a list of the direct messages sent to the authenticating user.

Accepts an optional hashref for arguments:

page

Retrieves the 20 next most recent direct messages.

since

Narrows the returned results to just those statuses created after the specified HTTP-formatted date.

since_id

Narrows the returned results to just those statuses created after the specified ID.

sent_direct_messages()

Returns a list of the direct messages sent by the authenticating user.

Accepts an optional hashref for arguments:

page

Retrieves the 20 next most recent direct messages.

since

Narrows the returned results to just those statuses created after the specified HTTP-formatted date.

since_id

Narrows the returned results to just those statuses created after the specified ID.

new_direct_message($args)

Sends a new direct message to the specified user from the authenticating user.

REQUIRES an argument of a hashref:

user

ID or email address of user to send direct message to.

text

Text of direct message.

destroy_direct_message($id)

Destroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message.

CONFIGURATION AND ENVIRONMENT

Net::Twitter uses LWP internally. Any environment variables that LWP supports should be supported by Net::Twitter. I hope.

DEPENDENCIES

LWP::UserAgent

JSON::Any

Starting with version 1.04, Net::Twitter requires JSON::Any instead of a specific JSON handler module. Net::Twitter currently accepts JSON::Any's default order for loading handlers.

INCOMPATIBILITIES

The X-Twitter-Client-Name, X-Twitter-Client-Version, and X-Twitter-Client-URL, headers (See: new) are currently a de facto standard that have not been fully codified and accepted by Twitter.

Though they are expected to be accepted as valid (And optional), they could possibly change in the future.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-net-twitter@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Chris Thompson <cpan@cthompson.com>

The framework of this module is shamelessly stolen from Net::AIML. Big ups to Chris "perigrin" Prather for that.

LICENCE AND COPYRIGHT

Copyright (c) 2007, Chris Thompson <cpan@cthompson.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm Net::Twitter

perl -MCPAN -e shell
install Net::Twitter