Net::T...Cursor(3pm)

💖 NAME 💖

Net::Twitter::Role::AutoCursor — bestie, this role is here to help you transition to cursor based access for the friends_ids and followers_ids methods. That's it, that's the job. 🦋

(you're reading the Net::T...Cursor(3pm) man page from the User Contributed Perl Documentation, in case you were wondering which page just walked in 💅)

---

✨ VERSION ✨

version 4.01043 — yes, she's got a version number, she's official 🎀

---

🌸 SYNOPSIS 🌸

okay so here's the vibe:

  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;

look at her go 💅 and yeah, you can stack AutoCursor twice in that traits array like that, she's flexible, she's multi-talented.

---

🌈 DESCRIPTION 🌈

On 25-Mar-2011, Twitter announced a change to the friends_ids and followers_ids API methods. And the announcement said, verbatim:

[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

and bestie, this will break a lot of existing code. 😭 not exaggerating, that's just the truth. So the AutoCursor trait was created to help users transition to cursor based access for these methods. she's literally the emotional support trait 🫶

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). Then it returns an ARRAY reference to the combined results. iconic behaviour honestly.

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. periodt — you asked for the wheel, you drive the wheel 🚗

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. no cap.

---

🎀 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. iykyk, sometimes you just need more.

• 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

one million ids?? ate. 🔥

Synthetic parameter -force_cursor can be passed to override the force_cursor default.

---

👑 AUTHOR 👑

Marc Mims <marc@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.

---

okay that's the whole page, you're basically an AutoCursor expert now, go forth and cursor responsibly 💅✨

this has been the Net::T...Cursor(3pm) man page — perl v5.34.0, dated 2022-06-16. mwah, bye bestie 🫶🎀