Restructure modules

Modules are now separated into a fashion where the library can be used
for most use cases, without needing to compile the rest.

The core of serenity, with no features enabled, contains only the
struct (model) definitions, constants, and prelude. Models do not have
most functions compiled in, as that is separated into the `model`
feature.

The `client` module has been split into 3 modules: `client`, `gateway`,
and `http`.

`http` contains functions to interact with the REST API. `gateway`
contains the Shard to interact with the gateway, requiring `http` for
retrieving the gateway URL. `client` requires both of the other features
and acts as an abstracted interface over both the gateway and REST APIs,
handling the event loop.

The `builder` module has been separated from `utils`, and can now be
optionally compiled in. It and the `http` feature are required by the
`model` feature due to a large number of methods requiring access to
them.

`utils` now contains a number of utilities, such as the Colour struct, the
`MessageBuilder`, and mention parsing functions.

Each of the original `ext` modules are still featured, with `cache` not
requiring any feature to be enabled, `framework` requiring the `client`,
`model`, and `utils`, and `voice` requiring `gateway`.

In total the features and their requirements are:

- `builder`: none
- `cache`: none
- `client`: `gateway`, `http`
- `framework`: `client`, `model`, `utils`
- `gateway`: `http`
- `http`: none
- `model`: `builder`, `http`
- `utils`: none
- `voice`: `gateway`

The default features are `builder`, `cache`, `client`, `framework`,
`gateway`, `model`, `http`, and `utils`.

To help with forwards compatibility, modules have been re-exported from
their original locations.

1 files changed, 83 insertions, 17 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 793ad12..50c5d37 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -71,62 +71,128 @@
 //! #[macro_use] extern crate serenity;
 //! ```
 //!
-//! [`Cache`]: ext/cache/struct.Cache.html
+//! [`Cache`]: cache/struct.Cache.html
 //! [`Client::login`]: client/struct.Client.html#method.login
 //! [`Client::on_message`]: client/struct.Client.html#method.on_message
 //! [`Context`]: client/struct.Context.html
 //! [`Event`]: model/event/enum.Event.html
 //! [`Event::MessageCreate`]: model/event/enum.Event.html#variant.MessageCreate
-//! [`Shard`]: client/gateway/struct.Shard.html
+//! [`Shard`]: gateway/struct.Shard.html
 //! [`examples`]: https://github.com/zeyla/serenity/blob/master/examples
-//! [cache docs]: ext/cache/index.html
+//! [cache docs]: cache/index.html
 //! [client's module-level documentation]: client/index.html
 //! [docs]: https://discordapp.com/developers/docs/intro
 //! [examples]: https://github.com/zeyla/serenity/tree/master/examples
-//! [gateway docs]: client/gateway/index.html
+//! [gateway docs]: gateway/index.html
 #![allow(doc_markdown, inline_always, unknown_lints)]
 #![warn(enum_glob_use, if_not_else)]
 
 #[macro_use]
 extern crate bitflags;
 #[macro_use]
-extern crate lazy_static;
-#[macro_use]
 extern crate log;
 #[macro_use]
 extern crate serde_derive;
 #[macro_use]
 extern crate serde_json;
 
+#[cfg(feature="lazy_static")]
+#[macro_use]
+extern crate lazy_static;
+
 extern crate base64;
 extern crate flate2;
-extern crate hyper;
-extern crate multipart;
 extern crate serde;
 extern crate time;
-extern crate typemap;
-extern crate websocket;
 
 #[cfg(feature="voice")]
 extern crate byteorder;
+#[cfg(feature="hyper")]
+extern crate hyper;
+#[cfg(feature="http")]
+extern crate multipart;
 #[cfg(feature="voice")]
 extern crate opus;
 #[cfg(feature="voice")]
 extern crate sodiumoxide;
+#[cfg(feature="client")]
+extern crate typemap;
+#[cfg(feature="gateway")]
+extern crate websocket;
 
 #[macro_use]
-pub mod utils;
+mod internal;
 
-pub mod client;
-pub mod ext;
+pub mod constants;
 pub mod model;
 pub mod prelude;
 
-#[macro_use]
-mod internal;
+#[cfg(feature="builder")]
+pub mod builder;
+#[cfg(feature="cache")]
+pub mod cache;
+#[cfg(feature="client")]
+pub mod client;
+#[cfg(any(feature="cache", feature="framework", feature="voice"))]
+pub mod ext;
+#[cfg(feature="framework")]
+pub mod framework;
+#[cfg(feature="gateway")]
+pub mod gateway;
+#[cfg(feature="http")]
+pub mod http;
+#[cfg(feature="utils")]
+pub mod utils;
+#[cfg(feature="voice")]
+pub mod voice;
 
-mod constants;
 mod error;
 
-pub use client::Client;
 pub use error::{Error, Result};
+
+#[cfg(feature="client")]
+pub use client::Client;
+
+#[cfg(feature="cache")]
+use cache::Cache;
+#[cfg(feature="cache")]
+use std::sync::RwLock;
+
+#[cfg(feature="cache")]
+lazy_static! {
+    /// A mutable and lazily-initialized static binding. It can be accessed
+    /// across any function and in any context.
+    ///
+    /// This [`Cache`] instance is updated for every event received, so you do
+    /// not need to maintain your own cache.
+    ///
+    /// See the [cache module documentation] for more details.
+    ///
+    /// The Cache itself is wrapped within an `RwLock`, which allows for
+    /// multiple readers or at most one writer at a time across threads. This
+    /// means that you may have multiple commands reading from the Cache
+    /// concurrently.
+    ///
+    /// # Examples
+    ///
+    /// Retrieve the [current user][`CurrentUser`]'s Id, by opening a Read
+    /// guard:
+    ///
+    /// ```rust,ignore
+    /// use serenity::CACHE;
+    ///
+    /// println!("{}", CACHE.read().unwrap().user.id);
+    /// ```
+    ///
+    /// By `unwrap()`ing, the thread managing an event dispatch will be blocked
+    /// until the guard can be opened.
+    ///
+    /// If you do not want to block the current thread, you may instead use
+    /// `RwLock::try_read`. Refer to `RwLock`'s documentation in the stdlib for
+    /// more information.
+    ///
+    /// [`CurrentUser`]: model/struct.CurrentUser.html
+    /// [`Cache`]: cache/struct.Cache.html
+    /// [cache module documentation]: cache/index.html
+    pub static ref CACHE: RwLock<Cache> = RwLock::new(Cache::default());
+}