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 either public or private. If not specified, it defaults to public.

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 the lists 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 the lists 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 the lists 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 by id 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 the users 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 the users 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, returns undef, making it suitable for a boolean test.

is_list_subscriber

Parameters: user, list_id, id

An alias for is_subscribed_list.

SEE ALSO

Net::Twitter

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.