NAME¶
Net::Twitter::Role::AutoCursor - Help transition to cursor based access to
friends_ids and followers_ids methods
VERSION¶
version 4.01005
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 a
"max_calls" argument to the API method.
- force_cursor
- If true, when the caller does not provide a "cursor" parameter,
"AutoCursor" will use up to "max_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.