fix(persist): Clarify API behavior

Closes #51

BREAKING CHANGE: `persist_if` was renamed to `into_persist_if`.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "assert_fs"
-version = "0.11.3"
+version = "0.12.0"
 authors = ["Ed Page <[email protected]>"]
 description = "Filesystem fixtures and assertions for testing."
 license = "MIT OR Apache-2.0"

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,

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 {