NAME

Reddit::Client - A Perl wrapper for the Reddit API

SYNOPSIS

    use Reddit::Client;

    my $client_id  = "DFhtrhBgfhhRTd";
    my $secret     = "KrDNsbeffdbILOdgbgSvSBsbfFs";
    my $username   = "reddit-username";
    my $password   = "reddit-password";


    # Create a Reddit::Client object and authorize in one step
    my $reddit = new Reddit::Client(
        user_agent      => 'MyScriptName 0.5 by /u/earth-tone',
        client_id       => $client_id,
        secret          => $secret,
        username        => $username,
        password        => $password,
    );
        
    # Or create object then authenticate. 
    # Useful if you need to authenticate more than once, for example if you were to check the inboxes of several accounts
    my $reddit       = Reddit::Client->new(
        user_agent   => 'MyApp/1.0',
    );

    $reddit->get_token(
        client_id       => $client_id,
        secret          => $secret,
        username        => $username,
        password        => $password,
    );


    $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::Client provides methods and object wrappers for objects exposed by the Reddit API. This module handles HTTP communication, oauth session management, 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_RISING         "Rising" 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           Remove any 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

$DEBUG

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

SUBROUTINES/METHODS

new(user_agent => , [client_id =>, secret =>, username=>, password =>])

Creates a new Reddit::Client object. Optionally authenticates at the same time. If any of the four optional arguments are used, all are required.

get_token(client_id =>, secret =>, username=>, password =>)

Get an Oauth token from Reddit. The client ID and secret come from your apps page, where you will first have to register the script: https://www.reddit.com/prefs/apps. Only the account that created the app and accounts that are registered as developers for the app will be able to use it.

For a Perl script, select a "script" type app. The "about url" and "redirect uri" can be any address; they are not used for scripts.

authorize()

Alias for get_token().

has_token()

Return true if a valid Oauth token exists.

authorized()

Alias for has_token().

me()

Returns a Reddit::Client::Account object.

info($item_id)

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

list_subreddits($type)

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

my_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_MINE).

home_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_HOME).

mod_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_MOD).

contrib_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_CONTRIB).

popular_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_POPULAR).

new_subreddits

Syntactic sugar for list_subreddits(SUBREDDITS_NEW).

find_subreddits($query)

Returns a list of SubReddit objects matching $query.

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

Returns a list of links.

All arguments are optional. If subreddit is specified, the list of links is returned from the desired subreddit or multi (i.e. "pics+new"). Otherwise, the links will be from the front page of the authenticated user (i.e. what you would see as the front page if you logged in as that user) . view specifieds the feed (e.g. VIEW_NEW or VIEW_HOT). limit may be used to limit the number of objects returned; Reddit returns a maximum of 100. 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.

delete_item(name => ...)

Deletes a post or comment. The object's full name is required.

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_subreddit_comments([subreddit => ...][before => ...][after => ...][limit => ...])

Return a list of Reddit::Client::Comment objects from a subreddit or multi. All arguments are optional. If subreddit is ommitted, a multi of the subscribed subreddits from the authenticating account will be returned (i.e. what you see when you visit reddit.com's from page and are logged in). If limit is ommitted, Reddit's default limit of 25 is used. If limit is present but false, this is interpreted as no limit and the maximum is returned (100).

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::Client::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. No longer used.

subreddit

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

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

<mailto:earth-tone@ubwg.net>

Jeff Ober mailto:jeffober@gmail.com

LICENSE

BSD license