13 unstable releases (4 breaking)

0.5.5 Oct 3, 2023
0.5.4 Oct 3, 2023
0.4.0 Sep 27, 2023
0.3.0 Sep 22, 2023
0.1.1 Feb 14, 2020

#182 in Filesystem

Download history 7/week @ 2023-11-02 26/week @ 2023-11-09 15/week @ 2023-11-16 29/week @ 2023-11-23 52/week @ 2023-11-30 4/week @ 2023-12-07 20/week @ 2023-12-14 48/week @ 2023-12-21 2/week @ 2023-12-28 4/week @ 2024-01-04 5/week @ 2024-01-11 8/week @ 2024-01-18 27/week @ 2024-01-25 80/week @ 2024-02-01 122/week @ 2024-02-08 204/week @ 2024-02-15

437 downloads per month

MIT license

61KB
948 lines

fs-tree

FsTree is a path Trie with an API focused on filesystem operations.

Clarifications:

  1. Unix only.
  2. This crate was transfered after 0.1.3, and changed its purpose.
  3. This crate refers to "filesystem tree" as the result you get from recursively traversing files:
    • If you try traversing a single file, you get a single node.
    • If you try traversing a directories, you might get a large subtree (of nodes).
    • This is agnostic to the underlying filesystem (nothing to do with ext4 or btrfs).
  4. Check Trie if you both haven't met yet.

Tree Layout:

A FsTree is a node with three possible file types:

use std::{collections::BTreeMap, path::PathBuf};

pub enum FsTree {
    Regular,
    Directory(TrieMap), // Recursive part
    Symlink(PathBuf),
}
//                                     ↓↓
pub type TrieMap = BTreeMap<PathBuf, FsTree>; // Recursive part

The root of the FsTree is unnamed (no filename/path), the "edges" to children are the relative paths.

Pitfall warning:

Like std functions, functions in this crate follow symlinks (and symlink chains), so you'll never get a FsTree::Symlink(_) in your tree! If you want symlink-awareness, use the function version with the symlink prefix (FsTree::read_at vs FsTree::symlink_read_at).

Ways to construct a FsTree:

  1. Read node/tree from path. (FsTree::symlink_read_at)
  2. Declare a FsTree literal. (tree!)
  3. Insert each node in an empty folder. (FsTree::new_dir + FsTree::insert)
  4. Parse from path text segments. (FsTree::from_path_text)

What you can do with a FsTree:

  1. Traverse, query, and modify it.
  2. Merge with another tree. (FsTree::try_merge)
  3. Write it to disk. (FsTree::write_at)
  4. Try loading a structural copy of it from a path. (FsTree::read_copy_at)
  5. (TODO) Compare with another FsTree, generating a DiffTree.
  6. (TODO) Add entry API.

Iterators:

See docs in the iter module.

Alternatives:

  • Crate walkdir - Better if you just need to iterate on filesystem trees.
  • Crate file_type_enum - If you want a shallow type enum.
  • Crate build-fs-tree - If you need to create a filesystem tree from a YAML file.

Dependencies

~105KB