Crate rawr [−] [src]

rawr - Rust API Wrapper for Reddit

This crate provides simple yet powerful access to the Reddit API.

Quick Start

This section will teach you the basics of rawr, so you can get started with your project easily.

To create a client to access the Reddit API, you can use the RedditClient class. All you need to do is pass in the user agent when creating the client to have anonymous access. In order to post or reply, you need to log in (which will be explained soon!).

As well as passing in a user agent, you need to pass in an authenticator, which handles logging in and proving who you are to Reddit. For now, we'll log in anonymously with AnonymousAuthenticator. You'll definitely want to take a look at the auth module documentation to find out how to log in to an account.

use rawr::client::RedditClient;
use rawr::auth::AnonymousAuthenticator;
let client = RedditClient::new("my user agent", AnonymousAuthenticator::new());

It is important that you pick a good user agent. The ideal format is platform:program:version (by /u/yourname), e.g. linux:rawr:v0.0.1 (by /u/Aurora0001).

Getting a List of Posts

First, you'll need to select the subreddit that you want to get a listing from. For our example, we'll use /r/all. To get that subreddit, we can do this:

let client = RedditClient::new("?:rawr:doc-tests", AnonymousAuthenticator::new());
let all = client.subreddit("all");

Once we have the subreddit object, we can get the post list. There are several listing types provided by Reddit: - Hot - the default sort, which shows the 'best' posts at this moment. - New - posts ordered from newest to oldest. - Rising - posts gaining in popularity (usually, this is quite a short listing and only has 10-20 items)

There are also 'time-scoped' listings that require a timespan as well. This is essentially the same as the 'links from: all time' dropdown. - Controversial - posts that have received lots of upvotes and downvotes. - Top - posts that have the highest score overall.

Here's an example of using the hot listing:

use rawr::options::ListingOptions;
let listing = all.hot(ListingOptions::default()).expect("Request unsuccessful");

Why do I need the expect call? Since it is possible for a request to the API to fail, most of the API wrapper returns Result<_, APIError> where _ is the actual value from the API. This allows you to handle the error gracefully if you want, but for our examples we will always use expect to simplify the examples.

The ListingOptions object is used to configure various options such as the amount of posts to fetch in each request and the anchor. For more information, see the documentation for ListingOptions.

Using the Post Listing

The Listing objects implement Iterator, which means it's really convenient to loop through multiple posts. You can just use a for loop, like this:

let listing = all.hot(ListingOptions::default()).expect("Could not fetch posts");
for post in listing {
    println!("{}", post.title());
}

Getting Replies

If you're interested in the replies to a post, you can get them using the replies() method. replies() returns a CommentList, which acts a lot like a Listing in that it will automatically fetch more comments as needed. However, unlike post listings, the comments section is threaded, so you can get the replies() to a comment as well.

Here's how to get the first comment (if available) for every post in the /r/all/hot listing:

use rawr::traits::{Commentable, Content};
let all = client.subreddit("all");
for post in all.hot(ListingOptions::default()).expect("Request failed") {
    if let Some(comment) = post.replies().expect("Could not get replies").next() {
        println!("{}", comment.author().name);
    }
}

'What were those traits about?', I hear you say. The Commentable trait provides functions to work with comments and manipulate them. The Commentable trait is implemented in both the Comment struct and the Submission struct, because you can comment on either. This also explains why you can get the replies() for a Comment using the same interface.

The Content trait is a little bit different. Things that implement Content were created by a user and exist in a subreddit (so they're either submissions or comments). You can use this trait to delete posts, get the author or get the parent subreddit.

Replying

The Commentable trait also allows your client to reply to anything that implements it. You can reply like this:

let all = client.subreddit("all");
let mut listing = all.hot(ListingOptions::default()).expect("Request failed");
if let Some(top_post) = listing.next() {
    top_post.reply("This is cool... I think. I'm a bot.").expect("Posting failed!");
}

Most actions in the API return a Result so you can handle any errors that occur. In this example, we just use expect(), but real code should handle this more gracefully, otherwise the code may panic. Be prepared to accept HTTP 5xx errors if reddit is having trouble with their servers; this will be returned to you as a APIError::HTTPError with the error status in the enum variant.

Posting a Thread

Reddit has two types of submissions: link posts and self posts. Link posts are hyperlinked to their URL, but have no body text. Self posts have a body but don't link anywhere. Both earn karma.

To post a link post, you can use the submit_link() method. First, you need to create a LinkPost object that can configure your post, like this:

use rawr::options::LinkPost;
let post = LinkPost::new("title", "https://example.com");

If that link has been posted previously in the subreddit, you need to mark it as a repost, like this:

let post = LinkPost::new("title", "https://example.com").resubmit();

You can then submit it, like this:

use rawr::options::LinkPost;
let programming = client.subreddit("programming");
let post = LinkPost::new("I love Rust!", "https://rust-lang.org");
programming.submit_link(post).expect("Could not submit link!");

Submitting a self post is largely the same, but the resubmit function is not available on the SelfPost struct. Example:

use rawr::options::SelfPost;
let programming = client.subreddit("programming");
let post = SelfPost::new("I love Rust!", "It's great! **Wow**!");
programming.submit_text(post).expect("Could not submit link!");

More Advanced Features

rawr also supports: - Getting a user by name (see RedditClient.user("name")) - Setting user flairs (see the user module) - Setting post flairs (see Submission.flair) - Getting 'about' information (see Subreddit.about())

Not Yet Implemented

Multireddits
Live Threads

Want to help? Take a look at the issue tracker!

Modules

auth	Whenever you create a `RedditClient`, you need to provide an `Authenticator` that can log in for you and send credentials with every request. Reddit's API provides multiple ways to authenticate, and it's important that you use the correct one for your application so that you only take passwords where necessary.
client	A client that represents one connection to the Reddit API. This can log in to one account or remain anonymous, and performs all interactions with the Reddit API.
errors	Error types used to signal problems with requests.
options	Configuration options for API requests.
prelude	Basic `rawr` structures to import with `use rawr::prelude::*`;
responses	Deserialized API responses.
structures	Reddit structures such as submissions, comments and subreddits.
traits	Traits for common API functionality.