pub trait Tree {
// Required methods
fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError>;
fn read_unseen(
&self,
path: &RelPath,
max_bytes: u64,
seen: &dyn Fn(&FileId) -> bool,
) -> Result<Opened, TreeError>;
fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError>;
fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError>;
// Provided methods
fn read_bytes(
&self,
path: &RelPath,
max_bytes: u64,
) -> Result<Vec<u8>, TreeError> { ... }
fn identity(&self, path: &RelPath) -> Result<FileId, TreeError> { ... }
}Expand description
A read-only tree of UTF-8 text files below one root.
The trait is object-safe and has no Send or Sync bound: loading is
serial, and requiring Tree: Sync for a parallel load would be a breaking
change to Workspace::load. Paths are
RelPath values, so no call can name a place above the root by text. A
backend may still refuse a path that its contents lead out of.
Standalone backends accept first-party paths and refuse other authorities
with TreeError::WrongAuthority, rather than discarding their tags.
SourceTrees selects a backend by authority and deliberately passes it an
unqualified path, then scopes returned file identities to the selected source.
Required Methods§
Sourcefn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError>
fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError>
The text of the file at path.
§Errors
Returns TreeError::NotFound when nothing is there,
TreeError::OutsideRoot when the path leads out of the root,
TreeError::NotRegular when it is not a regular file,
TreeError::TooLarge when the file holds more than max_bytes
bytes, TreeError::NotUtf8 when it is not UTF-8, and
TreeError::SymlinkLoop or TreeError::Io when the operating
system fails.
Sourcefn read_unseen(
&self,
path: &RelPath,
max_bytes: u64,
seen: &dyn Fn(&FileId) -> bool,
) -> Result<Opened, TreeError>
fn read_unseen( &self, path: &RelPath, max_bytes: u64, seen: &dyn Fn(&FileId) -> bool, ) -> Result<Opened, TreeError>
Open the file at path once, take its identity from that open, and
read its text from the same open unless seen says the identity is
one the caller already holds.
Two paths that name one file, such as a path and the same path through a symlink to a directory, have equal identities, and two different files never do. Because the identity and the text come from one open, no change to the tree between two calls can pair one file’s identity with another file’s text.
§Errors
As Tree::read; a file that seen accepts is not read, so it is
never TreeError::TooLarge or TreeError::NotUtf8.
Sourcefn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError>
fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError>
The entries of the directory at path, sorted by name.
A symlink is listed as EntryKind::Symlink and is never followed:
listing a symlink itself is refused.
§Errors
Returns TreeError::NotFound when the directory is missing,
TreeError::NotRegular when path is not a real directory,
TreeError::OutsideRoot when it leads out of the root,
TreeError::NonUtf8Name when an entry name is not UTF-8 (the entry
is never dropped), and TreeError::SymlinkLoop or
TreeError::Io when the operating system fails.
Sourcefn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError>
fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError>
What is at path, or None when nothing is.
A final symlink is reported as EntryKind::Symlink and not followed.
§Errors
Returns TreeError::OutsideRoot when the directory holding path
leads out of the root, and TreeError::SymlinkLoop or
TreeError::Io when the operating system fails. A missing entry is
Ok(None), not an error.
Provided Methods§
Sourcefn read_bytes(
&self,
path: &RelPath,
max_bytes: u64,
) -> Result<Vec<u8>, TreeError>
fn read_bytes( &self, path: &RelPath, max_bytes: u64, ) -> Result<Vec<u8>, TreeError>
The exact bytes of the file at path, with no UTF-8 check, read
through the same verified handle as Tree::read.
A backend that cannot return the bytes of a file refuses with
TreeError::Io of kind std::io::ErrorKind::Unsupported; it never
converts through text.
§Errors
As Tree::read, except that TreeError::NotUtf8 cannot occur.
Sourcefn identity(&self, path: &RelPath) -> Result<FileId, TreeError>
fn identity(&self, path: &RelPath) -> Result<FileId, TreeError>
The identity of the file at path, without reading it: the identity
Tree::read_unseen gives when every identity counts as seen.
§Errors
As Tree::read, without TreeError::TooLarge and
TreeError::NotUtf8.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".