/ 
Reddit-API-0.01
/ Reddit::API

NAME

Reddit::API - A perl wrapper for Reddit

VERSION

Version 0.01

SYNOPSIS

use Reddit::API;

my $session_file = '~/.reddit';
my $reddit       = Reddit::API->new(session_file => $session_file);

unless ($reddit->is_logged_in) {
    $reddit->login('someone', 'secret');
    $reddit->save_session();
}

$reddit->submit_link(
    subreddit => 'perl',
    title     => 'Perl is still alive!',
    url       => 'http://www.perl.org'
);

my $links = $reddit->fetch_links(subreddit => '/r/perl', limit => 10);
foreach (@{$links->{items}}) {
    ...
}

DESCRIPTION

Reddit::API provides methods and simple object wrappers for objects exposed by the Reddit API. This module handles HTTP communication, basic session management (e.g. storing an active login session), and communication with Reddit's external API.

For more information about the Reddit API, see https://github.com/reddit/reddit/wiki/API.

CONSTANTS

VIEW_HOT            "Hot" links feed
VIEW_NEW            "New" links feed
VIEW_CONTROVERSIAL  "Controversial" links feed
VIEW_TOP            "Top" links feed

VIEW_DEFAULT        Default feed if not specified (VIEW_HOT)
DEFAULT_LIMIT       The default number of links to be retried (25)

VOTE_UP             Up vote
VOTE_DOWN           Down vote
VOTE_NONE           "Un" vote

SUBREDDITS_HOME     List reddits on the homepage
SUBREDDITS_POPULAR  List popular reddits
SUBREDDITS_NEW      List new reddits
SUBREDDITS_MINE     List reddits for which the logged in user is subscribed
SUBREDDITS_CONTRIB  List reddits for which the logged in user is a contributor
SUBREDDITS_MOD      List reddits for which the logged in user is a moderator

GLOBALS

$UA

This is the user agent string, and defaults to Reddit::API/$VERSION.

$DEBUG

When set to true, outputs a small amount of debugging information.

SUBROUTINES/METHODS

new(session_file => ...)

Begins a new or loads an existing reddit session. If session_file is provided, it will be read and parsed as JSON. If session data is found, it is restored. Otherwise, a new session is started.

is_logged_in

Returns true(ish) if there is an active login session. No attempt is made to validate the current session against the server.

save_session($path)

Saves the current session to $path. Throws an error if the user is not logged in. $path is only required if the Reddit::API instance was created without the session_file parameter.

load_session($path)

Attempts to load the session from $path. When successful, returns true and stores the session file path for future use.

login($usr, $pwd)

Attempts to log the user in. Throws an error on failure.

me

Returns a Reddit::API::Account object

list_subreddits($type)

Returns a list of Reddit::API::SubReddit objects for $type, where $type is a SUBREDDITS_* constant.

my_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_MINE). Throws an error if the user is not logged in.

home_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_HOME). Throws an error if the user is not logged in.

mod_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_MOD). Throws an error if the user is not logged in.

contrib_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_CONTRIB).

Syntactic sugar for list_subreddits(SUBREDDITS_POPULAR).

new_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_NEW).

info($item_id)

Returns a has of information about $item_id, which must be a complete name (e.g., t3_xxxxx).

find_subreddits($query)

Returns a list of SubReddit objects matching $query.

fetch_links(subreddit => ..., view => ..., limit => ..., before => ..., after => ...)

Returns a list of links from a reddit page. If subreddit is specified, the list of links is returned from the desired subreddit. Otherwise, the links will be from the front page. view specifieds the feed (e.g. VIEW_NEW or VIEW_HOT). limit may be used to limit the number of objects returned, and before and after denote the placeholders for slicing the feed up, just as the reddit urls themselves do. Data is returned as a hash with three keys, before, after, and items.

submit_link(subreddit => ..., title => ..., url => ...)

Submits a link to a reddit. Returns the id of the new link.

submit_text(subreddit => ..., title => ..., text => ...)

Submits a self-post to a reddit. Returns the id of the new post.

get_comments($permalink)

Returns a list ref of Reddit::API::Comment objects underneath the the specified URL $permalink. Unfortunately, this is the only method available via the API. Comments may be more easily accessed via the Link object, which implicitly provides the $permalink parameter.

my $links = $reddit->fetch_links(...);
foreach (@{$links->{items}}) {
    my $comments = $_->comments();
}
submit_comment(parent_id => ..., text => ...)

Submits a new comment underneath parent_id.

vote(item_id => ..., direction => ...)

Votes for item_id. direction is one of VOTE_UP, VOTE_DOWN, or VOTE_NONE.

save($item_id)

Saves $item_id under the user's account.

unsave($item_id)

Unsaves $item_id under the user's account.

hide($item_id)

Hides $<item_id>. Throws an error if the user does not have permission to hide the item in question.

unhide($item_id)

Unhides $<item_id>. Throws an error if the user does not have permission to unhide the item in question.

INTERNAL ROUTINES

DEBUG

When $Reddit::API::DEBUG is true, acts as syntactic sugar for warn(sprintf(@_)). Used to provided logging.

require_login

Throws an error if the user is not logged in.

subreddit

Strips slashes and leading /r from a subreddit to ensure that only the "display name" of the subreddit is returned.

build_query

URI-encodes a hash of parameters into a query suitable for use in an HTTP request. Does not include the leading '?'.

request

Performs a request to reddit's servers using LWP. If the user is logged in, adds the "uh" and "modhash" parameters to POST queries as well as adding the reddit-specified cookie value for reddit_session.

json_request

Wraps request, configuring the parameters to perform the request with an api_type of "json". After the request is complete, parses the JSON result and throws and error if one is specified in the result contents. Otherwise, returns the json data portion of the result.

api_json_request

Wraps json_request, getting method and path from an API_CONSTANT.

AUTHOR

Jeff Ober mailto:jeffober@gmail.com

LICENSE

BSD license