NAME
   AnyEvent::Twitter - Implementation of the Twitter API for AnyEvent

VERSION
   Version 0.27

SYNOPSIS
      use AnyEvent::Twitter;

      my $cv = AnyEvent->condvar; # see below about this

      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!

      $cv->recv; # AnyEvent idiom to start some event loop or wait until
                 # the condvar is 'sent'

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

WEIGHTS AND RATE LIMITING
   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.

   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.

   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.

 LOCAL TIME
   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.

METHODS
   my $obj = AnyEvent::Twitter->new (%args)
       Creates a new twitter client object. %args can contain these
       arguments ("username" and "password" are mandatory):

       username => $username
           Your twitter username.

       password => $password
           Your twitter password.

       state => $new_state_struct
           Initializer for the value given to the "state" method (see
           below).

       bandwidth => $bandwidth_factor
           $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.

           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.

   $obj->start
       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.

   $obj->receive_statuses_friends ([$weight])
       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).

       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.

   $obj->receive_statuses_mentions ([$weight])
       This will enable polling for the statuses that mention you.

       About $weight see the "WEIGHTS AND RATE LIMITING" section.

       Whenever a new status is received the "statuses_mentions" event is
       emitted (see below).

       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.

   $obj->check_status_length ($status)
       This method checks whether the string in $status does not exceed the
       maximum length of a status update.

       If the length is ok a true value is returned. If not, a false value
       is returned.

   $obj->update_status ($status, $done_cb->($obj, $status, $js, $error))
       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).

       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.

       When the HTTP POST was successful the "status_updated" event will be
       emitted.

   my $state_struct = $obj->state
   $obj->state ($new_state_struct)
       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.

       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.

EVENTS
   statuses_<statuspath> => @statuses
       This event is emitted whenever a new status was seen for the
       "statuspath" which can be one of these:

          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:

          $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).

       It contains these key/value pairs:

       text => $text
           This is the text of the status update.

       screen_name => $screen_name
           This contains the screen name of the user who posted this status
           update.

       timestamp => $timestamp
           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 '&lt;' and
       '&gt;', so you will have to decode them yourself.

   next_request_in => $seconds, $remaining_request, $remaining_time
       This event is emitted when the timer for the next request is
       started. $seconds are the seconds until the next request is made.

       $remaining_request are the requests you have available within the
       next $remaining_time seconds.

   error => $error_string
       Whenever an error happens this event is emitted. $error_string
       contains a human readable error message.

AUTHOR
   Robin Redeker, "<[email protected]>"

ACKNOWLEDGEMENTS
     Nuno Nunes (nfmnunes @ CPAN)     - For initial patch for mentions.

SEE ALSO
   Object::Event

   <http://apiwiki.twitter.com/Twitter-API-Documentation>

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

SUPPORT
   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 & LICENSE
   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.