File Coverage

blib/lib/Net/Twitter/Role/API/Lists.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Net::Twitter::Role::API::Lists;
2             $Net::Twitter::Role::API::Lists::VERSION = '4.01043';
3 2     2   1507 use Moose::Role;
  2         4197  
  2         11  
4 2     2   9365 use Net::Twitter::API;
  2         5  
  2         11  
5 2     2   1626 use DateTime::Format::Strptime;
  2         5  
  2         14  
6 2     2   110 use Try::Tiny;
  2         4  
  2         1614  
7              
8             with 'Net::Twitter::Role::API::REST';
9              
10             =head1 NAME
11            
12             Net::Twitter::Role::API::Lists - Twitter Lists API support for Net::Twitter
13            
14             =head1 VERSION
15            
16             version 4.01043
17            
18             =head1 SYNOPSIS
19            
20             use Net::Twitter;
21            
22             my $nt = Net::Twitter->new(traits => ['API::Lists'], ...);
23            
24             $list = $nt->create_list($owner, { name => $name, description => $desc });
25             $list = $nt->update_list($owner, $list_id, { description => $desc });
26            
27             $lists = $nt->get_lists($owner);
28             $lists = $nt->list_lists($owner);
29            
30             $list = $nt->get_list($owner, $list_id);
31             $list = $nt->delete_list($owner, $list_id);
32            
33             $statuses = $nt->list_statuses($owner, $list_id);
34            
35             $lists = $nt->list_memberships($owner);
36             $lists = $nt->list_subscriptions($owner);
37            
38             $users = $nt->list_members($owner, $list_id);
39            
40             $user_or_undef = $nt->list_members($owner, $list_id, { id => $user_id });
41            
42             $user = $nt->add_list_member($owner, $list_id, $user_id);
43             $users = $nt->add_list_members($owner, $list_id, { screen_name => \@screen_names });
44            
45             $user = $nt->delete_list_member($owner, $list_id, $user_id);
46             $user = $nt->remove_list_member($owner, $list_id, $user_id);
47            
48             $user_or_undef = $nt->is_list_member($owner, $list_id, $user_id);
49            
50             $users = $nt->list_subscribers($owner, $list_id);
51            
52             $list = $nt->subscribe_list($owner, $list_id);
53             $list = $nt->unsubscribe_list($owner, $list_id);
54            
55             $user_or_undef = $nt->is_subscribed_list($owner, $list_id, $user_id);
56             $user_or_undef = $nt->is_list_subscriber($owner, $list_id, $user_id);
57            
58             #############################
59             # With the cursor parameter #
60             #############################
61            
62             $r = $nt->get_list($user, $list_id, { cursor => $cursor });
63             $lists = $r->{lists};
64            
65             $r = $nt->list_memberships($user, { cursor => $cursor });
66             $lists = $r->{lists};
67            
68             $r = $nt->list_subscriptions($user, { cursor => $cursor });
69             $lists = $r->{lists};
70            
71             $r = $nt->list_members($owner, $list_id, { cursor => $cursor });
72             $users = $r->{users};
73            
74             $r = $nt->list_subscribers($owner, $list_id, { cursor => $cursor });
75             $users = $r->{users};
76            
77             =head1 DEPRECATION NOTICE
78            
79             This module implements methods for the original Twitter Lists API. Twitter has
80             deprecated these API methods and reimplemented them with a saner semantics.
81             The new methods are implemented in the API::REST trait,
82             L<Net::Twitter::Role::API::REST>. This module provides backwards
83             compatibility for code written to use the original Lists API. To use the
84             new API methods, simply remove this trait from your code and change the
85             arguments to its methods to match the new semantics.
86            
87             This module may be dropped from L<Net::Twitter> in a future release. It will
88             remain as long as Twitter still provides the underlying API end-points.
89            
90             =head1 DESCRIPTION
91            
92             This module adds support to L<Net::Twitter> for the Twitter Lists API.
93            
94             =cut
95              
96             requires qw/username ua/;
97              
98              
99             =head1 DESCRIPTION
100            
101             B<Net::Twitter::Role::API::Lists> provides a trait for the Twitter Lists API methods.
102             See L<Net::Twitter> for full documentation.
103            
104             =cut
105              
106             has lists_api_url => ( isa => 'Str', is => 'rw', default => 'http://api.twitter.com/1' );
107              
108             base_url     'lists_api_url';
109             authenticate 1;
110              
111             our $DATETIME_PARSER = DateTime::Format::Strptime->new(pattern => '%a %b %d %T %z %Y');
112             datetime_parser $DATETIME_PARSER;
113              
114             after BUILD => sub {
115                 my $self = shift;
116              
117                 $self->{lists_api_url} =~ s/^http:/https:/ if $self->ssl;
118             };
119              
120             twitter_api_method legacy_create_list => (
121                 path => ':user/lists',
122                 method => 'POST',
123                 params => [qw/user name mode description/],
124                 required => [qw/user name/],
125                 returns => 'HashRef',
126                 description => <<'',
127             Creates a new list for the authenticated user. The C<mode> parameter may be
128             either C<public> or C<private>. If not specified, it defaults to C<public>.
129            
130             );
131              
132             twitter_api_method legacy_update_list => (
133                 path => ':user/lists/:list_id',
134                 method => 'POST',
135                 params => [qw/user list_id name mode description/],
136                 required => [qw/user list_id/],
137                 returns => 'HashRef',
138                 description => <<'',
139             Updates a list to change the name, mode, description, or any combination thereof.
140            
141             );
142              
143             twitter_api_method legacy_get_lists => (
144                 path => ':user/lists',
145                 method => 'GET',
146                 params => [qw/user cursor/],
147                 required => [qw/user/],
148                 returns => 'ArrayRef[List]',
149                 aliases => [qw/legacy_list_lists/],
150                 description => <<'EOT',
151             Returns a reference to an array of lists owned by the specified user. If the
152             user is the authenticated user, it returns both public and private lists.
153             Otherwise, it only returns public lists.
154            
155             When the C<cursor> parameter is used, a hash reference is returned; the lists
156             are returned in the C<lists> element of the hash.
157             EOT
158             );
159              
160             twitter_api_method legacy_get_list => (
161                 path => ':user/lists/:list_id',
162                 method => 'GET',
163                 params => [qw/user list_id/],
164                 required => [qw/user list_id/],
165                 returns => 'HashRef',
166                 description => <<'',
167             Returns the specified list as a hash reference.
168            
169             );
170              
171             twitter_api_method legacy_delete_list => (
172                 path => ':user/lists/:list_id',
173                 method => 'DELETE',
174                 params => [qw/user list_id/],
175                 required => [qw/user list_id/],
176                 description => <<'',
177             Deletes a list owned by the authenticating user. Returns the list as a hash
178             reference.
179            
180             );
181              
182             twitter_api_method legacy_list_statuses => (
183                 path => ':user/lists/:list_id/statuses',
184                 method => 'GET',
185                 params => [qw/user list_id since_id max_id per_page page/],
186                 required => [qw/user list_id/],
187                 returns => 'ArrayRef[Status]',
188                 description => <<'',
189             Returns a timeline of list member statuses as an array reference.
190            
191             );
192              
193             twitter_api_method legacy_list_memberships => (
194                 path => ':user/lists/memberships',
195                 method => 'GET',
196                 params => [qw/user cursor/],
197                 required => [qw/user/],
198                 description => <<'EOT',
199             Returns the lists the specified user is a member of as an array reference.
200            
201             When the C<cursor> parameter is used, a hash reference is returned; the lists
202             are returned in the C<lists> element of the hash.
203             EOT
204             );
205              
206             twitter_api_method legacy_list_subscriptions => (
207                 path => ':user/lists/subscriptions',
208                 method => 'GET',
209                 params => [qw/user cursor/],
210                 required => [qw/user/],
211                 description => <<'EOT',
212             Returns a lists to which the specified user is subscribed as an array reference.
213            
214             When the C<cursor> parameter is used, a hash reference is returned; the lists
215             are returned in the C<lists> element of the hash.
216             EOT
217             );
218              
219             twitter_api_method legacy_list_members => (
220                 path => ':user/:list_id/members',
221                 method => 'GET',
222                 params => [qw/user list_id id cursor/],
223                 required => [qw/user list_id/],
224                 returns => 'ArrayRef[User]',
225                 description => <<'EOT',
226             Returns the list members as an array reference.
227            
228             The optional C<id> parameter can be used to determine if the user specified by
229             C<id> is a member of the list. If so, the user is returned as a hash
230             reference; if not, C<undef> is returned.
231            
232             When the C<cursor> parameter is used, a hash reference is returned; the members
233             are returned in the C<users> element of the hash.
234             EOT
235             );
236              
237             around legacy_list_members => sub {
238                 my $orig = shift;
239                 my $self = shift;
240              
241                 $self->_user_or_undef($orig, 'member', @_);
242             };
243              
244             twitter_api_method legacy_is_list_member => (
245                 path => ':user/:list_id/members/:id',
246                 method => 'GET',
247                 params => [qw/user list_id id/],
248                 required => [qw/user list_id id/],
249                 returns => 'ArrayRef[User]',
250                 description => <<'EOT',
251             Returns the list member as a HASH reference if C<id> is a member of the list.
252             Otherwise, returns undef.
253             EOT
254             );
255              
256             around legacy_is_list_member => sub {
257                 my $orig = shift;
258                 my $self = shift;
259              
260                 $self->_user_or_undef($orig, 'member', @_);
261             };
262              
263             twitter_api_method legacy_add_list_member => (
264                 path => ':user/:list_id/members',
265                 method => 'POST',
266                 returns => 'User',
267                 params => [qw/user list_id id/],
268                 required => [qw/user list_id id/],
269                 description => <<'EOT',
270             Adds the user identified by C<id> to the list.
271            
272             Returns a reference the added user as a hash reference.
273             EOT
274             );
275              
276             twitter_api_method legacy_members_create_all => (
277                 aliases => [qw/legacy_add_list_members/],
278                 path => ':user/:list_id/members/create_all',
279                 method => 'POST',
280                 returns => 'ArrayRef[User]',
281                 params => [qw/user list_id screen_name user_id/],
282                 required => [qw/user list_id/],
283                 description => <<'EOT',
284             Adds multiple users C<id> to the list. Users are specified with the C<screen_name>
285             or C<user_id> parameter with a reference to an ARRAY of values.
286            
287             Returns a reference the added user as a hash reference.
288             EOT
289             );
290              
291             twitter_api_method legacy_delete_list_member => (
292                 path => ':user/:list_id/members',
293                 method => 'DELETE',
294                 params => [qw/user list_id id/],
295                 required => [qw/user list_id id/],
296                 aliases => [qw/legacy_remove_list_member/],
297                 description => <<'EOT',
298             Deletes the user identified by C<id> from the specified list.
299            
300             Returns the deleted user as a hash reference.
301             EOT
302             );
303              
304             twitter_api_method legacy_list_subscribers => (
305                 path => ':user/:list_id/subscribers',
306                 method => 'GET',
307                 params => [qw/user list_id id cursor/],
308                 required => [qw/user list_id/],
309                 returns => 'ArrayRef[User]',
310                 description => <<'EOT',
311             Returns the subscribers to a list as an array reference.
312            
313             When the C<cursor> parameter is used, a hash reference is returned; the subscribers
314             are returned in the C<users> element of the hash.
315             EOT
316             );
317              
318             around legacy_list_subscribers => sub {
319                 my $orig = shift;
320                 my $self = shift;
321              
322                 $self->_user_or_undef($orig, 'subscriber', @_);
323             };
324              
325             twitter_api_method legacy_is_list_subscriber => (
326                 path => ':user/:list_id/subscribers/:id',
327                 method => 'GET',
328                 params => [qw/user list_id id/],
329                 required => [qw/user list_id id/],
330                 returns => 'ArrayRef[User]',
331                 aliases => [qw/legacy_is_subscribed_list/],
332                 description => <<'EOT',
333             Returns the subscriber as a HASH reference if C<id> is a subscriber to the list.
334             Otherwise, returns undef.
335             EOT
336             );
337              
338             around legacy_is_list_subscriber => sub {
339                 my $orig = shift;
340                 my $self = shift;
341              
342                 $self->_user_or_undef($orig, 'subscriber', @_);
343             };
344              
345             twitter_api_method legacy_subscribe_list => (
346                 path => ':user/:list_id/subscribers',
347                 method => 'POST',
348                 returns => 'List',
349                 params => [qw/user list_id/],
350                 required => [qw/user list_id/],
351                 description => <<'',
352             Subscribes the authenticated user to the specified list.
353            
354             );
355              
356             twitter_api_method legacy_unsubscribe_list => (
357                 path => ':user/:list_id/subscribers',
358                 method => 'DELETE',
359                 returns => 'List',
360                 params => [qw/user list_id/],
361                 required => [qw/user list_id/],
362                 description => <<'',
363             Unsubscribes the authenticated user from the specified list.
364            
365             );
366              
367             for my $method ( qw/
368             create_list
369             update_list
370             get_lists
371             get_list
372             delete_list
373             list_statuses
374             list_memberships
375             list_subscriptions
376             list_members
377             is_list_member
378             add_list_member
379             members_create_all
380             delete_list_member
381             list_subscribers
382             is_list_subscriber
383             subscribe_list
384             unsubscribe_list
385             list_lists
386             add_list_members
387             remove_list_member
388             is_subscribed_list
389             / )
390             {
391                 my $legacy_method = "legacy_$method";
392                 around $method => sub {
393                     my $orig = shift;
394                     my $self = shift;
395              
396                     my $args = ref $_[-1] eq 'HASH' ? pop : {};
397                     my $legacy = exists $args->{-legacy_lists_api} ? delete $args->{-legacy_lists_api} : 1;
398                     return $self->$legacy_method(@_, $args) if $legacy;
399              
400                     $self->$orig(@_, $args);
401                 };
402             }
403              
404             1;
405              
406             __END__
407            
408             =head1 SEE ALSO
409            
410             L<Net::Twitter>
411            
412             =head1 AUTHOR
413            
414             Marc Mims <marc@questright.com>
415            
416             =head1 COPYRIGHT
417            
418             Copyright (c) 2009-2016 Marc Mims
419            
420             =head1 LICENSE
421            
422             This library is free software. You may redistribute and modify it under the
423             same terms as Perl itself.
424            
425             =cut
426