Struct testdir::NumberedDirBuilder

pub struct NumberedDirBuilder { /* fields omitted */ }

Builder to create a NumberedDir.

While you can use NumberedDir::create directly this provides functionality to specific ways of constructing and re-using the NumberedDir.

Primarily this builder adds the concept of a root, a directory in which to create the NumberedDir. The concept of the base is the same as for NumberedDir and is the prefix of the name of the NumberedDir, thus a prefix of myprefix would create directories numbered myprefix-0, myprefix-1 etc. Likewise the count is also the same concept as for NumberedDir and specifies the maximum number of numbered directories, older directories will be cleaned up.

Configuring the builder

The basic constructor uses a root of testdir-of-$USER placed in the system's default temporary director location as per std::env::temp_dir. To customise the root you can use NumberedDirBuilder::root or NumberedDirBuilder::user_root]. The temporary directory provider can also be changed using [NumberedDirBuilder::tmpdir_provider`.

If you simply want an absolute path as parent directory for the numbered directory use the NumberedDirBuilder::set_parent function.

Sometimes you may have some external condition which signals that an existing numbered directory should be re-used. The [NumberedDirBuilder::reusefn] can be used for this. This is useful for example when running tests using cargo test and you want to use the same numbered directory for the unit, integration and doc tests even though they all run in different processes. The [testdir] macro does this by storing the process ID of the cargo test` process in the numbered directory and comparing that to the parent process ID of the current process.

Creating the NumberedDir

The NumberedDirBuilder::create method will create a new NumberedDir.

Implementations

impl NumberedDirBuilder

pub fn new(base: String) -> Self

Create a new builder for NumberedDir.

By default the root will be set to testdir-of-$USER. (using ROOT_DEFAULT) and the count will be set to 8 (KEEP_DEFAULT).

pub fn base(&mut self, base: String) -> &mut Self

Resets the base-name of the NumberedDir.

pub fn root(&mut self, root: impl Into<String>) -> &mut Self

Sets a root in the system's temporary directory location.

The NumberedDir's parent will be the root subdirectory of the system's default temporary directory location.

pub fn user_root(&mut self, prefix: &str) -> &mut Self

Sets a root with the username affixed.

Like NumberedDirBuilder::root this sets a subdirectory of the system's default temporary directory location as the parent direcotry for the NumberedDir. However it suffixes the username to the given prefix to use as root.

pub fn tmpdir_provider(
    &mut self,
    provider: impl FnOnce() -> PathBuf
) -> &mut Self

Uses a different temporary direcotry to place the root into.

By default std::env::temp_dir is used to get the system's temporary directory location to place the root into. This allows you to provide an alternate function which will be called to get the location of the directory where root will be placed. You provider should probably return an absolute path but this is not enforced.

pub fn set_parent(&mut self, path: PathBuf) -> &mut Self

Sets the parent directory for the NumberedDir.

This does not follow the root concept anymore, instead it directly sets the full path for the parent directory in which the NumberedDir will be created. You probably want this to be an absolute path but this is not enforced.

Be aware that it is a requirement that the last component of the parent directory is valid UTF-8.

pub fn count(&mut self, count: NonZeroU8) -> &mut Self

Sets the total number of NumberedDir directories to keep.

If creating the new NumberedDir would exceed this number, older directories will be removed.

pub fn reusefn<F>(&mut self, f: F) -> &mut Self where
    F: Fn(&Path) -> bool + Send + Sync + 'static, 

Enables NumberedDir re-use if f returns true.

The provided function will be called with each existing numbered directory and if it returns true this directory will be re-used instead of a new one being created.

pub fn disable_reuse(&mut self) -> &mut Self

Disables any previous call to NumberedDirBuilder::reusefn.

pub fn create(&self) -> Result<NumberedDir>

Creates a new NumberedDir as configured.

Trait Implementations

impl Clone for NumberedDirBuilder

pub fn clone(&self) -> NumberedDirBuilder

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NumberedDirBuilder

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.