Crate egg_mode [−] [src]

A library for interacting with Twitter.

Please see the repository and its enclosed examples for tips on working with this library.

Quick Start

Before you write any code with this library, head over to the Twitter Application Manager to set up an app, so you can have your consumer key and consumer secret. The complete authentication process is outlined on the Token page and given in detail on the individual method pages.

PIN-Based Authentication

To sign in as a specific user:

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
// "oob" is needed for PIN-based auth; see docs for `request_token` for more info
let request_token = egg_mode::request_token(&con_token, "oob").unwrap();
let auth_url = egg_mode::authorize_url(&request_token);

// give auth_url to the user, they can sign in to Twitter and accept your app's permissions.
// they'll receive a PIN in return, they need to give this to your application

let verifier = "123456"; //read the PIN from the user here

// note this consumes con_token; if you want to sign in multiple accounts, clone it here
let (token, user_id, screen_name) =
    egg_mode::access_token(con_token, &request_token, verifier).unwrap();

// token can be given to any egg_mode method that asks for a token
// user_id and screen_name refer to the user who signed in

See the request token docs page for more information, or for sign-in options that are easier for websites or apps that can launch a web browser more seamlessly.

Shortcut: Pre-Generated Access Token

If you only want to sign in as yourself, you can skip the request token authentication flow and instead use the access token key pair given alongside your app keys:

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
let access_token = egg_mode::KeyPair::new("access token key", "access token secret");
let token = egg_mode::Token::Access {
    consumer: con_token,
    access: access_token,
};

// token can be given to any egg_mode method that asks for a token

Bearer Tokens and App-Only Authentication

If you can get away with performing requests on behalf of your application as a whole, and not as a specific user, you can use a Bearer token instead. You still need to set up an application as before, but you can use a simpler process instead:

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
let token = egg_mode::bearer_token(&con_token).unwrap();

// token can be given to *most* egg_mode methods that ask for a token
// for restrictions, see docs for bearer_token

For more information, see the bearer token docs page.

`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.

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.
text: Text processing functions to count characters in new tweets and extract links and hashtags for highlighting and linking.

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 the Place 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.
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.
text	Helper methods for character counting and entity extraction.
tweet	Structs and functions for working with statuses and timelines.
user	Structs and methods for pulling user information from Twitter.

Structs

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 `.into_iter()` on a `Response<Vec<T>>`.
ResponseIterMut	Iterator returned by calling `.iter_mut()` on a `Response<Vec<T>>`.
ResponseIterRef	Iterator returned by calling `.iter()` on a `Response<Vec<T>>`.

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, returns 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

WebResponse

Type alias for responses from Twitter.