/ 
Reddit-Client-1.083
River stage one • 1 direct dependent • 2 total dependents
/ Reddit::Client

NAME

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

The official documentation can be found at http://redditclient.readthedocs.org/en/latest/. What follows below might not be wrong but is not guaranteed to be right, and the likelihood of it being wrong increases with time.

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 authorize.
    # Useful if you need to switch between accounts, for example if you were to check the inboxes of several accounts.
    my $reddit = Reddit::Client->new(
        user_agent   	=> 'MyApp/1.0 by /u/earth-tone',
    );

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

    # Check your inbox
    my $me = $reddit->me();
    print "You've got mail!" if $me->{has_mail};

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

    # Submit a text post
    $reddit->submit_text(
	subreddit 	=> 'test',
	title		=> 'my test',
	text		=> 'a test'
    );

    # Get posts from a subreddit or multi
    my $posts = $reddit->fetch_links(subreddit=>'test', limit=>5);
    foreach my $post (@$posts) {
	print $post->{title} . "\n";
	if (!$post->{is_self}) { # Is it a self post or a link?
		print $post->{url};
	} else {
		print $post->{selftext};
	}
    }

    # Get comments from a subreddit or multi
    my $cmts = $reddit->get_subreddit_comments('test');
    foreach my $cmt (@$cmts) {
	print "$cmt->{author} says: $cmt->{body}\n";
    }

DESCRIPTION

Reddit::Client provides methods and object wrappers for objects exposed . 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.

Beginning August 3rd, 2015, the Reddit API requires Oauth authentication. This amounts to two extra arguments at the beginning of your script; in exchange you you twice as many requests per minute as before (60 vs 30) and some added convenience on the back end.

To get Oauth keys, visit your apps page: https://www.reddit.com/prefs/apps. Choose a "script" type app. None of the other fields are needed for a script type app; you can put in 127.0.0.1 for the URLs or whatever you like.

Every account that uses this script must have permission to use it. So for example if you were to check the inboxes of your various accounts, each one would need permission. To add accounts click "add developer" on the right, after you've created the app.

Methods

These are the methods of the Reddit::Client class.

Two notes about methods that return lists of things:

1. All methods that return lists of things return them as a Perl _list_-- that is, a reference to an anonymous array. In practice this means that you get at the values with `@$array` instead of `@array`.

2. All methods that return lists of things accept three optional parameters: `limit`, `before`, and `after`. You may recognize them from your address bar when viewing pages after the front page. `limit` defaults to 25, maximum 100. If `limit` is present but false, this is interpreted as "no limit" and the max is returned.

B<limit> I<integer> How many things to return. Default 25, maximum 100. If `limit`  is present but false, this is interpreted as "no limit" and the max is returned.

B<before> I<fullname> Return results that occur before `fullname`. 

B<after> I<fullname> Return results that occur after `fullname`.
delete
delete ( $fullname )

Delete a post or comment.

edit_wiki
    edit_wiki ( subreddit => $subreddit, page => $page, content => $content,
				[ previous => $previous_version_number,] [ reason => $edit_reason, ] )
	
	* `page` is the page being edited.
	* `content` is the new page content. Can be empty but must be defined. Maximum 524,288 characters.
	* `reason` is the edit reason. Max 256 characters, will be truncated if longer. Optional.
	* `previous` is the ID of the intended previous version of the page; if provided, that is the version the page will be rolled back to in a rollback. However, there's no way to find out what this should be from the Reddit website, or currently from Reddit::Client either. Use it only if you know what you're doing. Optional.
find_subreddits
    find_subreddits ( q => $query, [ sort => 'relevance' ,] 
					[ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )

Returns a list of Subreddit objects matching the search string `$query`. Optionally sort them by `sort`, which can be "relevance" or "activity".

get_comment
get_comment ( $fullname )

Returns a [Comment](classes/comment) object for `$fullname`.

get_flair_options
    get_flair_options( subreddit => $subreddit, post_id => $post_id_or_fullname, username => $username )

Return the flair options for either the post or the user provided.

Returns a hash containing two keys:

* `choices` is an array of hash references containing the flair options. Most important is `flair_template_id`, which is used to set the flair of a post or user with set_post_flair or set_user_flair. `flair_text` contains the text of the flair. * `current` is a hash of the post or user's existing flair.

get_inbox
    get_inbox ( [ view => MESSAGES_INBOX ,] [ limit => DEFAULT_LIMIT ,]
	            [ before => undef ,] [ after => undef ,] )

Returns a list of [Message](classes/message) objects, where `view` is one of the MESSAGE [constants](constants). All arguments are optional. If all are omitted your default inbox will be returned-- what you would see if you went to reddit.com and clicked the mailbox icon.

Checking your inbox via the API doesn't mark it as read. To do that you'll need to call [mark_inbox_read](http://redditclient.readthedocs.org/en/latest/main-methods/#mark_inbox_read).

get_link ( $fullname )

Returns a [Link](classes/link) object for `$fullname`.

    get_links ( [ subreddit => undef ,] [ view => VIEW_DEFAULT ,] [ limit => DEFAULT_LIMIT ,]
	            [ before => undef ,] [ after => undef ,] )

Returns a list of [Link](classes/link) objects. All arguments are optional.

`subreddit` can be a subreddit or multi (ex: "pics+funny"). If omitted, results from the user's front page will be returned-- i.e. what you would see if you visited reddit.com as that user.

`view` is a feed type [constant](constants)-- i.e. VIEW_HOT, VIEW_NEW, etc.

fetch_links is an alias for get_links.

    get_permalink ( $comment_id, $post_id )

Returns a permalink for `$comment_id`. **If you already have a [Comment](classes/comment) object, use its get_permalink function instead**, aka `$comment->get_permalink()`.

This version causes an extra request because it has to ask Reddit for the parent post's URL first, while a Comment object already has that information. It's provided for backwards compatibility, and for the rare case when you may have a comment's ID but not a comment object (perhaps you have a list of IDs stored in a database). It may be deprecated in the future.

`$comment_id` and `$post_id` can be either fullnames or short IDs.

get_subreddit_comments
get_subreddit_comments ( [ subreddit => '' ,] [ view => VIEW_DEFAULT ,] [ limit => DEFAULT_LIMIT ,]
                         [ before => undef ,] [ after => undef ,]  )

Returns a list of [Comment](classes/comment) objects from a subreddit or multi.

All arguments are optional. If subreddit is omitted the account's "front page" subreddits are returned (i.e. what you see when you visit reddit.com and are logged in).

`view` is a feed type [constant](constants)-- i.e. VIEW_HOT, VIEW_NEW, etc.

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

Get an Oauth token from Reddit. This is analogous to the old login function, and can be considered identical, with the exception that, if your script runs continuously for more than an hour, a new token will be obtained hourly.

get_user
    get_user ( [ user => $username ,] [ view => USER_OVERVIEW ,]
               [ limit => DEFAULT_LIMIT ,][ before => undef ,] [ after => undef ,]  )

Get information about a user, where `view` is one of the [user constants](constants): overview, comments, submitted, gilded, upvoted, downvoted, hidden, or saved. Defaults to overview, which shows the user's most recent comments and posts.

Note that if you try to get the upvoted, downvoted, hidden, or saved activity for a user other than yourself, Reddit will return a 403 error, so be sure to [wrap requests in a try/catch](http://redditclient.readthedocs.org/en/latest/examples/#catch-exceptions) if there's any chance that might happen. (Of course, all requests should be wrapped in a try/catch anyway, the internet being an unpredictable place.)

The result can be a list of [Links](classes/link), [Comments](classes/comment), or a mix of both, depending on what `view` you requested. You can determine which is which by looking at the type property, which is "t1" for comments and "t3" for posts.

has_token
has_token()

Return true if a valid Oauth token exists.

hide
hide ( $fullname )

Hide a post.

info
info ( $fullname )

Returns a hash of information about `$fullname`. `$fullname` can be any of the 8 types of thing.

list_subreddits
list_subreddits ( [ view => SUBREDDITS_HOME ,] [ limit => DEFAULT_LIMIT ,]
                  [ before => undef ,] [ after => undef ,]  )

Returns a list of subreddits, where `view` is one of the SUBREDDIT [constants](constants).

An alias function is provided for each view type, which is the same as calling `list_subreddits` with the view already provided:

* contrib_subreddits ( [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] ) * home_subreddits ( [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] ) * mod_subreddits ( [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] ) * my_subreddits ( [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] ) * new_subreddits ( [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] ) * popular_subreddits ( [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )

mark_inbox_read
mark_inbox_read()

Mark everything in your inbox as read. May take some time to complete.

me
me()

Return an [Account](classes/account) object that contains information about the logged in account. Aside from static account information it contains the `has_mail` property, which will be true if there is anything in your inbox.

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

Instantiate a Reddit::Client object. Optionally get an Oauth token (analogous to logging in) at the same time. If any of the four optional arguments are used, all are required.

`$user_agent` is always required, and should be something descriptive that uniquely identifies your app. The [API Rules](https://github.com/reddit/reddit/wiki/API#rules) says it should be

>something unique and descriptive, including the target platform, a unique application identifier, a version string, and your username as contact information

It also includes this warning:

>**NEVER lie about your user-agent.** This includes spoofing popular browsers and spoofing other bots. We will ban liars with extreme prejudice.

save
save ( $fullname )

Save a post or comment.

send_message
send_message ( to => $username, subject => $subject, text => $message )

Send a private message to `$username`. `$subject` is limited to 100 characters.

set_post_flair
    set_post_flair ( subreddit => $subreddit, post_id => $post_id_or_fullname, flair_template_id => $flair_id )

Set the flair on a post. The 'flair_template_id' is acquired via [get_flair_options](main-methods/#get_flair_options).

set_user_flair
    set_user_flair ( subreddit => $subreddit, username => $username, flair_template_id => $flair_id )

Set the flair for a user. The 'flair_template_id' is acquired via [get_flair_options](/main-methods/#get_flair_options).

submit_comment
submit_comment ( parent_id => $fullname, text => $text)

Submit a comment under `$fullname`, which must be a post or comment. Returns fullname of the new comment.

submit_link ( subreddit => $subreddit, title => $title, url => $url, [ inbox_replies => 1 ] )

Submit a link. Returns the fullname of the new post. If `inbox_replies` is set and is false, disable inbox replies for that post.

submit_text
submit_text ( subreddit => $subreddit, title => $title, text => $text, [ inbox_replies => 1 ] )

Submit a text post. Returns the fullname of the new post. If `inbox_replies` is set and is false, disable inbox replies for that post.

unhide
unhide ( $fullname )

Unhide a post.

unsave
unsave ( $fullname )

Unsave a post or comment.

version
version()

Return the Reddit::Client version.

vote
vote ( $fullname, $direction )

Vote on a post or comment. Direction must be 1, 0, or -1 (0 to clear votes).

AUTHOR

mailto:earth-tone@ubwg.net

LICENSE

BSD license