Struct Overlay 

pub struct Overlay { /* private fields */ }

A Workspace over another that reads through to it and keeps every write, removal and rename to itself: run a file tool on it to learn what the tool would leave on disk (changes) while the disk stays as it is. It runs no commands, since what a command changes cannot be kept from the disk.

use std::sync::Arc;
use rig_core::tool::ChangeKind;
use rig_tools::overlay::Overlay;
use rig_tools::workspace::{Local, Workspace};

let path = std::env::temp_dir().join(format!("overlay-doc-{}.txt", std::process::id()));
let overlay = Overlay::new(Arc::new(Local));
overlay.write(&path, b"would be written\n")?;
assert!(!path.exists());
let changes = overlay.changes();
assert_eq!(changes.iter().map(|change| change.kind).collect::<Vec<_>>(), [ChangeKind::Created]);

Implementations

impl Overlay

pub fn new(inner: Arc<dyn Workspace>) -> Self

An overlay over inner, with nothing written yet.

pub fn changes(&self) -> Vec<FileChange>

What the writes kept here would do to the files of the workspace under it, in the order each file was first touched: created, modified or deleted, with its hunks, its text before and the FileState of each side (the FileState::unread size of a file too large to read). A file written back as it was, or created and removed again, is no change.

Trait Implementations

impl Debug for Overlay

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

Formats the value using the given formatter.

impl Workspace for Overlay

fn files( &self, root: &Path, glob: Option<&str>, listing: Listing, ) -> Result<Vec<PathBuf>>

The files under it, as listed there, without those removed here, then the files created here that listing keeps by their names (Listing::keeps; ignore files are not read for them).

fn host(&self) -> Option<&str>

Where it is when it is not this machine, such as ssh://dev@box; None for this machine.

fn stat(&self, path: &Path) -> Result<Stat>

What path is, its links followed: a file (its size, whether it is read-only, when it was last changed), a directory, something else, or nothing.

fn read(&self, path: &Path, limit: u64) -> Result<Contents>

Up to limit bytes of the regular file path, and its whole size. Anything but a regular file is refused without being opened: opening a FIFO or a device can block forever.

fn excerpt(&self, path: &Path, first: usize, count: usize) -> Result<Excerpt>

Lines first (from 1) on, at most count of them, of the regular text file path, with how many lines it has and the hash of all of it. Refused, as read_text refuses, when it is no regular file, larger than MAX_FILE_BYTES (a FileTooLarge error) or not UTF-8 (an InvalidData error); a workspace that sends only the lines asked of a file larger than MAX_BYTES, such as a remote one, checks only those for UTF-8.

fn write(&self, path: &Path, bytes: &[u8]) -> Result<()>

Replaces the file path with bytes in one step, creating its directory, keeping its permissions, and refusing a read-only file or anything but a regular file (see write_atomic).

fn remove(&self, path: &Path) -> Result<()>

Removes the file path; a directory is refused.

fn rename(&self, from: &Path, to: &Path) -> Result<()>

Moves the file from to to, creating to’s directory and replacing a file there.

fn canonical(&self, path: &Path) -> PathBuf

path made absolute, with the links of its longest existing part followed (the file’s own too, when it exists) and .. folded, so two spellings of one file come out alike. A footprint is made with it, which may be on a thread that must not wait: a remote workspace may answer from a cache, or fold .. only.

fn join(&self, base: &Path, path: &Path) -> PathBuf

path relative to base, as resolve joins them: base.join(path), so an absolute path stays as it is. A workspace whose paths can name another machine, such as Hosts, keeps such a path whole too.

fn spawn( &self, _: &Launcher, _: Option<&Path>, _: &OsStr, _: &[OsString], _: Spawn, ) -> Result<Process>

Starts program with args in dir (None: the launcher’s own directory) under launcher’s policy: its wrapper and variables.

fn read_files(&self, paths: &[PathBuf], limit: u64) -> Vec<Option<Vec<u8>>>

The whole content of each of paths that is a regular file of at most limit bytes, in order: None for any other path, and for one that could not be read. What a search reads; a workspace where each call costs a round trip, such as a remote one, reads them in one.

fn replace( &self, path: &Path, bytes: &[u8], limit: u64, ) -> Result<Result<Contents>>

writes bytes to path and says what the file held before, as read with limit reads it: a NotFound error when there was no file, the file’s own when it could not be read. What a tool that writes a file diffs against; a workspace where each call costs a round trip, such as a remote one, does both in one.

fn write_if( &self, path: &Path, bytes: &[u8], held: &ContentHash, ) -> Result<Option<Contents>>

writes bytes to the regular file path only while it holds the text whose content_hash is held: None when it did. Otherwise nothing is written and it says what the file holds instead, as read with a limit of MAX_FILE_BYTES reads it. What an edit made from text seen before writes with; a workspace where each call costs a round trip, such as a remote one, checks and writes in one.

fn watch( self: Arc<Self>, root: &Path, recursive: bool, listing: Listing, ) -> Result<Watch>

Watches root, a file or a directory (with recursive, every directory under it too), from now on: a batch of the paths created, changed or removed each time something changed, of the files files would list with listing. Dropping the Watch stops it. To miss nothing, list the files once after the watch has started.