fakeenv

Struct EnvStore

Source
pub struct EnvStore { /* private fields */ }
Expand description

A handle to either the real environment or a fake environment.

§Example

§Using the real environment

let env = EnvStore::real();
std::env::set_var("THE_ANSWER", "42");
assert_eq!(env.var("THE_ANSWER").unwrap(), "42");

§Making a fake environment

let env = EnvStore::fake();
env.set_var("THE_ANSWER", "42");
assert_eq!(env.var("THE_ANSWER").unwrap(), "42");

§Cloning

The Clone implementation does the shallow copy, whereas the EnvStore::to_fake method does the deep copy.

let env = EnvStore::fake();
env.set_var("X", "42");

let env2 = env.to_fake();
env2.set_var("X", "53");
// The original env doesn't change
assert_eq!(env.var("X").unwrap(), "42");

let env3 = env.clone();
env3.set_var("X", "84");
// The original env changes as well
assert_eq!(env.var("X").unwrap(), "84");

§Default

The Default implementation is equivalent to EnvStore::real.

Implementations§

Source§

impl EnvStore

Source

pub fn audio_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_audio_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_audio_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn cache_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_cache_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_cache_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn config_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_config_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_config_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn data_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_data_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_data_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn data_local_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_data_local_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_data_local_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn desktop_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_desktop_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_desktop_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn document_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_document_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_document_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn download_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_download_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_download_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn executable_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_executable_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_executable_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn font_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_font_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_font_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn home_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_home_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_home_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn picture_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_picture_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_picture_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn public_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_public_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_public_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn runtime_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_runtime_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_runtime_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn template_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_template_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_template_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source

pub fn video_dir(&self) -> Option<PathBuf>

Available on crate feature dirs only.

Returns the path to the directory. See dirs for details.

§Examples
let env = EnvStore::real();
println!("home directory = {:?}", env.home_dir());
Source

pub fn set_video_dir<P: AsRef<Path>>(&self, path: P)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.set_home_dir("/foo/bar");
assert_eq!(&env.home_dir().unwrap(), Path::new("/foo/bar"));
Source

pub fn unset_video_dir(&self)

Available on crate features dirs and fake only.

Modifies the faked path to the directory. See dirs for details.

§Panics

This method panics when self points to the real environment.

§Examples
let env = EnvStore::fake();
env.unset_home_dir();
assert!(env.home_dir().is_none());
Source§

impl EnvStore

Source

pub const fn real() -> Self

Returns the handle to the real environment.

§Examples
let env = EnvStore::real();
std::env::set_var("THE_ANSWER", "42");
assert_eq!(env.var("THE_ANSWER").unwrap(), "42");
Source

pub fn fake() -> Self

Available on crate feature fake only.

Creates a new fake environment from the real environment.

§Examples
let env = EnvStore::fake();
env.set_var("THE_ANSWER", "42");
assert_eq!(env.var("THE_ANSWER").unwrap(), "42");
Source

pub fn to_fake(&self) -> Self

Available on crate feature fake only.

Creates a new fake environment from the existing environment (real or fake).

§Examples
let env = EnvStore::fake();
env.set_var("THE_ANSWER", "42");

let env2 = env.to_fake();
env2.set_var("THE_ANSWER", "84");

assert_eq!(env2.var("THE_ANSWER").unwrap(), "84");
assert_eq!(env.var("THE_ANSWER").unwrap(), "42");
Source

pub fn is_real(&self) -> bool

Returns true if this is the real environment.

Source

pub fn is_fake(&self) -> bool

Returns true if this is a fake environment.

Source

pub fn ptr_eq(&self, other: &Self) -> bool

Returns whether the two handle points to the same environment.

Source

pub fn var<K: AsRef<OsStr>>(&self, key: K) -> Result<String, VarError>

Fetches the environment variable key from the current process. Corresponds with std::env::var.

§Errors
  • Environment variable is not present
  • Environment variable is not valid unicode
§Panics

This function may panic if key is empty, contains an ASCII equals sign '=' or the NUL character '\0', or when the value contains the NUL character.

§Examples
let env = EnvStore::real();

let key = "HOME";
match env.var(key) {
    Ok(val) => println!("{}: {:?}", key, val),
    Err(e) => println!("couldn't interpret {}: {}", key, e),
}
Source

pub fn var_os<K: AsRef<OsStr>>(&self, key: K) -> Option<OsString>

Fetches the environment variable key from the current process, returning None if the variable isn’t set. Corresponds with std::env::var_os.

§Panics

This function may panic if key is empty, contains an ASCII equals sign '=' or the NUL character '\0', or when the value contains the NUL character.

§Examples
let env = EnvStore::real();

let key = "HOME";
match env.var_os(key) {
    Some(val) => println!("{}: {:?}", key, val),
    None => println!("{} is not defined in the environment.", key)
}
Source

pub fn vars(&self) -> Vars

Returns an iterator of (variable, value) pairs of strings, for all the environment variables of the current process. Corresponds with std::env::vars.

The returned iterator contains a snapshot of the process’s environment variables at the time of this invocation. Modifications to environment variables afterwards will not be reflected in the returned iterator.

§Panics

While iterating, the returned iterator will panic if any key or value in the environment is not valid unicode. If this is not desired, consider using the EnvStore::vars_os method.

§Examples
let env = EnvStore::real();

// We will iterate through the references to the element returned by
// env::vars();
for (key, value) in env.vars() {
    println!("{}: {}", key, value);
}
Source

pub fn vars_os(&self) -> VarsOs

Returns an iterator of (variable, value) pairs of OS strings, for all the environment variables of the current process. Corresponds with std::env::vars_os.

The returned iterator contains a snapshot of the process’s environment variables at the time of this invocation. Modifications to environment variables afterwards will not be reflected in the returned iterator.

§Examples
let env = EnvStore::real();

// We will iterate through the references to the element returned by
// env.vars_os();
for (key, value) in env.vars_os() {
    println!("{:?}: {:?}", key, value);
}
Source

pub fn set_var<K: AsRef<OsStr>, V: AsRef<OsStr>>(&self, k: K, v: V)

Sets the environment variable k to the value v for the currently running process. Corresponds with std::env::set_var.

Note that while concurrent access to environment variables is safe in Rust, some platforms only expose inherently unsafe non-threadsafe APIs for inspecting the environment. As a result, extra care needs to be taken when auditing calls to unsafe external FFI functions to ensure that any external environment accesses are properly synchronized with accesses in Rust.

Discussion of this unsafety on Unix may be found in:

§Panics

This function may panic if key is empty, contains an ASCII equals sign '=' or the NUL character '\0', or when the value contains the NUL character.

§Examples
let env = EnvStore::real();

let key = "KEY";
env.set_var(key, "VALUE");
assert_eq!(env.var(key), Ok("VALUE".to_string()));
Source

pub fn remove_var<K: AsRef<OsStr>>(&self, k: K)

Removes an environment variable from the environment of the currently running process. Corresponds with std::env::remove_var.

Note that while concurrent access to environment variables is safe in Rust, some platforms only expose inherently unsafe non-threadsafe APIs for inspecting the environment. As a result extra care needs to be taken when auditing calls to unsafe external FFI functions to ensure that any external environment accesses are properly synchronized with accesses in Rust.

Discussion of this unsafety on Unix may be found in:

§Panics

This function may panic if key is empty, contains an ASCII equals sign '=' or the NUL character '\0', or when the value contains the NUL character.

§Examples
let env = EnvStore::real();

let key = "KEY";
env.set_var(key, "VALUE");
assert_eq!(env.var(key), Ok("VALUE".to_string()));

env.remove_var(key);
assert!(env.var(key).is_err());
Source

pub fn current_dir(&self) -> Result<PathBuf>

Returns the current working directory as a PathBuf. Corresponds with std::env::current_dir.

§Errors

Returns an Err if the current working directory value is invalid. Possible cases:

  • Current directory does not exist.
  • There are insufficient permissions to access the current directory.
§Examples
use fakeenv::EnvStore;

fn main() -> std::io::Result<()> {
    let env = EnvStore::real();

    let path = env.current_dir()?;
    println!("The current directory is {}", path.display());
    Ok(())
}
Source

pub fn set_current_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>

Changes the current working directory to the specified path. Corresponds with std::env::set_current_dir.

Returns an Err if the operation fails.

§Examples
use fakeenv::EnvStore;
use std::path::Path;

let env = EnvStore::real();

let root = Path::new("/");
assert!(env.set_current_dir(&root).is_ok());
println!("Successfully changed working directory to {}!", root.display());

Trait Implementations§

Source§

impl Clone for EnvStore

Source§

fn clone(&self) -> EnvStore

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for EnvStore

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for EnvStore

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl RefUnwindSafe for EnvStore

Source§

impl UnwindSafe for EnvStore

Auto Trait Implementations§

§

impl Freeze for EnvStore

§

impl Send for EnvStore

§

impl Sync for EnvStore

§

impl Unpin for EnvStore

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.