Enum FsTree

pub enum FsTree {
    Regular,
    Directory(TrieMap),
    Symlink(PathBuf),
}

A filesystem tree recursive type.

Iterators:

See the iterator module documentation.

Variants

Regular

A regular file.

Directory(TrieMap)

A directory, might have children FsTrees inside.

Symlink(PathBuf)

Symbolic link, and it’s target path (the link might be broken).

Implementations

impl FsTree

pub fn new_dir() -> Self

Creates an empty directory node.

This is an alias to FsTree::Directory(Default::default()).

use fs_tree::{FsTree, TrieMap};

let result = FsTree::new_dir();
let expected = FsTree::Directory(TrieMap::new());

assert_eq!(result, expected);

pub fn len_leafs(&self) -> usize

Calculate the length by counting the leafs.

pub fn len_all(&self) -> usize

Calculate the length by counting all tree nodes, including the root.

pub fn read_at(path: impl AsRef<Path>) -> Result<Self>

Construct a FsTree by reading from path, follows symlinks.

If you want symlink-awareness, check symlink_read_at.

Errors:

• If any IO error occurs.
• If any file has an unexpected file type.

pub fn symlink_read_at(path: impl AsRef<Path>) -> Result<Self>

Construct a FsTree by reading from path.

If you don’t want symlink-awareness, check read_at.

Errors:

• If any IO error occurs.
• If any file has an unexpected file type.

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

Construct a structural copy of this FsTree by reading files at the given path.

In other words, the returned tree is formed of all paths in self that are also found in the given path (intersection), missing files are skipped and types might differ.

This function can be useful if you need to load a subtree from a huge folder and cannot afford to load the whole folder, or if you just want to filter out every node outside of the specified structure.

This function will make at maximum self.len() syscalls.

If you don’t want symlink-awareness, check FsTree::symlink_read_structure_at.

Examples:

use fs_tree::FsTree;

fn dynamically_load_structure() -> FsTree {
    ...
}

let structure = dynamically_load_structure();

let new_tree = structure.read_structure_at("path_here").unwrap();

// It is guaranteed that every path in here is present in `structure`
for path in new_tree.paths() {
    assert!(structure.get(path).is_some());
}

Errors:

• If an IO error happens, except io::ErrorKind::NotFound

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

Construct a structural copy of this FsTree by reading files at the given path.

In other words, the returned tree is formed of all paths in self that are also found in the given path (intersection), missing files are skipped and types might differ.

This function can be useful if you need to load a subtree from a huge folder and cannot afford to load the whole folder, or if you just want to filter out every node outside of the specified structure.

This function will make at maximum self.len() syscalls.

If you don’t want symlink-awareness, check FsTree::read_structure_at.

Examples:

use fs_tree::FsTree;

fn dynamically_load_structure() -> FsTree {
    ...
}

let structure = dynamically_load_structure();

let new_tree = structure.symlink_read_structure_at("path_here").unwrap();

// It is guaranteed that every path in here is present in `structure`
for path in new_tree.paths() {
    assert!(structure.get(path).is_some());
}

Errors:

• If an IO error happens, except io::ErrorKind::NotFound

pub fn from_path_text(path: impl AsRef<Path>) -> Self

Construct a FsTree from path pieces.

Returns None if the input is empty.

Returned value can correspond to a regular file or directory, but not a symlink.

Warning

The last piece is always a file, so inputs ending with /, like Path::new("example/") are NOT parsed as directories.

For my usage cases it’s OK, but open an issue if you think otherwise 👍.

Examples:

use fs_tree::{FsTree, tree};

let result = FsTree::from_path_text("a/b/c");

let expected = tree! {
    a: {
        b: {
            c
        }
    }
};

// The expected tree
assert_eq!(result, expected);

// Nodes are nested
assert!(result.is_dir());
assert!(result["a"].is_dir());
assert!(result["a"]["b"].is_dir());
assert!(result["a"]["b"]["c"].is_regular());

pub fn from_path_pieces<I, P>(path_iter: I) -> Self

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

Generic iterator version of from_path_text.

pub fn iter(&self) -> Iter<'_>

Creates an iterator that yields (&FsTree, PathBuf).

See iterator docs at the iter module documentation.

pub fn nodes(&self) -> NodesIter<'_>

Creates an iterator that yields &FsTree.

See iterator docs at the iter module documentation.

pub fn paths(&self) -> PathsIter<'_>

Creates an iterator that yields PathBuf.

See iterator docs at the iter module documentation.

pub fn is_same_type_as(&self, other: &Self) -> bool

Returns true if self type matches other type.

pub fn try_exists(&mut self) -> Result<bool>

Returns Ok(true) if all nodes exist in the filesystem.

Errors:

Similar to how Path::try_exists works, this function returns false if any IO error occurred when checking std::fs::symlink_metadata (except io::ErrorKind::NotFound).

pub fn merge(self, other: Self) -> Self

Merge two trees.

When conflicts happen, entries from self are kept, and the other’s are discarded.

pub fn conflicts_with(&self, other: &Self) -> bool

Checks for conflicts in case the two trees would be merged.

Also see Self::merge.

pub fn children(&self) -> Option<&TrieMap>

Reference to children if self.is_directory().

pub fn children_mut(&mut self) -> Option<&mut TrieMap>

Mutable reference to children if self.is_directory().

pub fn target(&self) -> Option<&Path>

Reference to target path, if self.is_symlink().

pub fn target_mut(&mut self) -> Option<&mut PathBuf>

Mutable reference to target path, if self.is_symlink().

pub fn is_leaf(&self) -> bool

Returns true if self is a leaf node.

A leaf node might be of any type, including directory, however, a non-leaf node is always a directory.

pub fn variant_str(&self) -> &'static str

The variant string, useful for showing to user.

pub fn is_regular(&self) -> bool

Returns true if self matches the FsTree::Regular variant.

pub fn is_dir(&self) -> bool

Returns true if self matches the FsTree::Directory variant.

pub fn is_symlink(&self) -> bool

Returns true if self matches the FsTree::Symlink variant.

pub fn write_at(&self, folder: impl AsRef<Path>) -> Result<()>

Write the tree structure in the path.

Errors:

• If provided folder doesn’t exist, or is not a directory.
• If any other IO error occurs.

pub fn get(&self, path: impl AsRef<Path>) -> Option<&Self>

Returns a reference to the node at the path, if any.

Errors:

• Returns None if there is no node at the given path.

Examples:

use fs_tree::FsTree;

let root = FsTree::from_path_text("a/b/c");

// Indexing is relative from `root`, so `root` cannot be indexed.
assert_eq!(root, FsTree::from_path_text("a/b/c"));
assert_eq!(root["a"], FsTree::from_path_text("b/c"));
assert_eq!(root["a/b"], FsTree::from_path_text("c"));
assert_eq!(root["a"]["b"], FsTree::from_path_text("c"));
assert_eq!(root["a/b/c"], FsTree::Regular);
assert_eq!(root["a/b"]["c"], FsTree::Regular);
assert_eq!(root["a"]["b/c"], FsTree::Regular);
assert_eq!(root["a"]["b"]["c"], FsTree::Regular);

pub fn get_mut(&mut self, path: impl AsRef<Path>) -> Option<&mut Self>

Returns a mutable reference to the node at the path, if any.

This is the mutable version of FsTree::get.

pub fn insert(&mut self, path: impl AsRef<Path>, node: Self)

Inserts a node at the given path.

Panics:

• If there are no directories up to the path node in order to insert it.
• If path is empty.

Trait Implementations

impl Clone for FsTree

fn clone(&self) -> FsTree

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FsTree

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

Formats the value using the given formatter.

impl Hash for FsTree

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<P> Index<P> for FsTree

where P: AsRef<Path>,

type Output = FsTree

The returned type after indexing.

fn index(&self, path: P) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Ord for FsTree

fn cmp(&self, other: &FsTree) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for FsTree

fn eq(&self, other: &FsTree) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for FsTree

fn partial_cmp(&self, other: &FsTree) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for FsTree

impl StructuralPartialEq for FsTree