From 73c8d0ddc2c9252a086c06b11b63baee8d786e30 Mon Sep 17 00:00:00 2001 From: Jon Gjengset Date: Tue, 3 Apr 2018 13:01:56 -0400 Subject: [PATCH] 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 | 39 ++++++++++++++++++------------------- README.tpl | 26 +++++++++++++++++++++++++ src/lib.rs | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 97 insertions(+), 24 deletions(-) create mode 100644 README.tpl diff --git a/README.md b/README.md index 3595349..35da2fb 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,44 @@ -rust-imap -================ -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) => { - for line in lines.iter() { - print!("{}", line); + Ok(messages) => { + for message in messages.iter() { + 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 diff --git a/README.tpl b/README.tpl new file mode 100644 index 0000000..185cea4 --- /dev/null +++ b/README.tpl @@ -0,0 +1,26 @@ + + + +# {{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. diff --git a/src/lib.rs b/src/lib.rs index 85e622d..f2b8fbd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,7 +1,55 @@ -#![crate_name = "imap"] -#![crate_type = "lib"] - -//! imap is a IMAP client for Rust. +//! IMAP client bindings for Rust. +//! +//! # Usage +//! +//! 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;