Skip to main content

Tree

Trait Tree 

Source
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§

Source

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.

Source

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.

Source

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.

Source

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§

Source

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.

Source

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".

Implementors§