Struct ergo_fs::PathTmp

pub struct PathTmp { /* fields omitted */ }

A PathDir that is automatically deleted when it goes out of scope.

Unlike the other Path types, this type is not cloneable.

The PathTmp type creates a directory on the file system that is deleted once it goes out of scope. At construction, the PathTmp creates a new directory with a randomly generated name, and with a prefix of your choosing.

The default constructor, PathTmp::create, creates directories in the location returned by std::env::temp_dir(), but PathTmp can be configured to manage a temporary directory in any location by constructing with PathTmp::create_in.

After creating a PathTmp, work with the file system by doing standard std::fs file system operations on its Path, which can be retrieved with PathTmp::path. Once the PathTmp 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.

Various platform-specific conditions may cause PathTmp 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 PathTmp goes out of scope. The PathTmp destructor will silently ignore any errors in deleting the directory; to instead handle errors call PathTmp::close.

Note that if the program exits before the PathTmp 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.

Methods

impl PathTmp

fn create(prefix: &str) -> Result<PathTmp>

Attempts to make a temporary directory inside of env::temp_dir() whose name will have the prefix, prefix. The directory and everything inside it will be automatically deleted once the returned PathTmp is destroyed.

Errors

If the directory can not be created, Err is returned.

Examples

use ergo_fs::{PathFile, PathTmp};

let tmp_dir = PathTmp::create("example").unwrap();
let file = PathFile::create(tmp_dir.join("temporary-note.txt")).unwrap();
let message = "This file existed, but only for a moment.";
file.write_str(message).unwrap();
assert_eq!(file.read_string().unwrap(), message);

// Close the tmp_dir manually (would automatically happen when dropped).
// All contents are automatically deleted.
tmp_dir.close().unwrap();
assert!(!file.exists());

fn create_in<P: AsRef<Path>>(base: P, prefix: &str) -> Result<PathTmp>

Attempts to create a temporary directory inside of base whose name will have the prefix prefix. The created directory and everything inside it will be automatically deleted once the returned PathTmp is destroyed.

Errors

If the directory can not be created, Err is returned.

Examples

use ergo_fs::{PathFile, PathTmp};

let tmp_dir = PathTmp::create_in(".", "example").unwrap();
let file = PathFile::create(tmp_dir.join("temporary-note.txt")).unwrap();
let message = "This file existed, but only for a moment.";
file.write_str(message).unwrap();
assert_eq!(file.read_string().unwrap(), message);

// Close the tmp_dir manually (would automatically happen when dropped).
// All contents are automatically deleted.
tmp_dir.close().unwrap();
assert!(!file.exists());

fn persist(self) -> PathDir

Persist the temporary directory on the file system.

This method consumes self, returning the location of the temporary directory as a regular PathDir. The directory will no longer be automatically deleted.

Examples

use ergo_fs::PathTmp;

let tmp_dir = PathTmp::create_in(".", "persist").unwrap();
let dir = tmp_dir.persist();

// The directory is now persisted to disk
assert!(dir.exists());

// It can still be manually removed though.
dir.remove().unwrap();

fn close(self) -> Result<()>

Closes and removes the temporary directory, returing a Result.

Although PathTmp 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::Errors 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.

fn as_path(&self) -> &Path

Return a reference to a basic std::path::Path

Methods from Deref<Target = PathAbs>

fn into_file(self) -> Result<PathFile, Error>

Resolve the PathAbs as a PathFile. Return an error if it is not a file.

fn into_dir(self) -> Result<PathDir, Error>

Resolve the PathAbs as a PathDir. Return an error if it is not a directory.

fn parent_dir(&self) -> Option<PathDir>

Get the parent directory of this path as a PathDir.

This does not make aditional syscalls, as the parent by definition must be a directory and exist.

Examples

use path_abs::{PathDir, PathFile};

let lib = PathFile::new("src/lib.rs")?;
let src = lib.parent_dir().unwrap();
assert_eq!(PathDir::new("src")?, src);

fn as_path(&self) -> &Path

Return a reference to a basic std::path::Path

Trait Implementations

impl Debug for PathTmp

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for PathTmp

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl AsRef<PathDir> for PathTmp

fn as_ref(&self) -> &PathDir

Performs the conversion.

impl AsRef<PathAbs> for PathTmp

fn as_ref(&self) -> &PathAbs

Performs the conversion.

impl AsRef<Path> for PathTmp

fn as_ref(&self) -> &Path

Performs the conversion.

impl AsRef<PathBuf> for PathTmp

fn as_ref(&self) -> &PathBuf

Performs the conversion.

impl Deref for PathTmp

type Target = PathAbs

The resulting type after dereferencing.

fn deref(&self) -> &PathAbs

Dereferences the value.

impl Into<PathAbs> for PathTmp

fn into(self) -> PathAbs

Downgrades the PathTmp into a PathAbs

impl Into<PathArc> for PathTmp

fn into(self) -> PathArc

Downgrades the PathTmp into a PathArc

impl Into<PathBuf> for PathTmp

fn into(self) -> PathBuf

Downgrades the PathTmp into a PathBuf. Avoids a clone if this is the only reference.