egg-mode

egg_mode

A library for interacting with Twitter.

Repository

egg-mode is a Twitter library that aims to make as few assumptions about the user's codebase as possible. Endpoints are exposed as bare functions where authentication details are passed in as arguments, rather than as builder functions of a root "service" manager. The only exceptions to this guideline are endpoints with many optional parameters, like posting a status update or updating the metadata of a list.

About the examples in this documentation

There are a couple prerequisites to using egg-mode, which its examples also assume:

To load the profile information of a single user:

# extern crate egg_mode; extern crate tokio_core;
# use egg_mode::Token; use tokio_core::reactor::{Core, Handle};
# fn main() {
# let (token, mut core, handle): (Token, Core, Handle) = unimplemented!();
let rustlang = core.run(egg_mode::user::show("rustlang", &token, &handle)).unwrap();

println!("{} (@{})", rustlang.name, rustlang.screen_name);
# }

To post a new tweet:

# extern crate egg_mode; extern crate tokio_core;
# use egg_mode::Token; use tokio_core::reactor::{Core, Handle};
use egg_mode::tweet::DraftTweet;
# fn main() {
# let (token, mut core, handle): (Token, Core, Handle) = unimplemented!();

let post = core.run(DraftTweet::new("Hey Twitter!").send(&token, &handle)).unwrap();
# }

Types and Functions

All of the main content of egg-mode is in submodules, but there are a few things here in the crate root. To wit, it contains items related to authentication and a couple items that all the submodules use.

Response<T>

Every method that calls Twitter and carries rate-limit information wraps its return value in a Response struct, that transmits this information to your app. From there, you can handle the rate-limit information to hold off on that kind of request, or simply grab its response field to get the output of whatever method you called. Response also implements Deref, so for the most part you can access fields of the final result without having to grab the response field directly.

Response also has IntoIterator implementations and iterator creation methods that echo those on Vec<T>, for methods that return Vecs. These methods and iterator types distribute the rate-limit information across each iteration.

TwitterFuture<'a, T>

Any method that requires a network call will return a handle to the pending network call, in most cases the type TwitterFuture. This type (and any other *Future in this library) implements the Future trait, for use as an asynchronous network call. All Future implementations in this library use the Error enum as their Error value. For more information on how to use the Future trait, check out the Tokio documentation guides.

In addition, there is also a FutureResponse type alias, that corresponds to TwitterFuture<'a, Response<T>>, for methods that return rate-limit information.

Authentication Types/Functions

The remaining types and methods are explained as part of the authentication overview, with the exception of verify_tokens, which is a simple method to ensure a given token is still valid.

Modules

As there are many actions available in the Twitter API, egg-mode divides them roughly into several modules by their shared purpose. Here's a sort of high-level overview, in rough order from "most important" to "less directly used":

Primary actions

These could be considered the "core" actions within the Twitter API that egg-mode has made available.

Secondary actions

These modules still contain direct actions for Twitter, but they can be considered as having more of a helper role than something you might use directly.

Helper structs

These modules contain some implementations that wrap some pattern seen in multiple "action" modules.