From 469d338d5da0cb8c3996614b42677428abbb9aaa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Thu, 17 Dec 2020 00:20:48 +0800
Subject: [PATCH 01/12] refactor: combine all append_* + introduce
 AppendOptions

---
 src/client.rs             | 54 ++++++++++++++++++---------------------
 tests/imap_integration.rs | 25 ++++++++++++++----
 2 files changed, 45 insertions(+), 34 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index 26a1432..167ea70 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -84,6 +84,15 @@ pub struct Connection<T: Read + Write> {
     pub greeting_read: bool,
 }
 
+/// A set of options for the append command
+#[derive(Default)]
+pub struct AppendOptions<'a> {
+    /// Optional list of flags
+    pub flags: Option<&'a [Flag<'a>]>,
+    /// Optional internal date
+    pub date: Option<DateTime<FixedOffset>>,
+}
+
 // `Deref` instances are so we can make use of the same underlying primitives in `Client` and
 // `Session`
 impl<T: Read + Write> Deref for Client<T> {
@@ -1078,10 +1087,9 @@ impl<T: Read + Write> Session<T> {
     /// Specifically, the server will generally notify the client immediately via an untagged
     /// `EXISTS` response.  If the server does not do so, the client MAY issue a `NOOP` command (or
     /// failing that, a `CHECK` command) after one or more `APPEND` commands.
-    pub fn append<S: AsRef<str>, B: AsRef<[u8]>>(&mut self, mailbox: S, content: B) -> Result<()> {
-        self.append_with_flags(mailbox, content, &[])
-    }
-
+    ///
+    /// -- TODO merge docs possibly move to AppendOptions
+    ///
     /// The [`APPEND` command](https://tools.ietf.org/html/rfc3501#section-6.3.11) can take
     /// an optional FLAGS parameter to set the flags on the new message.
     ///
@@ -1092,48 +1100,36 @@ impl<T: Read + Write> Session<T> {
     ///
     /// The [`\Recent` flag](https://tools.ietf.org/html/rfc3501#section-2.3.2) is not
     /// allowed as an argument to `APPEND` and will be filtered out if present in `flags`.
-    pub fn append_with_flags<S: AsRef<str>, B: AsRef<[u8]>>(
-        &mut self,
-        mailbox: S,
-        content: B,
-        flags: &[Flag<'_>],
-    ) -> Result<()> {
-        self.append_with_flags_and_date(mailbox, content, flags, None)
-    }
-
-    /// The [`APPEND` command](https://tools.ietf.org/html/rfc3501#section-6.3.11) can take
-    /// an optional FLAGS parameter to set the flags on the new message.
     ///
-    /// > If a flag parenthesized list is specified, the flags SHOULD be set
-    /// > in the resulting message; otherwise, the flag list of the
-    /// > resulting message is set to empty by default.  In either case, the
-    /// > Recent flag is also set.
-    ///
-    /// The [`\Recent` flag](https://tools.ietf.org/html/rfc3501#section-2.3.2) is not
-    /// allowed as an argument to `APPEND` and will be filtered out if present in `flags`.
+    /// -- TODO merge docs possibly move to AppendOptions
     ///
     /// Pass a date in order to set the date that the message was originally sent.
     ///
     /// > If a date-time is specified, the internal date SHOULD be set in
     /// > the resulting message; otherwise, the internal date of the
     /// > resulting message is set to the current date and time by default.
-    pub fn append_with_flags_and_date<S: AsRef<str>, B: AsRef<[u8]>>(
+    pub fn append<'a, S: AsRef<str>, B: AsRef<[u8]>>(
         &mut self,
         mailbox: S,
         content: B,
-        flags: &[Flag<'_>],
-        date: impl Into<Option<DateTime<FixedOffset>>>,
+        options: impl Into<Option<AppendOptions<'a>>>,
     ) -> Result<()> {
         let content = content.as_ref();
-        let flagstr = flags
+        let options_ = options.into().unwrap_or(AppendOptions::default());
+
+        let flagstr = options_
+            .flags
+            .unwrap_or(&[])
             .iter()
             .filter(|f| **f != Flag::Recent)
             .map(|f| f.to_string())
             .collect::<Vec<String>>()
             .join(" ");
-        let datestr = match date.into() {
-            Some(date) => format!(" \"{}\"", date.format("%d-%h-%Y %T %z")),
-            None => "".to_string(),
+
+        let datestr = if let Some(date) = options_.date {
+            format!(" \"{}\"", date.format("%d-%h-%Y %T %z"))
+        } else {
+            "".to_string()
         };
 
         self.run_command(&format!(
diff --git a/tests/imap_integration.rs b/tests/imap_integration.rs
index b37f3f3..18dd3e8 100644
--- a/tests/imap_integration.rs
+++ b/tests/imap_integration.rs
@@ -253,7 +253,8 @@ fn append() {
     let mbox = "INBOX";
     c.select(mbox).unwrap();
     //append
-    c.append(mbox, e.message_to_string().unwrap()).unwrap();
+    c.append(mbox, e.message_to_string().unwrap(), None)
+        .unwrap();
 
     // now we should see the e-mail!
     let inbox = c.uid_search("ALL").unwrap();
@@ -301,8 +302,15 @@ fn append_with_flags() {
     c.select(mbox).unwrap();
     //append
     let flags: &[Flag] = &[Flag::Seen, Flag::Flagged];
-    c.append_with_flags(mbox, e.message_to_string().unwrap(), flags)
-        .unwrap();
+    c.append(
+        mbox,
+        e.message_to_string().unwrap(),
+        imap::AppendOptions {
+            flags: Some(flags),
+            date: None,
+        },
+    )
+    .unwrap();
 
     // now we should see the e-mail!
     let inbox = c.uid_search("ALL").unwrap();
@@ -358,8 +366,15 @@ fn append_with_flags_and_date() {
     let date = FixedOffset::east(8 * 3600)
         .ymd(2020, 12, 13)
         .and_hms(13, 36, 36);
-    c.append_with_flags_and_date(mbox, e.message_to_string().unwrap(), flags, Some(date))
-        .unwrap();
+    c.append(
+        mbox,
+        e.message_to_string().unwrap(),
+        imap::AppendOptions {
+            flags: Some(flags),
+            date: Some(date),
+        },
+    )
+    .unwrap();
 
     // now we should see the e-mail!
     let inbox = c.uid_search("ALL").unwrap();

From 24445c5c652b6098d8c859411da74264105506dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Thu, 17 Dec 2020 00:41:26 +0800
Subject: [PATCH 02/12] feat: add AppendCmd builder

---
 src/client.rs | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/client.rs b/src/client.rs
index 167ea70..1e33ab5 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -93,6 +93,41 @@ pub struct AppendOptions<'a> {
     pub date: Option<DateTime<FixedOffset>>,
 }
 
+/// A builder for the append command
+#[derive(Default)]
+pub struct AppendCmd<'a> {
+    flags: Vec<&'a Flag<'a>>,
+    date: Option<DateTime<FixedOffset>>,
+}
+
+impl<'a> AppendCmd<'a> {
+    /// Create a new AppendCmd builder
+    pub fn create() -> Self {
+        Self::default()
+    }
+
+    /// Append a flag
+    pub fn flag(&mut self, flag: &'a Flag<'a>) -> &mut Self {
+        self.flags.push(flag);
+        self
+    }
+
+    /// Set the internal date
+    pub fn internal_date(&mut self, date: DateTime<FixedOffset>) -> &mut Self {
+        self.date = Some(date);
+        self
+    }
+}
+
+impl<'a> Into<AppendOptions<'a>> for AppendCmd<'a> {
+    fn into(self) -> AppendOptions<'a> {
+        AppendOptions {
+            flags: Some(&self.flags[..]),
+            date: self.date,
+        }
+    }
+}
+
 // `Deref` instances are so we can make use of the same underlying primitives in `Client` and
 // `Session`
 impl<T: Read + Write> Deref for Client<T> {

From cdf320fb0c87009bd3856220d263b62180637b8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Thu, 17 Dec 2020 11:02:48 +0800
Subject: [PATCH 03/12] refactor: use AppendCmd instead of AppendOptions

---
 src/client.rs             | 102 ++++++++++++++++----------------------
 tests/imap_integration.rs |  32 +++++-------
 2 files changed, 57 insertions(+), 77 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index 1e33ab5..6bbe119 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -84,28 +84,16 @@ pub struct Connection<T: Read + Write> {
     pub greeting_read: bool,
 }
 
-/// A set of options for the append command
-#[derive(Default)]
-pub struct AppendOptions<'a> {
-    /// Optional list of flags
-    pub flags: Option<&'a [Flag<'a>]>,
-    /// Optional internal date
-    pub date: Option<DateTime<FixedOffset>>,
-}
-
 /// A builder for the append command
-#[derive(Default)]
-pub struct AppendCmd<'a> {
+pub struct AppendCmd<'a, T: Read + Write> {
+    session: &'a Session<T>,
+    content: &'a [u8],
+    mailbox: &'a str,
     flags: Vec<&'a Flag<'a>>,
     date: Option<DateTime<FixedOffset>>,
 }
 
-impl<'a> AppendCmd<'a> {
-    /// Create a new AppendCmd builder
-    pub fn create() -> Self {
-        Self::default()
-    }
-
+impl<'a, T: Read + Write> AppendCmd<'a, T> {
     /// Append a flag
     pub fn flag(&mut self, flag: &'a Flag<'a>) -> &mut Self {
         self.flags.push(flag);
@@ -117,14 +105,40 @@ impl<'a> AppendCmd<'a> {
         self.date = Some(date);
         self
     }
-}
 
-impl<'a> Into<AppendOptions<'a>> for AppendCmd<'a> {
-    fn into(self) -> AppendOptions<'a> {
-        AppendOptions {
-            flags: Some(&self.flags[..]),
-            date: self.date,
+    /// Run command when set up
+    #[must_use]
+    pub fn run(&self) -> Result<()> {
+        let flagstr = self
+            .flags
+            .into_iter()
+            .filter(|f| **f != Flag::Recent)
+            .map(|f| f.to_string())
+            .collect::<Vec<String>>()
+            .join(" ");
+
+        let datestr = if let Some(date) = self.date {
+            format!(" \"{}\"", date.format("%d-%h-%Y %T %z"))
+        } else {
+            "".to_string()
+        };
+
+        self.session.run_command(&format!(
+            "APPEND \"{}\" ({}){} {{{}}}",
+            self.mailbox,
+            flagstr,
+            datestr,
+            self.content.len()
+        ))?;
+        let mut v = Vec::new();
+        self.session.readline(&mut v)?;
+        if !v.starts_with(b"+") {
+            return Err(Error::Append);
         }
+        self.session.stream.write_all(self.content)?;
+        self.session.stream.write_all(b"\r\n")?;
+        self.session.stream.flush()?;
+        self.session.read_response().map(|_| ())
     }
 }
 
@@ -1147,42 +1161,14 @@ impl<T: Read + Write> Session<T> {
         &mut self,
         mailbox: S,
         content: B,
-        options: impl Into<Option<AppendOptions<'a>>>,
-    ) -> Result<()> {
-        let content = content.as_ref();
-        let options_ = options.into().unwrap_or(AppendOptions::default());
-
-        let flagstr = options_
-            .flags
-            .unwrap_or(&[])
-            .iter()
-            .filter(|f| **f != Flag::Recent)
-            .map(|f| f.to_string())
-            .collect::<Vec<String>>()
-            .join(" ");
-
-        let datestr = if let Some(date) = options_.date {
-            format!(" \"{}\"", date.format("%d-%h-%Y %T %z"))
-        } else {
-            "".to_string()
-        };
-
-        self.run_command(&format!(
-            "APPEND \"{}\" ({}){} {{{}}}",
-            mailbox.as_ref(),
-            flagstr,
-            datestr,
-            content.len()
-        ))?;
-        let mut v = Vec::new();
-        self.readline(&mut v)?;
-        if !v.starts_with(b"+") {
-            return Err(Error::Append);
+    ) -> AppendCmd<'a, T> {
+        AppendCmd {
+            session: &self,
+            content: content.as_ref(),
+            mailbox: mailbox.as_ref(),
+            flags: Vec::new(),
+            date: None,
         }
-        self.stream.write_all(content)?;
-        self.stream.write_all(b"\r\n")?;
-        self.stream.flush()?;
-        self.read_response().map(|_| ())
     }
 
     /// The [`SEARCH` command](https://tools.ietf.org/html/rfc3501#section-6.4.4) searches the
diff --git a/tests/imap_integration.rs b/tests/imap_integration.rs
index 18dd3e8..abecb0f 100644
--- a/tests/imap_integration.rs
+++ b/tests/imap_integration.rs
@@ -253,7 +253,8 @@ fn append() {
     let mbox = "INBOX";
     c.select(mbox).unwrap();
     //append
-    c.append(mbox, e.message_to_string().unwrap(), None)
+    c.append(mbox, e.message_to_string().unwrap())
+        .run()
         .unwrap();
 
     // now we should see the e-mail!
@@ -302,15 +303,11 @@ fn append_with_flags() {
     c.select(mbox).unwrap();
     //append
     let flags: &[Flag] = &[Flag::Seen, Flag::Flagged];
-    c.append(
-        mbox,
-        e.message_to_string().unwrap(),
-        imap::AppendOptions {
-            flags: Some(flags),
-            date: None,
-        },
-    )
-    .unwrap();
+    c.append(mbox, e.message_to_string().unwrap())
+        .flag(Flag::Seen)
+        .flag(Flag::Flagged)
+        .run()
+        .unwrap();
 
     // now we should see the e-mail!
     let inbox = c.uid_search("ALL").unwrap();
@@ -366,15 +363,12 @@ fn append_with_flags_and_date() {
     let date = FixedOffset::east(8 * 3600)
         .ymd(2020, 12, 13)
         .and_hms(13, 36, 36);
-    c.append(
-        mbox,
-        e.message_to_string().unwrap(),
-        imap::AppendOptions {
-            flags: Some(flags),
-            date: Some(date),
-        },
-    )
-    .unwrap();
+    c.append(mbox, e.message_to_string().unwrap())
+        .flag(Flag::Seen)
+        .flag(Flag::Flagged)
+        .internal_date(date)
+        .run()
+        .unwrap();
 
     // now we should see the e-mail!
     let inbox = c.uid_search("ALL").unwrap();

From e6341ccfc0af9e617f15b1f59545ad3312bbe599 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Thu, 17 Dec 2020 11:37:01 +0800
Subject: [PATCH 04/12] fix: pass session as &mut

---
 src/client.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index 6bbe119..c5cfc82 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -86,7 +86,7 @@ pub struct Connection<T: Read + Write> {
 
 /// A builder for the append command
 pub struct AppendCmd<'a, T: Read + Write> {
-    session: &'a Session<T>,
+    session: &'a mut Session<T>,
     content: &'a [u8],
     mailbox: &'a str,
     flags: Vec<&'a Flag<'a>>,
@@ -1163,7 +1163,7 @@ impl<T: Read + Write> Session<T> {
         content: B,
     ) -> AppendCmd<'a, T> {
         AppendCmd {
-            session: &self,
+            session: self,
             content: content.as_ref(),
             mailbox: mailbox.as_ref(),
             flags: Vec::new(),

From b7bc84297979b7ad3f48e33300a149b406e8fb2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Sun, 20 Dec 2020 13:03:54 +0800
Subject: [PATCH 05/12] fix: correct lifetimes and types for append

---
 src/client.rs             | 19 ++++++++-----------
 tests/imap_integration.rs |  7 +++----
 2 files changed, 11 insertions(+), 15 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index c5cfc82..4fc4c25 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -89,13 +89,13 @@ pub struct AppendCmd<'a, T: Read + Write> {
     session: &'a mut Session<T>,
     content: &'a [u8],
     mailbox: &'a str,
-    flags: Vec<&'a Flag<'a>>,
+    flags: Vec<Flag<'a>>,
     date: Option<DateTime<FixedOffset>>,
 }
 
 impl<'a, T: Read + Write> AppendCmd<'a, T> {
     /// Append a flag
-    pub fn flag(&mut self, flag: &'a Flag<'a>) -> &mut Self {
+    pub fn flag(&mut self, flag: Flag<'a>) -> &mut Self {
         self.flags.push(flag);
         self
     }
@@ -108,11 +108,12 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
 
     /// Run command when set up
     #[must_use]
-    pub fn run(&self) -> Result<()> {
+    pub fn run(&mut self) -> Result<()> {
         let flagstr = self
             .flags
+            .clone()
             .into_iter()
-            .filter(|f| **f != Flag::Recent)
+            .filter(|f| *f != Flag::Recent)
             .map(|f| f.to_string())
             .collect::<Vec<String>>()
             .join(" ");
@@ -1157,15 +1158,11 @@ impl<T: Read + Write> Session<T> {
     /// > If a date-time is specified, the internal date SHOULD be set in
     /// > the resulting message; otherwise, the internal date of the
     /// > resulting message is set to the current date and time by default.
-    pub fn append<'a, S: AsRef<str>, B: AsRef<[u8]>>(
-        &mut self,
-        mailbox: S,
-        content: B,
-    ) -> AppendCmd<'a, T> {
+    pub fn append<'a>(&'a mut self, mailbox: &'a str, content: &'a [u8]) -> AppendCmd<'a, T> {
         AppendCmd {
             session: self,
-            content: content.as_ref(),
-            mailbox: mailbox.as_ref(),
+            content,
+            mailbox,
             flags: Vec::new(),
             date: None,
         }
diff --git a/tests/imap_integration.rs b/tests/imap_integration.rs
index abecb0f..b32a0c0 100644
--- a/tests/imap_integration.rs
+++ b/tests/imap_integration.rs
@@ -253,7 +253,7 @@ fn append() {
     let mbox = "INBOX";
     c.select(mbox).unwrap();
     //append
-    c.append(mbox, e.message_to_string().unwrap())
+    c.append(mbox, e.message_to_string().unwrap().as_bytes())
         .run()
         .unwrap();
 
@@ -303,7 +303,7 @@ fn append_with_flags() {
     c.select(mbox).unwrap();
     //append
     let flags: &[Flag] = &[Flag::Seen, Flag::Flagged];
-    c.append(mbox, e.message_to_string().unwrap())
+    c.append(mbox, e.message_to_string().unwrap().as_bytes())
         .flag(Flag::Seen)
         .flag(Flag::Flagged)
         .run()
@@ -359,11 +359,10 @@ fn append_with_flags_and_date() {
     let mbox = "INBOX";
     c.select(mbox).unwrap();
     // append
-    let flags: &[Flag] = &[Flag::Seen, Flag::Flagged];
     let date = FixedOffset::east(8 * 3600)
         .ymd(2020, 12, 13)
         .and_hms(13, 36, 36);
-    c.append(mbox, e.message_to_string().unwrap())
+    c.append(mbox, e.message_to_string().unwrap().as_bytes())
         .flag(Flag::Seen)
         .flag(Flag::Flagged)
         .internal_date(date)

From 5053cfbb3ec2037e0cc59684e24d31499759f1c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Sun, 20 Dec 2020 13:04:31 +0800
Subject: [PATCH 06/12] feat: add 'flags' method to add multiple flags at once

---
 src/client.rs             | 6 ++++++
 tests/imap_integration.rs | 3 +--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index 4fc4c25..74127ef 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -100,6 +100,12 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
         self
     }
 
+    /// Append an array of flags
+    pub fn flags(&mut self, flags: &'a [Flag<'a>]) -> &mut Self {
+        self.flags.append(&mut flags.to_vec());
+        self
+    }
+
     /// Set the internal date
     pub fn internal_date(&mut self, date: DateTime<FixedOffset>) -> &mut Self {
         self.date = Some(date);
diff --git a/tests/imap_integration.rs b/tests/imap_integration.rs
index b32a0c0..536efd2 100644
--- a/tests/imap_integration.rs
+++ b/tests/imap_integration.rs
@@ -304,8 +304,7 @@ fn append_with_flags() {
     //append
     let flags: &[Flag] = &[Flag::Seen, Flag::Flagged];
     c.append(mbox, e.message_to_string().unwrap().as_bytes())
-        .flag(Flag::Seen)
-        .flag(Flag::Flagged)
+        .flags(flags)
         .run()
         .unwrap();
 

From 74ef623fc589bc20ce1773f1ab9ef4729fe6729d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Sun, 20 Dec 2020 13:09:57 +0800
Subject: [PATCH 07/12] docs: move flag + date documentation to AppendCmd

---
 src/client.rs | 41 +++++++++++++++++------------------------
 1 file changed, 17 insertions(+), 24 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index 74127ef..aa5623f 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -94,7 +94,16 @@ pub struct AppendCmd<'a, T: Read + Write> {
 }
 
 impl<'a, T: Read + Write> AppendCmd<'a, T> {
-    /// Append a flag
+    /// The [`APPEND` command](https://tools.ietf.org/html/rfc3501#section-6.3.11) can take
+    /// an optional FLAGS parameter to set the flags on the new message.
+    ///
+    /// > If a flag parenthesized list is specified, the flags SHOULD be set
+    /// > in the resulting message; otherwise, the flag list of the
+    /// > resulting message is set to empty by default.  In either case, the
+    /// > Recent flag is also set.
+    ///
+    /// The [`\Recent` flag](https://tools.ietf.org/html/rfc3501#section-2.3.2) is not
+    /// allowed as an argument to `APPEND` and will be filtered out if present in `flags`.
     pub fn flag(&mut self, flag: Flag<'a>) -> &mut Self {
         self.flags.push(flag);
         self
@@ -106,14 +115,18 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
         self
     }
 
-    /// Set the internal date
+    /// Pass a date in order to set the date that the message was originally sent.
+    ///
+    /// > If a date-time is specified, the internal date SHOULD be set in
+    /// > the resulting message; otherwise, the internal date of the
+    /// > resulting message is set to the current date and time by default.
     pub fn internal_date(&mut self, date: DateTime<FixedOffset>) -> &mut Self {
         self.date = Some(date);
         self
     }
 
-    /// Run command when set up
-    #[must_use]
+    /// Run command
+    #[must_use = "always run a command once options are configured"]
     pub fn run(&mut self) -> Result<()> {
         let flagstr = self
             .flags
@@ -1144,26 +1157,6 @@ impl<T: Read + Write> Session<T> {
     /// `EXISTS` response.  If the server does not do so, the client MAY issue a `NOOP` command (or
     /// failing that, a `CHECK` command) after one or more `APPEND` commands.
     ///
-    /// -- TODO merge docs possibly move to AppendOptions
-    ///
-    /// The [`APPEND` command](https://tools.ietf.org/html/rfc3501#section-6.3.11) can take
-    /// an optional FLAGS parameter to set the flags on the new message.
-    ///
-    /// > If a flag parenthesized list is specified, the flags SHOULD be set
-    /// > in the resulting message; otherwise, the flag list of the
-    /// > resulting message is set to empty by default.  In either case, the
-    /// > Recent flag is also set.
-    ///
-    /// The [`\Recent` flag](https://tools.ietf.org/html/rfc3501#section-2.3.2) is not
-    /// allowed as an argument to `APPEND` and will be filtered out if present in `flags`.
-    ///
-    /// -- TODO merge docs possibly move to AppendOptions
-    ///
-    /// Pass a date in order to set the date that the message was originally sent.
-    ///
-    /// > If a date-time is specified, the internal date SHOULD be set in
-    /// > the resulting message; otherwise, the internal date of the
-    /// > resulting message is set to the current date and time by default.
     pub fn append<'a>(&'a mut self, mailbox: &'a str, content: &'a [u8]) -> AppendCmd<'a, T> {
         AppendCmd {
             session: self,

From 19af971c9a435bcb4f9d389b0deb33ac1d62249c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?=
 <mblarsen@users.noreply.github.com>
Date: Mon, 21 Dec 2020 10:37:18 +0800
Subject: [PATCH 08/12] refactor: use extend instead of append

Co-authored-by: Jon Gjengset <jon@thesquareplanet.com>
---
 src/client.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index aa5623f..e7833e4 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -110,8 +110,8 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
     }
 
     /// Append an array of flags
-    pub fn flags(&mut self, flags: &'a [Flag<'a>]) -> &mut Self {
-        self.flags.append(&mut flags.to_vec());
+    pub fn flags(&mut self, flags: impl IntoIterator<Item = Flag<'a>>) -> &mut Self {
+        self.flags.extend(flags);
         self
     }
 

From 029da6fd5226c1aa607881a66907a8cfc4878325 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Mon, 21 Dec 2020 11:19:42 +0800
Subject: [PATCH 09/12] refactor: move must_use to AppendCmd

---
 src/client.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/client.rs b/src/client.rs
index e7833e4..5d4ddd4 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -85,6 +85,7 @@ pub struct Connection<T: Read + Write> {
 }
 
 /// A builder for the append command
+#[must_use]
 pub struct AppendCmd<'a, T: Read + Write> {
     session: &'a mut Session<T>,
     content: &'a [u8],
@@ -126,7 +127,6 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
     }
 
     /// Run command
-    #[must_use = "always run a command once options are configured"]
     pub fn run(&mut self) -> Result<()> {
         let flagstr = self
             .flags

From 8cd8a210085e6d86ec3a3859b96dbcf149a9094f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Mon, 21 Dec 2020 11:21:22 +0800
Subject: [PATCH 10/12] refactor: rename run to finish

---
 src/client.rs             | 2 +-
 tests/imap_integration.rs | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index 5d4ddd4..8b94376 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -127,7 +127,7 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
     }
 
     /// Run command
-    pub fn run(&mut self) -> Result<()> {
+    pub fn finish(&mut self) -> Result<()> {
         let flagstr = self
             .flags
             .clone()
diff --git a/tests/imap_integration.rs b/tests/imap_integration.rs
index 536efd2..9d443cd 100644
--- a/tests/imap_integration.rs
+++ b/tests/imap_integration.rs
@@ -254,7 +254,7 @@ fn append() {
     c.select(mbox).unwrap();
     //append
     c.append(mbox, e.message_to_string().unwrap().as_bytes())
-        .run()
+        .finish()
         .unwrap();
 
     // now we should see the e-mail!
@@ -305,7 +305,7 @@ fn append_with_flags() {
     let flags: &[Flag] = &[Flag::Seen, Flag::Flagged];
     c.append(mbox, e.message_to_string().unwrap().as_bytes())
         .flags(flags)
-        .run()
+        .finish()
         .unwrap();
 
     // now we should see the e-mail!
@@ -365,7 +365,7 @@ fn append_with_flags_and_date() {
         .flag(Flag::Seen)
         .flag(Flag::Flagged)
         .internal_date(date)
-        .run()
+        .finish()
         .unwrap();
 
     // now we should see the e-mail!

From b2f2e297c2f7d9cf04005bf5c0a76f923b1d4140 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Mon, 21 Dec 2020 11:21:40 +0800
Subject: [PATCH 11/12] docs: improve docs

---
 src/client.rs | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/client.rs b/src/client.rs
index 8b94376..0637514 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -110,7 +110,7 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
         self
     }
 
-    /// Append an array of flags
+    /// Set multiple flags at once.
     pub fn flags(&mut self, flags: impl IntoIterator<Item = Flag<'a>>) -> &mut Self {
         self.flags.extend(flags);
         self
@@ -126,7 +126,10 @@ impl<'a, T: Read + Write> AppendCmd<'a, T> {
         self
     }
 
-    /// Run command
+    /// Finishes up the command and executes it.
+    ///
+    /// Note: be sure to set flags and optional date before you
+    /// finish the command.
     pub fn finish(&mut self) -> Result<()> {
         let flagstr = self
             .flags

From 80f54b1e81e339e67bcebe1edc276402056b0679 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20B=C3=B8cker-Larsen?= <m19n@pm.me>
Date: Tue, 22 Dec 2020 20:31:55 +0800
Subject: [PATCH 12/12] test: correct test for append_with_flags

---
 tests/imap_integration.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/imap_integration.rs b/tests/imap_integration.rs
index 9d443cd..997b2f5 100644
--- a/tests/imap_integration.rs
+++ b/tests/imap_integration.rs
@@ -302,7 +302,7 @@ fn append_with_flags() {
     let mbox = "INBOX";
     c.select(mbox).unwrap();
     //append
-    let flags: &[Flag] = &[Flag::Seen, Flag::Flagged];
+    let flags = vec![Flag::Seen, Flag::Flagged];
     c.append(mbox, e.message_to_string().unwrap().as_bytes())
         .flags(flags)
         .finish()