NAME
Net::Twitter::Role::API::Lists - Twitter Lists API support for Net::Twitter
SYNOPSIS
use Net::Twitter;
my $nt = Net::Twitter->new(traits => ['API::Lists'], ...);
$list = $nt->create_list($owner, { name => $name, description => $desc });
$list = $nt->update_list($owner, $list_id, { description => $desc });
$lists = $nt->get_lists($owner);
$lists = $nt->list_lists($owner);
$list = $nt->get_list($owner, $list_id);
$list = $nt->delete_list($owner, $list_id);
$statuses = $nt->list_statuses($owner, $list_id);
$lists = $nt->list_memberships($owner);
$lists = $nt->list_subscriptions($owner);
$users = $nt->list_members($owner, $list_id);
$user_or_undef = $nt->list_members($owner, $list_id, { id => $user_id });
$user = $nt->add_list_member($owner, $list_id, $user_id);
$user = $nt->delete_list_member($owner, $list_id, $user_id);
$user = $nt->remove_list_member($owner, $list_id, $user_id);
$user_or_undef = $nt->is_list_member($owner, $list_id, $user_id);
$users = $nt->list_subscribers($owner, $list_id);
$list = $nt->subscribe_list($owner, $list_id);
$list = $nt->unsubscribe_list($owner, $list_id);
$user_or_undef = $nt->is_subscribed_list($owner, $list_id, $user_id);
$user_or_undef = $nt->is_list_subscriber($owner, $list_id, $user_id);
#############################
# With the cursor parameter #
#############################
$r = $nt->get_list($user, $list_id, { cursor => $cursor });
$lists = $r->{lists};
$r = $nt->list_memberships($user, { cursor => $cursor });
$lists = $r->{lists};
$r = $nt->list_subscriptions($user, { cursor => $cursor });
$lists = $r->{lists};
$r = $nt->list_members($owner, $list_id, { cursor => $cursor });
$users = $r->{users};
$r = $nt->list_subscribers($owner, $list_id, { cursor => $cursor });
$users = $r->{users};
DESCRIPTION
This module adds support to Net::Twitter for the Twitter Lists API.
METHODS
The API::Lists methods can be called with positional parameters for the parameters used to compose the URI path. Additional parameters, including both required and optional parameters are passed in a HASH reference as the final argument to the method. All parameters may be passed in the HASH ref, if preferred.
Most methods take a list_id
parameter. You can pass either the numeric ID of the list or the list's slug
. Both are returned by by the create_list
call: $list->{id}
and $list->{slug}
respectively.
The slug
changes if the list is renamed. The numeric ID does not.
The slug
is a URI safe identifier assigned by Twitter for each list, based on the list's name. A slug
is unique to a list owner, but is not globally unique.
Many methods take an optional cursor
parameter. See "Cursors and Paging" in Net::Twitter for details on using the cursor
parameter. Without the cursor parameter, these methods return a reference to an array of results (users, or lists). With it, they return a reference to a hash that contains next_cursor
, previous_cursor
, and either users
, or lists
, as appropriate, which is a reference to the array of results.
- new
-
This role makes the following additional arguments available to new.
- lists_api_url
-
The base URL for the Twitter Lists API. Defaults to
http://api.twitter.com/1
- create_list
-
Parameters: user [ name, mode, description ] Required: user, name
Creates a new list for the authenticated user. The
mode
parameter may be eitherpublic
orprivate
. If not specified, it defaults topublic
.Returns the list as a hash reference.
- update_list
-
Parameters: user, list_id, [ name, mode, description ]
Updates a list to change the name, mode, description, or any combination thereof.
Returns the list as a hash reference.
- get_lists
-
Parameters: user, [ cursor ]
Returns a reference to an array of lists owned by the specified user. If the user is the authenticated user, it returns both public and private lists. Otherwise, it only returns public lists.
When the
cursor
parameter is used, a hash reference is returned; the lists are returned in thelists
element of the hash. - list_lists
-
An alias for get_lists
- get_list
-
Parameters: user, list_id
Returns the specified list as a hash reference.
- delete_list
-
Parameters: user, list_id
Deletes a list owned by the authenticating user. Returns the list as a hash reference.
- list_statuses
-
Parameters: user, list_id, [ since_id, max_id, per_page, page ]
Returns a timeline of list member statuses as an array reference.
- list_memberships
-
Parameters: user, [ cursor ]
Returns the lists the specified user is a member of as an array reference.
When the
cursor
parameter is used, a hash reference is returned; the lists are returned in thelists
element of the hash. - list_subscriptions
-
Parameters: user, [ cursor ]
Returns a lists to which the specified user is subscribed as an array reference.
When the
cursor
parameter is used, a hash reference is returned; the lists are returned in thelists
element of the hash. - list_members
-
Parameters: user, list_id, [ id, cursor ]
Returns the list members as an array reference.
The optional
id
parameter can be used to determine if the user specified byid
is a member of the list. If so, the user is returned as a hash reference; if not,undef
is returned.When the
cursor
parameter is used, a hash reference is returned; the members are returned in theusers
element of the hash. - add_list_member
-
Parameters: user, list_id, id
Adds the user identified by
id
to the list.Returns a reference the added user as a hash reference.
- delete_list_member
-
Parameters: user, list_id, id
Deletes the user identified by
id
from the specified list.Returns the deleted user as a hash reference.
- remove_list_member
-
Parameters: user, list_id, id
An alias for
delete_list_member
. - is_list_member
-
Parameters: user, list_id, id
Check to see if the user identified by
id
is a member of the specified list. Returns the user as a hash reference if so,undef
if not making it suitable for boolean tests. - list_subscribers
-
Parameters: user, list_id, [ cursor ]
Returns the subscribers to a list as an array reference.
When the
cursor
parameter is used, a hash reference is returned; the subscribers are returned in theusers
element of the hash. - subscribe_list
-
Parameters: user, list_id
Subscribes the authenticated user to the specified list.
Returns the list as a hash reference.
- unsubscribe_list
-
Parameters: user, list_id
Unsubscribes the authenticated user from the specified list.
Returns the list as a hash reference.
- is_subscribed_list
-
Parameters: user, list_id, id
Check to see if the user identified by
id
is subscribed to the specified list. If subscribed, returns the user as a hash reference, otherwise, returnsundef
, making it suitable for a boolean test. - is_list_subscriber
-
Parameters: user, list_id, id
An alias for
is_subscribed_list
.
SEE ALSO
AUTHOR
Marc Mims <marc@questright.com>
COPYRIGHT
Copyright (c) 2009 Marc Mims
LICENSE
This library is free software. You may redistribute and modify it under the same terms as Perl itself.