serenity/
lib.rs

1//! Serenity is a Rust library for the Discord API.
2//!
3//! View the [examples] on how to make and structure a bot.
4//!
5//! Serenity supports bot user authentication via the use of [`Client::builder`].
6//!
7//! Once logged in, you may add handlers to your client to dispatch [`Event`]s, such as
8//! [`EventHandler::message`]. This will cause your handler to be called when a
9//! [`Event::MessageCreate`] is received. Each handler is given a [`Context`], giving information
10//! about the event. See the [client's module-level documentation].
11//!
12//! The [`Shard`] is transparently handled by the library, removing unnecessary complexity. Sharded
13//! connections are automatically handled for you. See the [gateway's documentation][gateway docs]
14//! for more information.
15//!
16//! A [`Cache`] is also provided for you. This will be updated automatically for you as data is
17//! received from the Discord API via events. When calling a method on a [`Context`], the cache
18//! will first be searched for relevant data to avoid unnecessary HTTP requests to the Discord API.
19//! For more information, see the [cache's module-level documentation][cache docs].
20//!
21//! Note that, although this documentation will try to be as up-to-date and accurate as possible,
22//! Discord hosts [official documentation][docs]. If you need to be sure that some information
23//! piece is sanctioned by Discord, refer to their own documentation.
24//!
25//! ### Full Examples
26//!
27//! Full examples, detailing and explaining usage of the basic functionality of the library, can be
28//! found in the [`examples`] directory.
29//!
30//! # Installation
31//!
32//! Add the following to your `Cargo.toml` file:
33//!
34//! ```toml
35//! [dependencies]
36//! serenity = "0.12"
37//! ```
38//!
39//! [`Cache`]: crate::cache::Cache
40//! [`Context`]: crate::client::Context
41//! [`EventHandler::message`]: crate::client::EventHandler::message
42//! [`Event`]: crate::model::event::Event
43//! [`Event::MessageCreate`]: crate::model::event::Event::MessageCreate
44//! [`Shard`]: crate::gateway::Shard
45//! [`examples`]: https://github.com/serenity-rs/serenity/blob/current/examples
46//! [cache docs]: crate::cache
47//! [client's module-level documentation]: crate::client
48//! [docs]: https://discord.com/developers/docs/intro
49//! [examples]: https://github.com/serenity-rs/serenity/tree/current/examples
50//! [gateway docs]: crate::gateway
51#![doc(html_root_url = "https://docs.rs/serenity/*")]
52#![cfg_attr(docsrs, feature(doc_cfg))]
53#![warn(
54    unused,
55    rust_2018_idioms,
56    clippy::unwrap_used,
57    clippy::clone_on_ref_ptr,
58    clippy::non_ascii_literal,
59    clippy::fallible_impl_from,
60    clippy::let_underscore_must_use,
61    clippy::format_collect,
62    clippy::format_push_string,
63    clippy::pedantic
64)]
65#![allow(
66    // Allowed to avoid breaking changes.
67    clippy::module_name_repetitions,
68    clippy::struct_excessive_bools,
69    clippy::result_large_err,
70    clippy::unused_self,
71    // Allowed as they are too pedantic
72    clippy::cast_possible_truncation,
73    clippy::unreadable_literal,
74    clippy::cast_possible_wrap,
75    clippy::wildcard_imports,
76    clippy::cast_sign_loss,
77    clippy::too_many_lines,
78    clippy::doc_markdown,
79    clippy::cast_lossless,
80    clippy::redundant_closure_for_method_calls,
81    // Covered by other lints
82    clippy::missing_panics_doc, // clippy::unwrap_used
83)]
84#![cfg_attr(test, allow(clippy::unwrap_used))]
85#![type_length_limit = "3294819"] // needed so ShardRunner::run compiles with instrument.
86
87#[macro_use]
88extern crate serde;
89
90#[macro_use]
91mod internal;
92
93pub mod constants;
94pub mod json;
95pub mod model;
96pub mod prelude;
97
98#[cfg(feature = "builder")]
99pub mod builder;
100#[cfg(feature = "cache")]
101pub mod cache;
102#[cfg(feature = "client")]
103pub mod client;
104#[cfg(feature = "collector")]
105pub mod collector;
106#[cfg(feature = "framework")]
107pub mod framework;
108#[cfg(feature = "gateway")]
109pub mod gateway;
110#[cfg(feature = "http")]
111pub mod http;
112#[cfg(feature = "interactions_endpoint")]
113pub mod interactions_endpoint;
114#[cfg(feature = "utils")]
115pub mod utils;
116
117mod error;
118
119// For the procedural macros in `command_attr`.
120pub use async_trait::async_trait;
121pub use futures;
122pub use futures::future::FutureExt;
123#[cfg(feature = "standard_framework")]
124#[doc(hidden)]
125pub use static_assertions;
126
127#[cfg(all(feature = "client", feature = "gateway"))]
128pub use crate::client::Client;
129pub use crate::error::{Error, Result};
130
131#[cfg(feature = "absolute_ratelimits")]
132compile_error!(
133    "The absolute_ratelimits feature has been removed.\n\
134    Configure absolute ratelimits via Ratelimiter::set_absolute_ratelimits.\n\
135    You can set the Ratelimiter of Http via HttpBuilder::ratelimiter."
136);
137
138/// Special module that re-exports most public items from this crate.
139///
140/// Useful, because you don't have to remember the full paths of serenity items.
141///
142/// Not exported:
143/// - [`crate::json`]: it's a general-purpose JSON wrapper, not intrinsic to serenity
144/// - [`crate::framework::standard`]: has many standard_framework-specific items that may collide
145///   with items from the rest of serenity
146pub mod all {
147    #[cfg(feature = "builder")]
148    #[doc(no_inline)]
149    pub use crate::builder::*;
150    #[cfg(feature = "cache")]
151    #[doc(no_inline)]
152    pub use crate::cache::*;
153    #[cfg(feature = "client")]
154    #[doc(no_inline)]
155    pub use crate::client::*;
156    #[cfg(feature = "collector")]
157    #[doc(no_inline)]
158    pub use crate::collector::*;
159    #[doc(no_inline)]
160    pub use crate::constants::{close_codes::*, *};
161    #[cfg(feature = "framework")]
162    #[doc(no_inline)]
163    pub use crate::framework::*;
164    #[cfg(feature = "gateway")]
165    #[doc(no_inline)]
166    pub use crate::gateway::*;
167    #[cfg(feature = "http")]
168    #[doc(no_inline)]
169    pub use crate::http::*;
170    #[cfg(feature = "interactions_endpoint")]
171    #[doc(no_inline)]
172    pub use crate::interactions_endpoint::*;
173    #[cfg(feature = "utils")]
174    #[doc(no_inline)]
175    pub use crate::utils::{
176        token::{validate as validate_token, InvalidToken},
177        *,
178    };
179    // #[doc(no_inline)]
180    // pub use crate::*;
181    #[doc(no_inline)]
182    pub use crate::{
183        // Need to re-export this manually or it can't be accessed for some reason
184        async_trait,
185        model::prelude::*,
186        *,
187    };
188}
serenity/lib.rs

serenity/
lib.rs
