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. Shell is cheaply clonable and you can use methods like Shell::with_current_dir to create independent copies with separate environments.

By convention, the variable holding the shell is named sh.

Example

use xshell::{cmd, Shell};

let sh = Shell::new()?;
let sh = sh.with_current_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>

Creates a new Shell.

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

pub fn current_dir(&self) -> &Path

Returns the working directory for this Shell.

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

pub fn set_current_dir(&mut self, path: impl AsRef<Path>)

Changes the working directory for this Shell.

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

pub fn with_current_dir(&self, path: impl AsRef<Path>) -> Shell

Returns a new Shell with the working directory set to path.

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

pub fn var(&self, key: impl AsRef<OsStr>) -> 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.

pub fn var_os(&self, key: impl AsRef<OsStr>) -> 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.

pub fn vars_os(&self) -> HashMap<OsString, OsString>

Fetches the whole environment as a (Key, Value) iterator for this Shell.

Returns an error if any of the variables are not utf8.

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

pub fn set_var(&mut self, key: impl AsRef<OsStr>, value: impl AsRef<OsStr>)

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

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

pub fn with_var( &self, key: impl AsRef<OsStr>, value: impl AsRef<OsStr>, ) -> Shell

Returns a new Shell with environmental variable key set to value.

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

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

Read an utf-8 encoded text file into string.

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

Read a file into a vector of bytes.

pub fn write_file( &self, path: impl AsRef<Path>, contents: impl AsRef<[u8]>, ) -> 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.

pub fn copy_file( &self, src_file: impl AsRef<Path>, dst_file: impl AsRef<Path>, ) -> Result<()>

Creates a dst file with the same contents as src

pub fn copy_file_to_dir( &self, src_file: impl AsRef<Path>, dst_dir: impl AsRef<Path>, ) -> Result<()>

Creates a file in dst directory with the same name and contents as src.

pub fn hard_link( &self, src: impl AsRef<Path>, dst: impl AsRef<Path>, ) -> Result<()>

Hardlinks src to dst.

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

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

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

Ensures that the specified directory exist.

All intermediate directories will also be created as needed.

pub fn create_temp_dir(&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.

pub fn remove_path(&self, path: impl AsRef<Path>) -> Result<()>

Removes the file or directory at the given path.

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

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

Be mindful of Time Of Check, Time Of Use (TOCTOU) errors – often, it is better to attempt a given operation and handle an error if a path doesn’t exist, instead of trying to check beforehand.

pub fn cmd(&self, program: impl AsRef<OsStr>) -> Cmd

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

Formats the value using the given formatter.