Move README example into src/lib.rs

This way it'll be run as a doctest and we'll know if it breaks (again).

Fixes #67.

README.md

@@ -1,45 +1,44 @@
-rust-imap
+<!-- this file uses https://github.com/livioribeiro/cargo-readme -->
-================
+<!-- do not manually edit README.md, instead edit README.tpl or src/lib.rs -->
-IMAP Client for Rust
+
+# imap
 
-[![Number of Crate Downloads](https://img.shields.io/crates/d/imap.svg)](https://crates.io/crates/imap)
 [![Crate Version](https://img.shields.io/crates/v/imap.svg)](https://crates.io/crates/imap)
+[![Documentation](https://docs.rs/arccstr/badge.svg)](https://docs.rs/arccstr/)
 [![Crate License](https://img.shields.io/crates/l/imap.svg)](https://crates.io/crates/imap)
 [![Build Status](https://travis-ci.org/mattnenterprise/rust-imap.svg)](https://travis-ci.org/mattnenterprise/rust-imap)
 [![Build Status](https://ci.appveyor.com/api/projects/status/github/mattnenterprise/rust-imap?svg=true)](https://ci.appveyor.com/api/projects/status/github/mattnenterprise/rust-imap)
 [![Coverage Status](https://coveralls.io/repos/github/mattnenterprise/rust-imap/badge.svg?branch=master)](https://coveralls.io/github/mattnenterprise/rust-imap?branch=master)
 
+IMAP client bindings for Rust.
 
-[Documentation](https://docs.rs/imap/)
+## Usage
+
+Here is a basic example of using the client.
+See the `examples/` directory for more examples.
 
-### Usage
-Here is a basic example of using the client. See the examples directory for more examples.
 ```rust
-extern crate imap;
 extern crate native_tls;
 
-use native_tls::TlsConnector;
-use imap::client::Client;
-
 // To connect to the gmail IMAP server with this you will need to allow unsecure apps access.
 // See: https://support.google.com/accounts/answer/6010255?hl=en
-// Look at the gmail_oauth2.rs example on how to connect to a gmail server securely.
+// Look at the `examples/gmail_oauth2.rs` for how to connect to gmail securely.
 fn main() {
     let domain = "imap.gmail.com";
     let port = 993;
     let socket_addr = (domain, port);
-    let ssl_connector = TlsConnector::builder().unwrap().build().unwrap();
+    let ssl_connector = native_tls::TlsConnector::builder().unwrap().build().unwrap();
     let mut imap_socket = Client::secure_connect(socket_addr, domain, ssl_connector).unwrap();
 
     imap_socket.login("username", "password").unwrap();
 
-    match imap_socket.capability() {
+    match imap_socket.capabilities() {
         Ok(capabilities) => {
             for capability in capabilities.iter() {
                 println!("{}", capability);
             }
         }
-        Err(e) => println!("Error parsing capability: {}", e),
+        Err(e) => println!("Error parsing capabilities: {}", e),
     };
 
     match imap_socket.select("INBOX") {
@@ -50,9 +49,9 @@ fn main() {
     };
 
     match imap_socket.fetch("2", "body[text]") {
-        Ok(lines) => {
+        Ok(messages) => {
-            for line in lines.iter() {
+            for message in messages.iter() {
-                print!("{}", line);
+                print!("{:?}", message);
             }
         }
         Err(e) => println!("Error Fetching email 2: {}", e),
@@ -62,14 +61,14 @@ fn main() {
 }
 ```
 
-### License
+## License
 
 Licensed under either of
  * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 at your option.
 
-### Contribution
+## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any

README.tpl

@@ -0,0 +1,26 @@
+<!-- this file uses https://github.com/livioribeiro/cargo-readme -->
+<!-- do not manually edit README.md, instead edit README.tpl or src/lib.rs -->
+
+# {{crate}}
+
+[![Crate Version](https://img.shields.io/crates/v/imap.svg)](https://crates.io/crates/imap)
+[![Documentation](https://docs.rs/arccstr/badge.svg)](https://docs.rs/arccstr/)
+[![Crate License](https://img.shields.io/crates/l/imap.svg)](https://crates.io/crates/imap)
+[![Build Status](https://travis-ci.org/mattnenterprise/rust-imap.svg)](https://travis-ci.org/mattnenterprise/rust-imap)
+[![Build Status](https://ci.appveyor.com/api/projects/status/github/mattnenterprise/rust-imap?svg=true)](https://ci.appveyor.com/api/projects/status/github/mattnenterprise/rust-imap)
+[![Coverage Status](https://coveralls.io/repos/github/mattnenterprise/rust-imap/badge.svg?branch=master)](https://coveralls.io/github/mattnenterprise/rust-imap?branch=master)
+
+{{readme}}
+
+## License
+
+Licensed under either of
+ * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+at your option.
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
+additional terms or conditions.

src/lib.rs

@@ -1,7 +1,55 @@
-#![crate_name = "imap"]
+//! IMAP client bindings for Rust.
-#![crate_type = "lib"]
+//!
-
+//! # Usage
-//! imap is a IMAP client for Rust.
+//!
+//! Here is a basic example of using the client.
+//! See the `examples/` directory for more examples.
+//!
+//! ```no_run
+//! # extern crate imap;
+//! extern crate native_tls;
+//! # use imap::client::Client;
+//!
+//! // To connect to the gmail IMAP server with this you will need to allow unsecure apps access.
+//! // See: https://support.google.com/accounts/answer/6010255?hl=en
+//! // Look at the `examples/gmail_oauth2.rs` for how to connect to gmail securely.
+//! fn main() {
+//!     let domain = "imap.gmail.com";
+//!     let port = 993;
+//!     let socket_addr = (domain, port);
+//!     let ssl_connector = native_tls::TlsConnector::builder().unwrap().build().unwrap();
+//!     let mut imap_socket = Client::secure_connect(socket_addr, domain, &ssl_connector).unwrap();
+//!
+//!     imap_socket.login("username", "password").unwrap();
+//!
+//!     match imap_socket.capabilities() {
+//!         Ok(capabilities) => {
+//!             for capability in capabilities.iter() {
+//!                 println!("{}", capability);
+//!             }
+//!         }
+//!         Err(e) => println!("Error parsing capabilities: {}", e),
+//!     };
+//!
+//!     match imap_socket.select("INBOX") {
+//!         Ok(mailbox) => {
+//!             println!("{}", mailbox);
+//!         }
+//!         Err(e) => println!("Error selecting INBOX: {}", e),
+//!     };
+//!
+//!     match imap_socket.fetch("2", "body[text]") {
+//!         Ok(messages) => {
+//!             for message in messages.iter() {
+//!                 print!("{:?}", message);
+//!             }
+//!         }
+//!         Err(e) => println!("Error Fetching email 2: {}", e),
+//!     };
+//!
+//!     imap_socket.logout().unwrap();
+//! }
+//! ```
 
 extern crate bufstream;
 extern crate imap_proto;