AnyEvent::Twitter - Implementation of the Twitter API for AnyEvent
Version 0.26
use AnyEvent::Twitter; my $twitty = AnyEvent::Twitter->new ( username => 'elm3x', password => 'secret123' ); $twitty->reg_cb ( error => sub { my ($twitty, $error) = @_; warn "Error: $error\n"; }, statuses_friends => sub { my ($twitty, @statuses) = @_; for (@statuses) { my ($pp_status, $raw_status) = @$_; printf "new friend status: %s: %s\n", $pp_status->{screen_name}, $pp_status->{text}; } }, ); $twitty->receive_statuses_friends; $twitty->update_status ("I'm bathing in my hot tub!", sub { my ($twitty, $status, $js_status, $error) = @_; if (defined $error) { # ... } else { # ... } }); $twitty->start; # important!
This is a lightweight implementation of the Twitter API. It's currently still very limited and only implements the most necessary parts of the API (for inclusion in my chat client).
If you are missing something don't hesitate to bug me!
This module uses AnyEvent::HTTP for communicating with twitter. It currently doesn't use OAuth based authentication but HTTP Basic Authentication, as it is still not deprecated at the time of this writing (July 2009). If it will ever be deprecated I will take care to implement OAuth.
The AnyEvent::Twitter class inherits the event callback interface from Object::Event.
As the Twitter API is heavily rate limited in that kind of way that you only have a few GET requests per hour (~150), this module implements rate limiting. It will dynamically adjust the poll intervals (if you didn't set a fixed poll intervall) to not exceed the requests per hours.
The bandwidth parameter to the new method (see below) controls how much of the available requests are used. This is useful if you want to run multiple clients for one twitter account and not have them take away each others request per hours.
bandwidth
new
The $weigth parameters to the receive_... methods is for prioritizing the requests. It works as follows: Each time a request can be made every receive_... 'job' gets his weight added to an internal counter. The 'job' with the highest count will be executed.
$weigth
receive_...
With this simple weight system you can say which kind of information you are most interested in. For example giving the statuses of your friends a $weight of 2 and the mentions of your nickname a $weight of 1 will result in polling the statuses of your friends two times more often.
$weight
NOTE: It's crucial that your system clock is correctly set. As twitter only reports an absolute time at which the rate limiting is reseted we have to calculate the next poll time based on your clock.
Creates a new twitter client object. %args can contain these arguments (username and password are mandatory):
%args
username
password
Your twitter username.
Your twitter password.
Initializer for the value given to the state method (see below).
state
$bandwidth_factor is the amount of "bandwidth" that is consumed by the regular polling. The default value is 0.95. Any value between 0 and 1 is valid.
$bandwidth_factor
0.95
If you give a value of 0.5 this AnyEvent::Twitter instance will only use up half of the available requests per hours for the polls.
0.5
This method will start requesting the data you are interested in. See also the receive_... methods, about how to say what you are interested in.
This will enable polling for the statuses of your friends.
About $weight see the "WEIGHTS AND RATE LIMITING" section.
Whenever a new status is received the statuses_friends event is emitted (see below).
statuses_friends
The id of the seen statuses are recorded in a data structure which you may set or retrieve via the state method. I recommend caching the state data structure.
id
This will enable polling for the statuses that mention you.
Whenever a new status is received the statuses_mentions event is emitted (see below).
statuses_mentions
This method checks whether the string in $status does not exceed the maximum length of a status update.
$status
If the length is ok a true value is returned. If not, a false value is returned.
This will post an update of your status to twitter. $status should not be longer than 140 octets, you can check this with the check_status_length method (see above).
check_status_length
When the request is done the $done_cb callback will be called with the $status as second argument if the update was successful and a human readable $error string as fourth argument in case of an error. $js is the JSON response received from the server.
$done_cb
$error
$js
When the HTTP POST was successful the status_updated event will be emitted.
status_updated
With these methods you can set the internal sequence state. Whenever a special kind of data is retrieved from Twitter the most recent sequence id of the entry is remembered in the hash $state_struct.
$state_struct
You can use this method to store the state or restore it. This is useful if you have an application that shouldn't forget which entries it already saw.
This event is emitted whenever a new status was seen for the statuspath which can be one of these:
statuspath
friends public (currently unimplemented) user (currently unimplemented) mentions
@statuses contains the new status updates. The order is usually that the newest statuses come first. Each element of @statuses is an array reference containing:
@statuses
$status, $raw_status
$status is a hash reference containing some post processed information about the status update in $raw_status. Most notable is the unescaping of the texts (see below about $raw_status).
$raw_status
It contains these key/value pairs:
This is the text of the status update.
This contains the screen name of the user who posted this status update.
This contains the creation time of the status as unix timestamp in UTC time.
$raw_status is the parsed JSON structure of the new status. About the interesting fields please consult http://apiwiki.twitter.com/Twitter-API-Documentation.
Please note that '<' and '>' are encoded as HTML entities '<' and '>', so you will have to decode them yourself.
This event is emitted when the timer for the next request is started. $seconds are the seconds until the next request is made.
$seconds
$remaining_request are the requests you have available within the next $remaining_time seconds.
$remaining_request
$remaining_time
Whenever an error happens this event is emitted. $error_string contains a human readable error message.
$error_string
Robin Redeker, <elmex@ta-sa.org>
<elmex@ta-sa.org>
Nuno Nunes (nfmnunes @ CPAN) - For initial patch for mentions.
Object::Event
http://apiwiki.twitter.com/Twitter-API-Documentation
Please report any bugs or feature requests to bug-anyevent-twitter at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=AnyEvent-Twitter. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.
bug-anyevent-twitter at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc AnyEvent::Twitter
You can also look for information at:
IRC: AnyEvent::Twitter IRC Channel
See the same channel as the AnyEvent::XMPP module:
IRC Network: http://freenode.net/ Server : chat.freenode.net Channel : #ae_xmpp Feel free to join and ask questions!
Homepage:
http://software.schmorp.de/pkg/AnyEvent-Twitter.html
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/AnyEvent-Twitter
CPAN Ratings
http://cpanratings.perl.org/d/AnyEvent-Twitter
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=AnyEvent-Twitter
Search CPAN
http://search.cpan.org/dist/AnyEvent-Twitter
Copyright 2009 Robin Redeker, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install AnyEvent::Twitter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm AnyEvent::Twitter
CPAN shell
perl -MCPAN -e shell install AnyEvent::Twitter
For more information on module installation, please visit the detailed CPAN module installation guide.