view release on metacpan or  search on metacpan

lib/Reddit/Client.pm  view on Meta::CPAN

__END__

=pod

=head1 NAME

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

=head1 DESCRIPTION

Reddit::Client handles Oauth session management and HTTP communication with Reddit's external API. For more information about the Reddit API, see L<https://github.com/reddit/reddit/wiki/API>. 

=head1 EXAMPLE

    use Reddit::Client;
    
    # Create a Reddit::Client object and authorize: "script"-type app
    my $reddit = new Reddit::Client(
        user_agent  => "Test script 1.0 by /u/myusername",
        client_id   => "client_id_string",
        secret      => "secret_string",
        username    => "reddit_username",
        password    => "reddit_password",
    );
    
    # Create a Reddit::Client object and authorize: "web"-type app
    # Authorization can also be done separately with get_token()
    my $reddit = new Reddit::Client(
        user_agent    => "Test script 1.0 by /u/myusername",
        client_id     => "client_id_string",
        secret        => "secret_string",
        refresh_token => "refresh_token",
    );
    
    # 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       => "Change is bad, use Perl",
        url         => "http://www.perl.org",
    );
    
    # Get posts from a subreddit or multi
    my $posts = $reddit->get_links(subreddit=>'test', limit=>5);
    
    for my $post (@$posts) {
        print $post->{is_self} ? $post->{selftext} : $post->{url};
        print $post->get_web_url();

        if ($post->{title} =~ /some phrase/) {
            $post->reply("hi, I'm a bot, oops I'm banned already, harsh");
        }
    }

=head1 OAUTH

Reddit::Client uses Oauth to communicate with Reddit. To get Oauth keys, visit your apps page on Reddit, located at L<https://www.reddit.com/prefs/apps>, and create an app. There are three types of apps available. Reddit::Client supports "script" and...

=over

=item Script apps

Most new users will want a "script"-type app. This is an app intended for personal use that uses a username and password to authenticate. The I<description> and I<about url> fields can be empty, and the I<redirect URI> can be any valid URL (script ap...

Use the app's client id and secret along with your username and password to create a L<new|https://metacpan.org/pod/Reddit::Client#new> Reddit::Client object.

=item Web apps

As of v1.20, Reddit::Client also supports "web"-type apps. These are apps that can take actions on behalf of any user that grants them permission. (They use the familiar "ThisRedditApp wants your permission to..." screen.)

While they are fully supported, there is not yet a setup guide, so getting one running is left as an exercise for the reader. You will need a web server, which you will use to direct users to Reddit's authorization page, where the user will be asked ...

Documentation for the web app flow can be found at L<https://github.com/reddit-archive/reddit/wiki/OAuth2>.

=back

=head1 V1 vs. V2

v1 is "old" Reddit (the one you see if you use the subdomain old.reddit.com), v2 new (the one you see with new.reddit.com). Reddit's API has some endpoints that are for one or the other. This guide has labeled most of the v2 functions as such, but so...

When in doubt, use v2. It's usually the same as v1 but with more options, like flair, which can have extra colors and styles in New Reddit.

=head1 TERMINOLOGY

Reddit's API is slightly inconsistent in its naming. To avoid confusion, this guide will always use the following terms in the following ways:

=over

=item id

A thing's short ID without prefix. Example: 3npkj4. Seen in your address bar when viewing, for example, a post or comment. 

=item fullname

A thing's complete ID with prefix. Example: t1_3npkj4. When Reddit returns data, the fullname is usually found in the "name" field. The type of thing can be determined by the prefix; for example, t1 for comments and t3 for links.

=back

=head1 LISTINGS

Lists of things returned by the Reddit API are called I<listings>. Endpoints that return listings accept several optional parameters:

=over

C<limit>: Integer. How many things to return. Default 25, maximum 100. If I<limit> is 0, this is interpreted as "no limit" and the maximum is returned.

C<after>: Fullname. Return results that occur after I<fullname> in the listing.

C<before>: Fullname. Return results that occur before I<fullname> in the listing. 

C<only>: The string "links" or "comments". Return only links or only comments. (Obviously only relevant to listings that could contain both.)

C<show_all>: Boolean. Return items that would have been omitted, for example posts you have hidden, or have reported, or are hidden from you because you are using the option to hide posts after you've upvoted/downvoted them. Default false.

C<count>: Integer. Appears to be used by the Reddit website to number listings after the first page. Listings returned by the API are not numbered, so it does not seem to have a use in the API.

=back