[−][src]Crate egg_mode
A library for interacting with Twitter.
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:
- This library provides several types which implement the
Future
trait, but does not describe how to interact with them. The examples use theblock_on_all
method from tokio's runtime to show a synchronous interaction, but more advanced scenarios are beyond the scope of this documentation. See the tokio documentation for more information. - Twitter tracks API use through "tokens" which are managed by Twitter and processed separately
for each "authenticated user" you wish to connect to your app. egg-mode's Token
documentation describes how you can obtain one of these, but each example outside of the
authentication documentation brings in a
Token
"offscreen", to avoid distracting from the rest of the example.
To load the profile information of a single user:
use tokio::runtime::current_thread::block_on_all; let rustlang = block_on_all(egg_mode::user::show("rustlang", &token)).unwrap(); println!("{} (@{})", rustlang.name, rustlang.screen_name);
To post a new tweet:
use tokio::runtime::current_thread::block_on_all; use egg_mode::tweet::DraftTweet; let post = block_on_all(DraftTweet::new("Hey Twitter!").send(&token)).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.
tweet
: This module lets you act on tweets. Here you can find actions to load a user's timeline, post a new tweet, or like and retweet individual posts.user
: This module lets you act on users, be it by following or unfollowing them, loading their profile information, blocking or muting them, or showing the relationship between two users.search
: Due to the complexity of searching for tweets, it gets its own module.direct
: Here you can work with a user's Direct Messages, either by loading DMs they've sent or received, or by sending new ones.list
: This module lets you act on lists, from creating and deleting them, adding and removing users, or loading the posts made by their members.media
: This module lets you upload images, GIFs, and videos to Twitter so you can attach them to tweets.
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.
place
: Here are actions that look up physical locations that can be attached to tweets, as well at thePlace
struct that appears on tweets with locations attached.service
: These are some miscellaneous methods that show information about the Twitter service as a whole, like loading the maximum length of t.co URLs or loading the current Terms of Service or Privacy Policy.
Helper structs
These modules contain some implementations that wrap some pattern seen in multiple "action" modules.
cursor
: This contains a helper trait and some helper structs that allow effective cursoring through certain collections of results from Twitter.entities
: Whenever some text can be returned that may contain links, hashtags, media, or user mentions, its metadata is parsed into something that lives in this module.error
: Any interaction with Twitter may result in an error condition, be it from finding a tweet or user that doesn't exist or the network connection being unavailable. All the error types are aggregated into an enum in this module.
Modules
cursor | Types and traits to navigate cursored collections. |
direct | Structs and methods for working with direct messages. |
entities | Data structures containing extracted URL, mention, tag, and media information. |
error | A composite error type for errors that can occur while interacting with Twitter. |
list | Structs and functions for working with lists. |
media | Functionality to upload images, GIFs, and videos that can be attached to tweets. |
place | Types and methods for looking up locations. |
search | Structs and methods for searching for tweets. |
service | Methods to inquire about the Twitter service itself. |
stream | Access to the Streaming API. |
tweet | Structs and functions for working with statuses and timelines. |
user | Structs and methods for pulling user information from Twitter. |
Structs
AuthFuture |
|
KeyPair | A key/secret pair representing an OAuth token. |
Response | A helper struct to wrap response data with accompanying rate limit information. |
ResponseIter | Iterator returned by calling |
ResponseIterMut | Iterator returned by calling |
ResponseIterRef | Iterator returned by calling |
TwitterFuture | A |
Enums
Token | A token that can be used to sign requests to Twitter. |
Functions
access_token | With the given OAuth tokens and verifier, ask Twitter for an access KeyPair that can be used to sign further requests to the Twitter API. |
authenticate_url | With the given request KeyPair, return a URL to redirect a user to so they can accept or reject an authorization request. |
authorize_url | With the given request KeyPair, return a URL that a user can access to accept or reject an authorization request. |
bearer_token | With the given consumer KeyPair, request the current Bearer token to perform Application-only authentication. |
invalidate_bearer | Invalidate the given Bearer token using the given consumer KeyPair. Upon success, the future returned by this function yields the Token that was just invalidated. |
request_token | With the given consumer KeyPair, ask Twitter for a request KeyPair that can be used to request access to the user's account. |
verify_tokens | If the given tokens are valid, return the user information for the authenticated user. |
Type Definitions
FutureResponse | Type alias for futures that resolve to responses from Twitter. |