phpman > perldoc > Net::Twitter::Role::AutoCursor(3pm)

NAME
    Net::Twitter::Role::AutoCursor - Help transition to cursor based access to friends_ids and
    followers_ids methods

VERSION
    version 4.01043

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 AT questright.com>

COPYRIGHT
    Copyright (c) 2016 Marc Mims

LICENSE
    This library is free software and may be distributed under the same terms as perl itself.