feat: runtime independent examples

Author: dignifiedquire

Cargo.toml

@@ -27,12 +27,12 @@ nom = "5.0"
 base64 = "0.11"
 chrono = "0.4"
 async-native-tls = "0.3.0"
-async-std = { version = "1.4.0", default-features = false, features = ["std"] }
+async-std = { version = "1.4.0", default-features = false, features = ["std"]}
 pin-utils = "0.1.0-alpha.4"
 futures = "0.3.0"
 async-attributes = "1.1.0"
 rental = "0.5.5"
-stop-token = { version = "0.1.1", features = ["unstable"] }
+stop-token = "0.1.1"
 byte-pool = "0.2.1"
 lazy_static = "1.4.0"
 log = "0.4.8"
@@ -42,6 +42,8 @@ thiserror = "1.0.9"
 lettre_email = "0.9"
 pretty_assertions = "0.6.1"
 async-smtp = "0.2.0"
+async-std = { version = "1.4.0", features = ["default"] }
+tokio = "0.2.6"
 
 [[example]]
 name = "basic"
@@ -51,6 +53,14 @@ required-features = ["default"]
 name = "gmail_oauth2"
 required-features = ["default"]
 
+[[example]]
+name = "futures"
+required-features = ["default"]
+
+[[example]]
+name = "tokio"
+required-features = ["default"]
+
 [[test]]
 name = "imap_integration"
 required-features = ["default"]

examples/README.md

@@ -7,7 +7,9 @@ Examples:
 * basic - This is a very basic example of using the client.
 
 * idle - This is a basic example of how to perform an IMAP IDLE call
-  and interrupt it based on typing a line into stdin. 
+  and interrupt it based on typing a line into stdin.
 
 * gmail_oauth2 - This is an example using oauth2 for logging into
-  gmail via the OAUTH2 mechanism. 
+  gmail via the OAUTH2 mechanism.
+
+* futures - The basic example, but using the `futures` executor.

examples/futures.rs

@@ -0,0 +1,57 @@
+use async_imap::error::{Error, Result};
+use async_std::prelude::*;
+use std::env;
+
+fn main() -> Result<()> {
+    futures::executor::block_on(async {
+        let args: Vec<String> = env::args().collect();
+        if args.len() != 4 {
+            eprintln!("need three arguments: imap-server login password");
+            Err(Error::Bad("need three arguments".into()))
+        } else {
+            let res = fetch_inbox_top(&args[1], &args[2], &args[3]).await?;
+            println!("**result:\n{}", res.unwrap());
+            Ok(())
+        }
+    })
+}
+
+async fn fetch_inbox_top(imap_server: &str, login: &str, password: &str) -> Result<Option<String>> {
+    let tls = async_native_tls::TlsConnector::new();
+
+    // we pass in the imap_server twice to check that the server's TLS
+    // certificate is valid for the imap_server we're connecting to.
+    let client = async_imap::connect((imap_server, 993), imap_server, tls).await?;
+    println!("-- connected to {}:{}", imap_server, 993);
+
+    // the client we have here is unauthenticated.
+    // to do anything useful with the e-mails, we need to log in
+    let mut imap_session = client.login(login, password).await.map_err(|e| e.0)?;
+    println!("-- logged in a {}", login);
+
+    // we want to fetch the first email in the INBOX mailbox
+    imap_session.select("INBOX").await?;
+    println!("-- INBOX selected");
+
+    // fetch message number 1 in this mailbox, along with its RFC822 field.
+    // RFC 822 dictates the format of the body of e-mails
+    let messages_stream = imap_session.fetch("1", "RFC822").await?;
+    let messages: Vec<_> = messages_stream.collect::<Result<_>>().await?;
+    let message = if let Some(m) = messages.first() {
+        m
+    } else {
+        return Ok(None);
+    };
+
+    // extract the message's body
+    let body = message.body().expect("message did not have a body!");
+    let body = std::str::from_utf8(body)
+        .expect("message was not valid utf-8")
+        .to_string();
+    println!("-- 1 message received, logging out");
+
+    // be nice to the server and log out
+    imap_session.logout().await?;
+
+    Ok(Some(body))
+}

examples/tokio.rs

@@ -0,0 +1,60 @@
+use async_imap::error::{Error, Result};
+use async_std::prelude::*;
+use std::env;
+use tokio::runtime::Runtime;
+
+fn main() -> Result<()> {
+    let mut rt = Runtime::new().expect("unable to create runtime");
+
+    rt.block_on(async {
+        let args: Vec<String> = env::args().collect();
+        if args.len() != 4 {
+            eprintln!("need three arguments: imap-server login password");
+            Err(Error::Bad("need three arguments".into()))
+        } else {
+            let res = fetch_inbox_top(&args[1], &args[2], &args[3]).await?;
+            println!("**result:\n{}", res.unwrap());
+            Ok(())
+        }
+    })
+}
+
+async fn fetch_inbox_top(imap_server: &str, login: &str, password: &str) -> Result<Option<String>> {
+    let tls = async_native_tls::TlsConnector::new();
+
+    // we pass in the imap_server twice to check that the server's TLS
+    // certificate is valid for the imap_server we're connecting to.
+    let client = async_imap::connect((imap_server, 993), imap_server, tls).await?;
+    println!("-- connected to {}:{}", imap_server, 993);
+
+    // the client we have here is unauthenticated.
+    // to do anything useful with the e-mails, we need to log in
+    let mut imap_session = client.login(login, password).await.map_err(|e| e.0)?;
+    println!("-- logged in a {}", login);
+
+    // we want to fetch the first email in the INBOX mailbox
+    imap_session.select("INBOX").await?;
+    println!("-- INBOX selected");
+
+    // fetch message number 1 in this mailbox, along with its RFC822 field.
+    // RFC 822 dictates the format of the body of e-mails
+    let messages_stream = imap_session.fetch("1", "RFC822").await?;
+    let messages: Vec<_> = messages_stream.collect::<Result<_>>().await?;
+    let message = if let Some(m) = messages.first() {
+        m
+    } else {
+        return Ok(None);
+    };
+
+    // extract the message's body
+    let body = message.body().expect("message did not have a body!");
+    let body = std::str::from_utf8(body)
+        .expect("message was not valid utf-8")
+        .to_string();
+    println!("-- 1 message received, logging out");
+
+    // be nice to the server and log out
+    imap_session.logout().await?;
+
+    Ok(Some(body))
+}