Struct `Shell`

struct Shell { ... }

A Shell is the main API entry point.

Almost all of the crate's functionality is available as methods of the Shell object.

Shell is a stateful object. It maintains a logical working directory and an environment map. They are independent from process's std::env::current_dir and std::env::var, and only affect paths and commands passed to the Shell.

By convention, variable holding the shell is named sh.

Example

use xshell::{cmd, Shell};

let sh = Shell::new()?;
let _d = sh.push_dir("./target");
let cwd = sh.current_dir();
cmd!(sh, "echo current dir is {cwd}").run()?;

let process_cwd = std::env::current_dir().unwrap();
assert_eq!(cwd, process_cwd.join("./target"));
# Ok::<(), xshell::Error>(())

Implementations

`impl Shell`

fn new() -> Result<Shell>

Creates a new Shell.

Fails if std::env::current_dir returns an error.

fn current_dir(self: &Self) -> PathBuf

Returns the working directory for this Shell.

All relative paths are interpreted relative to this directory, rather than std::env::current_dir.

fn change_dir<P: AsRef<Path>>(self: &Self, dir: P)

Changes the working directory for this Shell.

Note that this doesn't affect std::env::current_dir.

fn push_dir<P: AsRef<Path>>(self: &Self, path: P) -> PushDir<'_>

Temporary changes the working directory of this Shell.

Returns a RAII guard which reverts the working directory to the old value when dropped.

Note that this doesn't affect std::env::current_dir.

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

Fetches the environmental variable key for this Shell.

Returns an error if the variable is not set, or set to a non-utf8 value.

Environment of the Shell affects all commands spawned via this shell.

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

Fetches the environmental variable key for this Shell as OsString Returns None if the variable is not set.

Environment of the Shell affects all commands spawned via this shell.

fn set_var<K: AsRef<OsStr>, V: AsRef<OsStr>>(self: &Self, key: K, val: V)

Sets the value of key environment variable for this Shell to val.

Note that this doesn't affect std::env::var.

fn push_env<K: AsRef<OsStr>, V: AsRef<OsStr>>(self: &Self, key: K, val: V) -> PushEnv<'_>

Temporary sets the value of key environment variable for this Shell to val.

Returns a RAII guard which restores the old environment when dropped.

Note that this doesn't affect std::env::var.

fn read_file<P: AsRef<Path>>(self: &Self, path: P) -> Result<String>

Read the entire contents of a file into a string.

fn read_binary_file<P: AsRef<Path>>(self: &Self, path: P) -> Result<Vec<u8>>

Read the entire contents of a file into a vector of bytes.

fn read_dir<P: AsRef<Path>>(self: &Self, path: P) -> Result<Vec<PathBuf>>

Returns a sorted list of paths directly contained in the directory at path.

fn write_file<P: AsRef<Path>, C: AsRef<[u8]>>(self: &Self, path: P, contents: C) -> Result<()>

Write a slice as the entire contents of a file.

This function will create the file and all intermediate directories if they don't exist.

fn copy_file<S: AsRef<Path>, D: AsRef<Path>>(self: &Self, src: S, dst: D) -> Result<()>

Copies src into dst.

src must be a file, but dst need not be. If dst is an existing directory, src will be copied into a file in the dst directory whose name is same as that of src.

Otherwise, dst is a file or does not exist, and src will be copied into it.

fn hard_link<S: AsRef<Path>, D: AsRef<Path>>(self: &Self, src: S, dst: D) -> Result<()>

Hardlinks src to dst.

fn create_dir<P: AsRef<Path>>(self: &Self, path: P) -> Result<PathBuf>

Creates the specified directory.

All intermediate directories will also be created.

fn create_temp_dir(self: &Self) -> Result<TempDir>

Creates an empty named world-readable temporary directory.

Returns a TempDir RAII guard with the path to the directory. When dropped, the temporary directory and all of its contents will be removed.

Note that this is an insecure method -- any other process on the system will be able to read the data.

fn remove_path<P: AsRef<Path>>(self: &Self, path: P) -> Result<()>

Removes the file or directory at the given path.

fn path_exists<P: AsRef<Path>>(self: &Self, path: P) -> bool

Returns whether a file or directory exists at the given path.

fn cmd<P: AsRef<Path>>(self: &Self, program: P) -> Cmd<'_>

Creates a new Cmd that executes the given program.

`impl Clone for Shell`

fn clone(self: &Self) -> Shell

`impl Debug for Shell`

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

`impl Freeze for Shell`

`impl RefUnwindSafe for Shell`

`impl Send for Shell`

`impl Sync for Shell`

`impl Unpin for Shell`

`impl UnwindSafe for Shell`

`impl<T> Any for Shell`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for Shell`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for Shell`

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

`impl<T> CloneToUninit for Shell`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for Shell`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for Shell`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for Shell`

fn into(self: Self) -> U

Calls U::from(self).

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

`impl<T, U> TryFrom for Shell`

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

`impl<T, U> TryInto for Shell`

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