Struct Shell

Source

pub struct Shell { /* private fields */ }

Expand description

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§

Source §

impl Shell

Source

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

Creates a new Shell.

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

Source

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.

Source

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

Changes the working directory for this Shell.

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

Source

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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Read the entire contents of a file into a string.

Source

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

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

Source

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

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

Source

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.

Source

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.

Source