1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
//! # twilight
//!
//! [![discord badge][]][discord link] [![github badge][]][github link] [![license badge][]][license link] ![rust badge]
//!
//! ![project logo][logo]
//!
//! `twilight` is a powerful, flexible, and scalable ecosystem of Rust libraries
//! for the Discord API.
//!
//! The ecosystem of first-class crates includes [`twilight-cache-inmemory`],
//! [`twilight-command-parser`], [`twilight-gateway`], [`twilight-http`],
//! [`twilight-model`], and more. These are explained in detail below.
//!
//! The main `twilight` crate is purely an advertisement crate: it has *no*
//! functionality. Please use the individual crates listed below instead!
//!
//! ## Installation
//!
//! Twilight supports a MSRV of Rust 1.49+.
//!
//! We recommend that most users start out with these crates added to your
//! `Cargo.toml`'s `[dependencies]` section:
//!
//! ```toml
//! twilight-cache-inmemory = "0.4"
//! twilight-gateway = "0.4"
//! twilight-http = "0.4"
//! twilight-model = "0.4"
//! ```
//!
//! If you need any other functionality that Twilight provides, you can just add
//! that dependency in.
//!
//! ## Core Crates
//!
//! These are essential crates that most users will use together for a full
//! development experience. You may not need all of these - such as
//! [`twilight-command-parser`] - but they are often used together to accomplish
//! most of what you need.
//!
//! ### [`twilight-model`]
//!
//! Models defining structures, enums, and bitflags for the entirety of the
//! Discord API. It is split into a number of sub-modules, such as `gateway` for
//! containing the WebSocket gateway types, `guild` for containing types owned
//! by guilds (servers), `voice` containing the types used by the Voice
//! WebSocket API, and more.
//!
//! These are all in a single crate so that you can use `gateway` models without
//! depending on [`twilight-gateway`]. One use case is if you write your own
//! WebSocket gateway implementation.
//!
//! ### [`twilight-cache-inmemory`]
//!
//! In-process-memory based cache over objects received from the gateway. It's
//! responsible for holding and managing information about things like guilds,
//! channels, role information, voice states, and any other events that come
//! from Discord.
//!
//! ### [`twilight-gateway`]
//!
//! Implementation of Discord's sharding gateway sessions. This is responsible
//! for receiving stateful events in real-time from Discord and sending *some*
//! stateful information.
//!
//! ### [`twilight-command-parser`]
//!
//! Helpful crate for parsing commands out of messages received over the
//! gateway. It finds messages commanding your bot and parses the arguments out.
//!
//! ### [`twilight-http`]
//!
//! HTTP client supporting all of the Discord REST API. It is based on `hyper`.
//! It meets Discord's ratelimiting requirements and supports proxying.
//!
//! ### [`twilight-standby`]
//!
//! Event processor that allows for tasks to wait for an event to come in. This
//! is useful, for example, when you have a reaction menu and want to wait for a
//! specific reaction on it to come in.
//!
//! ## Additional Crates
//!
//! These are crates that are officially supported by Twilight, but aren't
//! considered core crates due to being vendor-specific or non-essential for
//! most users.
//!
//! ### [`twilight-embed-builder`]
//!
//! Utility crate for creating and validating message embeds, to be used when
//! creating or updating messages.
//!
//! ### [`twilight-lavalink`]
//!
//! Client for [Lavalink] as part of the twilight ecosystem.
//!
//! It includes support for managing multiple nodes, a player manager for
//! conveniently using players to send events and retrieve information for each
//! guild, and an HTTP module for creating requests using the [`http`] crate and
//! providing models to deserialize their responses.
//!
//! ### [`twilight-mention`]
//!
//! Create display formatters for various model types that format mentions. For
//! example, it can create formatters for mentioning a channel or emoji, or
//! pinging a role or user.
//!
//! ### [`twilight-util`]
//!
//! Utility crate that adds utilities to the twilight ecosystem that do not fit
//! in any other crate. Currently, it contains:
//!
//! - A trait to make extracting data from Discord identifiers (Snowflakes)
//! easier;
//! - A calculator to calculate the permissions of a member in a guild or
//! channel.
//!
//! ### [`twilight-gateway-queue`]
//!
//! A trait and some implementations that are used by the gateway to ratelimit
//! identify calls. Developers should prefer to use the re-exports of these
//! crates through the gateway.
//!
//! ## Examples
//!
//! ```rust,no_run
//! use std::{env, error::Error};
//! use futures::stream::StreamExt;
//! use twilight_cache_inmemory::{InMemoryCache, ResourceType};
//! use twilight_gateway::{cluster::{Cluster, ShardScheme}, Event};
//! use twilight_http::Client as HttpClient;
//! use twilight_model::gateway::Intents;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
//!     let token = env::var("DISCORD_TOKEN")?;
//!
//!     // This is the default scheme. It will automatically create as many
//!     // shards as is suggested by Discord.
//!     let scheme = ShardScheme::Auto;
//!
//!     // Use intents to only receive guild message events.
//!     let (cluster, mut events) = Cluster::builder(&token, Intents::GUILD_MESSAGES)
//!         .shard_scheme(scheme)
//!         .build()
//!         .await?;
//!
//!     // Start up the cluster.
//!     let cluster_spawn = cluster.clone();
//!
//!     // Start all shards in the cluster in the background.
//!     tokio::spawn(async move {
//!         cluster_spawn.up().await;
//!     });
//!
//!     // HTTP is separate from the gateway, so create a new client.
//!     let http = HttpClient::new(&token);
//!
//!     // Since we only care about new messages, make the cache only
//!     // cache new messages.
//!     let cache = InMemoryCache::builder()
//!         .resource_types(ResourceType::MESSAGE)
//!         .build();
//!
//!     // Process each event as they come in.
//!     while let Some((shard_id, event)) = events.next().await {
//!         // Update the cache with the event.
//!         cache.update(&event);
//!
//!         tokio::spawn(handle_event(shard_id, event, http.clone()));
//!     }
//!
//!     Ok(())
//! }
//!
//! async fn handle_event(
//!     shard_id: u64,
//!     event: Event,
//!     http: HttpClient,
//! ) -> Result<(), Box<dyn Error + Send + Sync>> {
//!     match event {
//!         Event::MessageCreate(msg) if msg.content == "!ping" => {
//!             http.create_message(msg.channel_id).content("Pong!")?.await?;
//!         }
//!         Event::ShardConnected(_) => {
//!             println!("Connected on shard {}", shard_id);
//!         }
//!         // Other events here...
//!         _ => {}
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Note about tracing
//!
//! When using the `tracing` crate you won't, by default, see logs from any
//! libraries that use the `log` crate. You can add that back by using the
//! [`tracing-log`] crate and initializing it like this:
//!
//! ```rust
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! tracing_log::LogTracer::init()?;
//! # Ok(()) }
//! ```
//!
//! ## License
//!
//! All first-party crates are licensed under [ISC][LICENSE.md]
//!
//! [LICENSE.md]: https://github.com/twilight-rs/twilight/blob/main/LICENSE.md
//! [Lavalink]: https://github.com/freyacodes/Lavalink
//! [`http`]: https://crates.io/crates/http
//! [discord badge]: https://img.shields.io/discord/745809834183753828?color=%237289DA&label=discord%20server&logo=discord&style=for-the-badge
//! [discord link]: https://discord.gg/7jj8n7D
//! [docs:discord:sharding]: https://discord.com/developers/docs/topics/gateway#sharding
//! [github badge]: https://img.shields.io/badge/github-twilight-6f42c1.svg?style=for-the-badge&logo=github
//! [github link]: https://github.com/twilight-rs/twilight
//! [license badge]: https://img.shields.io/badge/license-ISC-blue.svg?style=for-the-badge&logo=pastebin
//! [license link]: https://github.com/twilight-rs/twilight/blob/main/LICENSE.md
//! [logo]: https://raw.githubusercontent.com/twilight-rs/twilight/main/logo.png
//! [rust badge]: https://img.shields.io/badge/rust-1.49+-93450a.svg?style=for-the-badge&logo=rust
//! [`tracing-log`]: https://github.com/tokio-rs/tracing/tree/master/tracing-log
//! [`twilight-cache-inmemory`]: https://twilight.rs/chapter_1_crates/section_4_cache_inmemory.html
//! [`twilight-command-parser`]: https://twilight.rs/chapter_1_crates/section_5_command_parser.html
//! [`twilight-embed-builder`]: https://twilight.rs/chapter_1_crates/section_7_first_party/section_1_embed_builder.html
//! [`twilight-gateway-queue`]: https://twilight.rs/chapter_1_crates/section_7_first_party/section_5_gateway_queue.html
//! [`twilight-gateway`]: https://twilight.rs/chapter_1_crates/section_3_gateway.html
//! [`twilight-http`]: https://twilight.rs/chapter_1_crates/section_2_http.html
//! [`twilight-lavalink`]: https://twilight.rs/chapter_1_crates/section_7_first_party/section_3_lavalink.html
//! [`twilight-mention`]: https://twilight.rs/chapter_1_crates/section_7_first_party/section_2_mention.html
//! [`twilight-model`]: https://twilight.rs/chapter_1_crates/section_1_model.html
//! [`twilight-standby`]: https://twilight.rs/chapter_1_crates/section_6_standby.html
//! [`twilight-util`]: https://twilight.rs/chapter_1_crates/section_7_first_party/section_4_util.html