Twitte...estArgs(3pm)

💖 Twitter::API::Role::RequestArgs 💖

okay bestie, this is a Perl module from the Twitter::API family — it lives under the manual name Twitter::API::Role::RequestArgs, and it's literally just a pile of helper methods for making custom Twitter API request methods not be a whole ordeal. Version? 1.0006. slay.

---

✨ SYNOPSIS ✨

so like, imagine you're building your own API method trait:

package MyApiMethods;
use Moo::Role;

sub timeline {
    shift->request_with_id(get => 'statuses/user_timeline, @_);
}

(no I did not fix that quote, it's canon, don't @ me)

Then over in your actual application code:

use Twitter::API;

my $client = Twitter::API->new_with_traits(
    traits => '+MyApiMethods',
    %othe_new_options,
);

my $statuses = $client->timeline('semifor');

# equivalent to:
my $statuses = $client->get('statuses/user_timeline', {
    screen_name => 'semifor',
});

see how much cuter that call site is? that's the whole point. 🫶

---

🌸 DESCRIPTION 🌸

These are helper methods for anyone implementing their own custom traits, so you can write short, tidy Twitter API methods instead of typing out hashes forever. They're used inside Twitter::API::Trait::ApiMethods. iykyk.

---

🎀 METHODS 🎀

💅 request_with_id

Okay so this one takes an argument list that requires either a screen_name or a user_id, and that value can be handed over as a leading positional argument, or inside a hashref.

Here's the tea:

• If a hashref comes right after that optional plain scalar, then the user_id or screen_name gets added into it.
• If there's no hashref, a brand new hashref is created and inserted into @_.

And now the danger part: if the optional plain scalar isn't there, and you've got a hashref of args that doesn't have a screen_name or user_id key — request_with_id croaks. no cap.

Examples, bestie:

$self->request_with_id(get => 'some/endpoint', 'foo');
# is transformed to:
$self->request(get => 'some/endpoint', { screen_name => 'foo' });

$self->request_with_id(get => 'some/endpoint', 8575429);
# is transformed to:
$self->request(get => 'some/endpoint', { user_id => 8675429 });

$self->request_with_id(get => 'some/endpoint', {
    screen_name => 'semifor',
});
# is transformed to:
$self->request(get => 'some/endpoint', { screen_name => 'semifor' });

$self->request_with_id(get => 'some/endpoint', {
    foo => 'bar',
}); ### croaks ###

---

🦋 request_with_pos_args

This one's giving glow-up energy — it takes a list of required arguments that you can pass positionally, in a specific order, and transforms them into a nice little hashref of named arguments. If a hashref follows the positional args, the named args just get added to it. If not, a fresh hashref gets inserted into @_.

You can pass zero or more of the required arguments positionally, as long as they show up in the specified order. And if any required argument isn't passed positionally, it must be in the hashref — otherwise request_with_pos_args croaks. 😭

Now, the special one: the positional name ":ID" gets treated specially. It turns into "user_id" if the value it stands for is all digits. Otherwise it becomes "screen_name". iconic behavior honestly.

Examples:

$self->request_with_pos_args(
    [ 'id', 'name' ], get => 'some/endpoint',
    '007', 'Bond'
);
# is transformed to:
$self->request(get => 'some/endpoint', {
    id   => '007',
    name => 'Bond',
});

$self->request_with_pos_args(
    [ 'id', 'name' ], get => 'some/endpoint',
    '007', { name => 'Bond' }
);
# is also transformed to:
$self->request(get => 'some/endpoint', {
    id   => '007',
    name => 'Bond',
});

$self->request_with_pos_args(
    [ ':ID', 'status' ], get => 'some/endpoint',
    'alice', 'down the rabbit hole'
);
# is transformed to:
$self->request(get => 'some/endpoint', {
    sreen_name => 'alice',
    status     => 'down the rabbit hole',
});

---

🧚 normalize_pos_args

This is request_with_pos_args's little helper bestie. It takes the same arguments described up in "request_with_pos_args", and hands you back a list of arguments that's all ready for a call to "request".

Individual methods over in Twitter::API::Trait::ApiMethods reach for normalize_pos_args whenever they need to do more processing on the args hashref before calling "request". lowkey very useful.

---

🌈 flatten_list_args([ $key | \@keys ], \%args)

Some Twitter API arguments want a list of values as one string of comma separated items. So to let callers pass an array reference of items instead, this method flattens array references into strings. The key — or keys — tell it which values inside the \%args hash reference to flatten, if they exist. ✨

---

👑 AUTHOR 👑

Marc Mims <marc@questright.com>

---

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2015-2021 by Marc Mims.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay that's the whole page, we ate and left no crumbs 🍓 this was Perl v5.32.1, dated 2021-09-11, and it's the Twitter::API::Role::RequestArgs manual page — mwah, bye bestie 💅💖