Merge pull request #41 from epage/ext

Improve fixture support

Author: epage

src/fixture/child.rs

@@ -0,0 +1,86 @@
+use std::path;
+
+/// Access paths within [`TempDir`] for testing.
+///
+/// See [`ChildPath`] trait implementations.
+///
+/// ```rust
+/// use assert_fs::prelude::*;
+///
+/// let temp = assert_fs::TempDir::new().unwrap();
+/// let input_file = temp.child("foo.txt");
+/// input_file.touch().unwrap();
+/// temp.close().unwrap();
+/// ```
+///
+/// [`TempDir`]: struct.TempDir.html
+/// [`ChildPath`]: struct.ChildPath.html
+pub trait PathChild {
+    /// Access a path within the temp directory.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use assert_fs::prelude::*;
+    ///
+    /// let temp = assert_fs::TempDir::new().unwrap();
+    /// println!("{}", temp.path().display());
+    /// println!("{}", temp.child("foo/bar.txt").path().display());
+    /// temp.close().unwrap();
+    /// ```
+    fn child<P>(&self, path: P) -> ChildPath
+    where
+        P: AsRef<path::Path>;
+}
+
+impl PathChild for super::TempDir {
+    fn child<P>(&self, path: P) -> ChildPath
+    where
+        P: AsRef<path::Path>,
+    {
+        ChildPath::new(self.path().join(path.as_ref()))
+    }
+}
+
+/// A path within a [`TempDir`]
+///
+/// See Trait Implementations.
+///
+/// # Examples
+///
+/// ```rust
+/// use assert_fs::prelude::*;
+///
+/// let temp = assert_fs::TempDir::new().unwrap();
+///
+/// let input_file = temp.child("foo.txt");
+/// input_file.touch().unwrap();
+///
+/// temp.child("bar.txt").touch().unwrap();
+///
+/// temp.close().unwrap();
+/// ```
+///
+/// [`TempDir`]: struct.TempDir.html
+pub struct ChildPath {
+    path: path::PathBuf,
+}
+
+impl ChildPath {
+    /// Wrap a path for use with extension traits.
+    ///
+    /// See trait implementations or [`PathChild`] for more details.
+    ///
+    /// [`PathChild`]: trait.PathChild.html
+    pub fn new<P>(path: P) -> Self
+    where
+        P: Into<path::PathBuf>,
+    {
+        Self { path: path.into() }
+    }
+
+    /// Access the path.
+    pub fn path(&self) -> &path::Path {
+        &self.path
+    }
+}

src/fixture/dir.rs

@@ -0,0 +1,179 @@
+use std::path;
+
+use tempfile;
+
+use super::errors::*;
+
+/// A directory in the filesystem that is automatically deleted when
+/// it goes out of scope.
+///
+/// The [`TempDir`] type creates a directory on the file system that
+/// is deleted once it goes out of scope. At construction, the
+/// `TempDir` creates a new directory with a randomly generated name.
+///
+/// The constructor, [`TempDir::new()`], creates directories in
+/// the location returned by [`std::env::temp_dir()`].
+///
+/// After creating a `TempDir`, work with the file system by doing
+/// standard [`std::fs`] file system operations on its [`Path`],
+/// which can be retrieved with [`TempDir::path()`]. Once the `TempDir`
+/// value is dropped, the directory at the path will be deleted, along
+/// with any files and directories it contains. It is your responsibility
+/// to ensure that no further file system operations are attempted
+/// inside the temporary directory once it has been deleted.
+///
+/// # Resource Leaking
+///
+/// Various platform-specific conditions may cause `TempDir` to fail
+/// to delete the underlying directory. It's important to ensure that
+/// handles (like [`File`] and [`ReadDir`]) to files inside the
+/// directory are dropped before the `TempDir` goes out of scope. The
+/// `TempDir` destructor will silently ignore any errors in deleting
+/// the directory; to instead handle errors call [`TempDir::close()`].
+///
+/// Note that if the program exits before the `TempDir` destructor is
+/// run, such as via [`std::process::exit()`], by segfaulting, or by
+/// receiving a signal like `SIGINT`, then the temporary directory
+/// will not be deleted.
+///
+/// # Examples
+///
+/// Create a temporary directory with a generated name:
+///
+/// ```
+/// use assert_fs::fixture::TempDir;
+///
+/// let tmp_dir = TempDir::new().unwrap();
+///
+/// // Ensure deletion happens.
+/// tmp_dir.close().unwrap();
+/// ```
+///
+/// [`File`]: http://doc.rust-lang.org/std/fs/struct.File.html
+/// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
+/// [`ReadDir`]: http://doc.rust-lang.org/std/fs/struct.ReadDir.html
+/// [`TempDir::close()`]: struct.TempDir.html#method.close
+/// [`TempDir::new()`]: struct.TempDir.html#method.new
+/// [`TempDir::path()`]: struct.TempDir.html#method.path
+/// [`TempDir`]: struct.TempDir.html
+/// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html
+/// [`std::fs`]: http://doc.rust-lang.org/std/fs/index.html
+/// [`std::process::exit()`]: http://doc.rust-lang.org/std/process/fn.exit.html
+pub struct TempDir {
+    temp: Inner,
+}
+
+enum Inner {
+    Temp(tempfile::TempDir),
+    Persisted(path::PathBuf),
+}
+
+impl TempDir {
+    /// Attempts to make a temporary directory inside of `env::temp_dir()`.
+    ///
+    /// The directory and everything inside it will be automatically deleted
+    /// once the returned `TempDir` is destroyed.
+    ///
+    /// # Errors
+    ///
+    /// If the directory can not be created, `Err` is returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use assert_fs::fixture::TempDir;
+    ///
+    /// let tmp_dir = TempDir::new().unwrap();
+    ///
+    /// // Ensure deletion happens.
+    /// tmp_dir.close().unwrap();
+    /// ```
+    pub fn new() -> Result<Self, FixtureError> {
+        let temp = tempfile::TempDir::new().chain(FixtureError::new(FixtureKind::CreateDir))?;
+        let temp = Inner::Temp(temp);
+        Ok(Self { temp })
+    }
+
+    /// Conditionally persist the temporary directory for debug purposes.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use assert_fs::fixture::TempDir;
+    ///
+    /// let tmp_dir = TempDir::new().unwrap().persist_if(true);
+    ///
+    /// // Ensure deletion happens.
+    /// tmp_dir.close().unwrap();
+    /// ```
+    pub fn persist_if(self, yes: bool) -> Self {
+        if !yes {
+            return self;
+        }
+
+        let path = match self.temp {
+            Inner::Temp(temp) => temp.into_path(),
+            Inner::Persisted(path) => path,
+        };
+        let temp = Inner::Persisted(path);
+        Self { temp }
+    }
+
+    /// Accesses the [`Path`] to the temporary directory.
+    ///
+    /// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use assert_fs::fixture::TempDir;
+    ///
+    /// let tmp_dir = TempDir::new().unwrap();
+    ///
+    /// println!("{}", tmp_dir.path().display());
+    ///
+    /// // Ensure deletion happens.
+    /// tmp_dir.close().unwrap();
+    /// ```
+    pub fn path(&self) -> &path::Path {
+        match self.temp {
+            Inner::Temp(ref temp) => temp.path(),
+            Inner::Persisted(ref path) => path.as_path(),
+        }
+    }
+
+    /// Closes and removes the temporary directory, returing a `Result`.
+    ///
+    /// Although `TempDir` removes the directory on drop, in the destructor
+    /// any errors are ignored. To detect errors cleaning up the temporary
+    /// directory, call `close` instead.
+    ///
+    /// # Errors
+    ///
+    /// This function may return a variety of [`std::io::Error`]s that result from deleting
+    /// the files and directories contained with the temporary directory,
+    /// as well as from deleting the temporary directory itself. These errors
+    /// may be platform specific.
+    ///
+    /// [`std::io::Error`]: http://doc.rust-lang.org/std/io/struct.Error.html
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use assert_fs::fixture::TempDir;
+    ///
+    /// let tmp_dir = TempDir::new().unwrap();
+    ///
+    /// // Ensure deletion happens.
+    /// tmp_dir.close().unwrap();
+    /// ```
+    pub fn close(self) -> Result<(), FixtureError> {
+        match self.temp {
+            Inner::Temp(temp) => temp
+                .close()
+                .chain(FixtureError::new(FixtureKind::Cleanup))?,
+            Inner::Persisted(_) => (),
+        }
+        Ok(())
+    }
+}

src/errors.rs renamed to src/fixture/errors.rs

@@ -49,14 +49,17 @@ pub enum FixtureKind {
     CopyFile,
     /// Failed when creating a directory.
     CreateDir,
+    /// Failed to cleanup fixture.
+    Cleanup,
 }
 
 impl fmt::Display for FixtureKind {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match *self {
-            FixtureKind::Walk => write!(f, "Failed when walking the source tree"),
-            FixtureKind::CopyFile => write!(f, "Failed when copying a file"),
-            FixtureKind::CreateDir => write!(f, "Failed when creating a directory"),
+            FixtureKind::Walk => write!(f, "Failed when walking the source tree,"),
+            FixtureKind::CopyFile => write!(f, "Failed when copying a file."),
+            FixtureKind::CreateDir => write!(f, "Failed when creating a directory."),
+            FixtureKind::Cleanup => write!(f, "Failed to cleanup fixture."),
         }
     }
 }