NAME
Net::Twitter::Role::AutoCursor - Help transition to cursor based access to friends_ids and followers_ids methods
VERSION
version 4.01006
SYNOPSIS
use Net::Twitter;
my $nt = Net::Twitter->new(
traits => [qw/AutoCursor API::RESTv1_1 RetryOnError OAuth/],
# additional ags...
);
# Get friends_ids or followers_ids without worrying about cursors
my $ids = $nt->followers_ids;
my $nt = Net::Twitter->new(
traits => [
qw/API::RESTv1_1 RetryOnError OAuth/
AutoCursor => { max_calls => 32 },
AutoCursor => {
max_calls => 4,
force_cursor => 1,
array_accessor => 'users',
methods => [qw/friends followers/],
},
],
# additional args
);
# works with any Twitter call that takes a cursor parameter
my $friends = $nt->friends;
DESCRIPTION
On 25-Mar-2011, Twitter announced a change to friends_ids
and followers_ids
API methods:
[Soon] followers/ids and friends/ids is being updated to set the cursor to -1
if it isn't supplied during the request. This changes the default response
format
This will break a lot of existing code. The AutoCursor
trait was created to help users transition to cursor based access for these methods.
With default parameters, the AutoCursor
trait attempts a non-cursored call for friends_ids
and followers_ids
. If it detects a cursored response from Twitter, it continues to call the underlying Twitter API method, with the next cursor, until it has received all results or 16 calls have been made (yielding 80,000 results). It returns an ARRAY reference to the combined results.
If the cursor
parameter is passed to friends_ids
or followers_ids
, Net::Twitter
assumes the user is handling cursoring and does not modify behavior or results.
The AutoCursor
trait is parameterized, allowing it to work with any Twitter API method that expects cursors, returning combined results for up to the maximum number of calls specified.
AutoCursor
can be applied multiple times to handle different sets of API methods.
PARAMETERS
- max_calls
-
An integer specifying the maximum number of API calls to make. Default is 16.
max_calls
can be overridden on a per-call basis by passing amax_calls
argument to the API method. - force_cursor
-
If true, when the caller does not provide a
cursor
parameter,AutoCursor
will use up tomax_calls
cursored calls rather than attempting an initial non-cursored call. Default is 0. - array_accessor
-
The name of the HASH key used to access the ARRAY ref of results in the data structure returned by Twitter. Default is
ids
. - methods
-
A reference to an ARRAY containing the names of Twitter API methods to which
AutoCursor
will be applied.
METHOD CALLS
Synthetic parameter -max_calls
can be passed for individual method calls to override the default:
$r = $nt->followers_ids({ -max_calls => 200 }); # get up to 1 million ids
Synthetic parameter -force_cursor
can be passed to override the force_cursor
default.
AUTHOR
Marc Mims <marc@questright.com>
COPYRIGHT
Copyright (c) 2011 Marc Mims
LICENSE
This library is free software and may be distributed under the same terms as perl itself.