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_auto_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::unused_self,
70    // Allowed as they are too pedantic
71    clippy::cast_possible_truncation,
72    clippy::unreadable_literal,
73    clippy::cast_possible_wrap,
74    clippy::wildcard_imports,
75    clippy::cast_sign_loss,
76    clippy::too_many_lines,
77    clippy::doc_markdown,
78    clippy::cast_lossless,
79    clippy::redundant_closure_for_method_calls,
80    // Covered by other lints
81    clippy::missing_panics_doc, // clippy::unwrap_used
82)]
83#![cfg_attr(test, allow(clippy::unwrap_used))]
84#![type_length_limit = "3294819"] // needed so ShardRunner::run compiles with instrument.
85
86#[macro_use]
87extern crate serde;
88
89#[macro_use]
90mod internal;
91
92pub mod constants;
93pub mod json;
94pub mod model;
95pub mod prelude;
96
97#[cfg(feature = "builder")]
98pub mod builder;
99#[cfg(feature = "cache")]
100pub mod cache;
101#[cfg(feature = "client")]
102pub mod client;
103#[cfg(feature = "collector")]
104pub mod collector;
105#[cfg(feature = "framework")]
106pub mod framework;
107#[cfg(feature = "gateway")]
108pub mod gateway;
109#[cfg(feature = "http")]
110pub mod http;
111#[cfg(feature = "interactions_endpoint")]
112pub mod interactions_endpoint;
113#[cfg(feature = "utils")]
114pub mod utils;
115
116mod error;
117
118// For the procedural macros in `command_attr`.
119pub use async_trait::async_trait;
120pub use futures;
121pub use futures::future::FutureExt;
122#[cfg(feature = "standard_framework")]
123#[doc(hidden)]
124pub use static_assertions;
125
126#[cfg(all(feature = "client", feature = "gateway"))]
127pub use crate::client::Client;
128pub use crate::error::{Error, Result};
129
130#[cfg(feature = "absolute_ratelimits")]
131compile_error!(
132    "The absolute_ratelimits feature has been removed.\n\
133    Configure absolute ratelimits via Ratelimiter::set_absolute_ratelimits.\n\
134    You can set the Ratelimiter of Http via HttpBuilder::ratelimiter."
135);
136
137/// Special module that re-exports most public items from this crate.
138///
139/// Useful, because you don't have to remember the full paths of serenity items.
140///
141/// Not exported:
142/// - [`crate::json`]: it's a general-purpose JSON wrapper, not intrinsic to serenity
143/// - [`crate::framework::standard`]: has many standard_framework-specific items that may collide
144///   with items from the rest of serenity
145pub mod all {
146    #[cfg(feature = "builder")]
147    #[doc(no_inline)]
148    pub use crate::builder::*;
149    #[cfg(feature = "cache")]
150    #[doc(no_inline)]
151    pub use crate::cache::*;
152    #[cfg(feature = "client")]
153    #[doc(no_inline)]
154    pub use crate::client::*;
155    #[cfg(feature = "collector")]
156    #[doc(no_inline)]
157    pub use crate::collector::*;
158    #[doc(no_inline)]
159    pub use crate::constants::{close_codes::*, *};
160    #[cfg(feature = "framework")]
161    #[doc(no_inline)]
162    pub use crate::framework::*;
163    #[cfg(feature = "gateway")]
164    #[doc(no_inline)]
165    pub use crate::gateway::*;
166    #[cfg(feature = "http")]
167    #[doc(no_inline)]
168    pub use crate::http::*;
169    #[cfg(feature = "interactions_endpoint")]
170    #[doc(no_inline)]
171    pub use crate::interactions_endpoint::*;
172    #[cfg(feature = "utils")]
173    #[doc(no_inline)]
174    pub use crate::utils::{
175        token::{validate as validate_token, InvalidToken},
176        *,
177    };
178    // #[doc(no_inline)]
179    // pub use crate::*;
180    #[doc(no_inline)]
181    pub use crate::{
182        // Need to re-export this manually or it can't be accessed for some reason
183        async_trait,
184        model::prelude::*,
185        *,
186    };
187}
serenity/lib.rs

serenity/
lib.rs
