From 5411d07c37fbfb89e3efde2c4562a6dd4d0f1ebb Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 28 Nov 2019 20:24:12 -0700
Subject: [PATCH] fix(persist): Clarify API behavior

Closes #51

BREAKING CHANGE: `persist_if` was renamed to `into_persist_if`.
---
 Cargo.toml          |  2 +-
 src/fixture/dir.rs  | 28 ++++++++++++++++++++++++++--
 src/fixture/file.rs | 28 ++++++++++++++++++++++++++--
 3 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 7b4da9b..575a615 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "assert_fs"
-version = "0.11.3"
+version = "0.12.0"
 authors = ["Ed Page <eopage@gmail.com>"]
 description = "Filesystem fixtures and assertions for testing."
 license = "MIT OR Apache-2.0"
diff --git a/src/fixture/dir.rs b/src/fixture/dir.rs
index e40608b..6bd985a 100644
--- a/src/fixture/dir.rs
+++ b/src/fixture/dir.rs
@@ -96,21 +96,45 @@ impl TempDir {
 
     /// Conditionally persist the temporary directory for debug purposes.
     ///
+    /// Note: this operation is not reversible, i.e. `into_persist_if(false)` is a no-op.
+    ///
     /// # Examples
     ///
     /// ```no_run
     /// use assert_fs::fixture::TempDir;
     ///
-    /// let tmp_dir = TempDir::new().unwrap().persist_if(true);
+    /// let tmp_dir = TempDir::new()
+    ///     .unwrap()
+    ///     .into_persist_if(std::env::var_os("TEST_PERSIST_FILES").is_some());
     ///
     /// // Ensure deletion happens.
     /// tmp_dir.close().unwrap();
     /// ```
-    pub fn persist_if(self, yes: bool) -> Self {
+    pub fn into_persist_if(self, yes: bool) -> Self {
         if !yes {
             return self;
         }
 
+        self.into_persist()
+    }
+
+    /// Persist the temporary directory for debug purposes.
+    ///
+    /// Note: this operation is not reversible, i.e. `into_persist_if(false)` is a no-op.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use assert_fs::fixture::TempDir;
+    ///
+    /// let tmp_dir = TempDir::new()
+    ///     .unwrap()
+    ///     .into_persist();
+    ///
+    /// // Ensure deletion happens.
+    /// tmp_dir.close().unwrap();
+    /// ```
+    pub fn into_persist(self) -> Self {
         let path = match self.temp {
             Inner::Temp(temp) => temp.into_path(),
             Inner::Persisted(path) => path,
diff --git a/src/fixture/file.rs b/src/fixture/file.rs
index 462f8fb..e6bba77 100644
--- a/src/fixture/file.rs
+++ b/src/fixture/file.rs
@@ -101,21 +101,45 @@ impl NamedTempFile {
 
     /// Conditionally persist the temporary file for debug purposes.
     ///
+    /// Note: this operation is not reversible, i.e. `into_persist_if(false)` is a no-op.
+    ///
     /// # Examples
     ///
     /// ```no_run
     /// use assert_fs::fixture::NamedTempFile;
     ///
-    /// let tmp_file = NamedTempFile::new("foo.rs").unwrap().persist_if(true);
+    /// let tmp_file = NamedTempFile::new("foo.rs")
+    ///     .unwrap()
+    ///     .into_persist_if(std::env::var_os("TEST_PERSIST_FILES").is_some());
     ///
     /// // Ensure deletion happens.
     /// tmp_file.close().unwrap();
     /// ```
-    pub fn persist_if(mut self, yes: bool) -> Self {
+    pub fn into_persist_if(self, yes: bool) -> Self {
         if !yes {
             return self;
         }
 
+        self.into_persist()
+    }
+
+    /// Persist the temporary file for debug purposes.
+    ///
+    /// Note: this operation is not reversible, i.e. `into_persist_if(false)` is a no-op.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use assert_fs::fixture::NamedTempFile;
+    ///
+    /// let tmp_file = NamedTempFile::new("foo.rs")
+    ///     .unwrap()
+    ///     .into_persist();
+    ///
+    /// // Ensure deletion happens.
+    /// tmp_file.close().unwrap();
+    /// ```
+    pub fn into_persist(mut self) -> Self {
         let mut temp = Inner::Persisted;
         ::std::mem::swap(&mut self.temp, &mut temp);
         if let Inner::Temp(temp) = temp {