Struct Shell

pub struct Shell { /* private fields */ }

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"));

Implementations

impl Shell

pub fn new() -> Result<Shell, Error>

Creates a new Shell.

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

pub fn current_dir(&self) -> PathBuf

Returns the working directory for this Shell.

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

pub fn change_dir<P>(&self, dir: P)

where P: AsRef<Path>,

Changes the working directory for this Shell.

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

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

where P: AsRef<Path>,

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.

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

where K: AsRef<OsStr>,

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.

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

where K: AsRef<OsStr>,

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.

pub fn set_var<K, V>(&self, key: K, val: V)

where K: AsRef<OsStr>, V: AsRef<OsStr>,

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

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

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

where K: AsRef<OsStr>, V: AsRef<OsStr>,

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.

pub fn read_file<P>(&self, path: P) -> Result<String, Error>

where P: AsRef<Path>,

Read the entire contents of a file into a string.

pub fn read_binary_file<P>(&self, path: P) -> Result<Vec<u8>, Error>

where P: AsRef<Path>,

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

pub fn read_dir<P>(&self, path: P) -> Result<Vec<PathBuf>, Error>

where P: AsRef<Path>,

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

pub fn write_file<P, C>(&self, path: P, contents: C) -> Result<(), Error>

where P: AsRef<Path>, C: AsRef<[u8]>,

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.

pub fn copy_file<S, D>(&self, src: S, dst: D) -> Result<(), Error>

where S: AsRef<Path>, D: AsRef<Path>,

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.

pub fn hard_link<S, D>(&self, src: S, dst: D) -> Result<(), Error>

where S: AsRef<Path>, D: AsRef<Path>,

Hardlinks src to dst.

pub fn create_dir<P>(&self, path: P) -> Result<PathBuf, Error>

where P: AsRef<Path>,

Creates the specified directory.

All intermediate directories will also be created.

pub fn create_temp_dir(&self) -> Result<TempDir, Error>

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.

pub fn remove_path<P>(&self, path: P) -> Result<(), Error>

where P: AsRef<Path>,

Removes the file or directory at the given path.

pub fn path_exists<P>(&self, path: P) -> bool

where P: AsRef<Path>,

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

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

where P: AsRef<Path>,

Creates a new Cmd that executes the given program.

Trait Implementations

impl Clone for Shell

fn clone(&self) -> Shell

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Shell

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

Formats the value using the given formatter.

impl RefUnwindSafe for Shell

impl UnwindSafe for Shell