1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629
#![warn(missing_docs)]
//! Filesystem trie-like tree structure for commons operations.
//!
//! Given a path, you can load a `FileTree` which might represent a regular file, directory, or symlink.
//!
//! # Features:
//!
//! - Aware of regular files, directories and symlinks.
//! - Read from your filesystem.
//! - Merge trees.
//! - Get the difference of two trees.
//! - Macros for creating trees more easily (WIP).
//! - Tree iteration.
//! - Supports useful tree filters.
//! - You can perform operations on the iteration results (e.g. read each file and link them).
//!
//! # When not to use:
//!
//! - If you just want to iterate a directory, use [`WalkDir`] instead.
//! - If you want to use a text trie directly, use other crate too.
//!
//! # When to use:
//!
//! - You need to easily load a file type-aware trie from your filesystem and compare with other tries.
//!
//! ---
//!
//! [`WalkDir`]: https://docs.rs/walkdir
// TODO (so that I don't forget):
// - FileType -> mode_t
// - Change layout to a more trie-like tree, where the root may contain several subtrees.
// - This helps with possible node duplication, which is bad.
// - Also helps with complexity of queries.
// - re-add the extra generic field
// - re-test Pathsiter
// - enable all tests in rustdocs
// - improve fmt::Debug on File and FileType recursive display
/// `Result` and `Error` types.
pub mod error;
/// FsTree iterators.
pub mod iter;
/// Exposed functions that are used internally by this crate
pub mod util;
// /// Macros for creating `FileTree` structure.
// pub mod macros;
use std::{
collections::HashMap,
env, fs, mem,
path::{Path, PathBuf},
};
use file_type_enum::FileType as FileTypeEnum;
pub use self::{
error::*,
iter::{FilesIter, PathsIter},
};
/// A filesystem tree recursive type.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct FileTree {
/// The filename of this file.
pub path: PathBuf,
/// The filetype of this file.
pub file_type: FileTreeType,
}
/// A filesystem tree recursive enum.
///
/// This enum has a variant for the following file types:
/// 1. `FileTreeType::Regular` - A regular file.
/// 2. `FileTreeType::Directory` - A folder with a (possible empty) list of children.
/// 3. `FileTreeType::Symlink` - A symbolic link that points to another path.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum FileTreeType {
/// A regular file.
Regular,
/// A directory, might have children `FileTree`s inside.
Directory(Vec<FileTree>),
/// Symbolic link, and it's target path.
///
/// The link might be broken, it's not guaranteed that a symlink points to a valid path.
Symlink(PathBuf),
}
impl FileTreeType {
/// Checks if the FileTreeType is the same type as other.
pub fn is_same_type_as(&self, other: &Self) -> bool {
mem::discriminant(self) == mem::discriminant(other)
}
/// Shorthand for `file.file_type.is_regular()`
pub fn is_regular(&self) -> bool {
matches!(self, Self::Regular)
}
/// Shorthand for `file.file_type.is_dir()`
pub fn is_dir(&self) -> bool {
matches!(self, Self::Directory(_))
}
/// Shorthand for `file.file_type.is_symlink()`
pub fn is_symlink(&self) -> bool {
matches!(self, Self::Symlink(_))
}
}
impl FileTree {
/// Creates a `FileTree::Regular` from arguments.
pub fn new_regular(path: impl AsRef<Path>) -> Self {
Self {
path: path.as_ref().to_owned(),
file_type: FileTreeType::Regular,
}
}
// /// Creates a `FileTree::Regular` with default arguments.
// pub fn regular_default() -> Self {
// Self::new_regular_with_extra(path)
// }
/// Creates a `FileTree::Directory` from arguments.
pub fn new_directory(path: impl AsRef<Path>, children: Vec<Self>) -> Self {
Self {
path: path.as_ref().to_path_buf(),
file_type: FileTreeType::Directory(children),
}
}
// /// Creates a `FileTree::Directory` with default arguments.
// pub fn directory_default() -> Self {
// Self::new_directory(PATH_DEFAULT, Vec::default())
// }
/// Creates a `FileTree::Symlink` from arguments.
pub fn new_symlink(path: impl AsRef<Path>, target_path: impl AsRef<Path>) -> Self {
let path = path.as_ref().to_path_buf();
let target_path = target_path.as_ref().to_path_buf();
Self {
path,
file_type: FileTreeType::Symlink(target_path),
}
}
// /// Creates a `FileTree::Symlink` with default arguments.
// pub fn symlink_default() -> Self {
// Self::new_symlink(PATH_DEFAULT, PATH_DEFAULT)
// }
// Private implementation
fn __collect_from_directory(path: &Path, follow_symlinks: bool) -> Result<Vec<Self>> {
if !path.exists() {
return Err(Error::NotFoundError(path.to_path_buf()));
} else if !FileTypeEnum::from_path(path)?.is_directory() {
return Err(Error::NotADirectoryError(path.to_path_buf()));
}
let dirs = fs::read_dir(path)?;
let mut children = vec![];
for entry in dirs {
let entry = entry?;
let file = Self::__from_path(&entry.path(), follow_symlinks)?;
children.push(file);
}
Ok(children)
}
/// Collects a `Vec` of `FileTree` from `path` that is a directory.
pub fn collect_from_directory(path: impl AsRef<Path>) -> Result<Vec<Self>> {
Self::__collect_from_directory(path.as_ref(), true)
}
/// Collects a `Vec` of `FileTree` from `path` that is a directory, entries can be symlinks.
pub fn collect_from_directory_symlink(path: impl AsRef<Path>) -> Result<Vec<Self>> {
Self::__collect_from_directory(path.as_ref(), false)
}
// Private implementation
fn __collect_from_directory_cd(path: &Path, follow_symlinks: bool) -> Result<Vec<Self>> {
let previous_path = env::current_dir()?;
debug_assert!(path.is_absolute());
env::set_current_dir(path)?;
let result = Self::__collect_from_directory(Path::new("."), follow_symlinks);
env::set_current_dir(previous_path)?;
result
}
/// Collects a `Vec` of `FileTree` from `path` that is a directory.
pub fn collect_from_directory_cd(path: impl AsRef<Path>) -> Result<Vec<Self>> {
Self::__collect_from_directory_cd(path.as_ref(), false)
}
/// Collects a `Vec` of `FileTree` from `path` that is a directory, entries can be symlinks.
pub fn collect_from_directory_symlink_cd(path: impl AsRef<Path>) -> Result<Vec<Self>> {
Self::__collect_from_directory_cd(path.as_ref(), false)
}
// Internal implementation of `from_path` and `from_path_symlink`
fn __from_path(path: &Path, follow_symlinks: bool) -> Result<Self> {
let get_file_type = if follow_symlinks {
FileTypeEnum::from_path
} else {
FileTypeEnum::from_symlink_path
};
match get_file_type(path)? {
FileTypeEnum::Regular => Ok(Self::new_regular(path)),
FileTypeEnum::Directory => {
let children = Self::__collect_from_directory(path, follow_symlinks)?;
Ok(Self::new_directory(path, children))
},
FileTypeEnum::Symlink => {
let target_path = util::symlink_follow(path)?;
Ok(Self::new_symlink(path, target_path))
},
other_type => Err(Error::UnexpectedFileTypeError(
other_type,
path.to_path_buf(),
)),
}
}
/// Builds a `FileTree` from `path`, follows symlinks.
///
/// Similar to `from_path_symlink`.
///
/// If file at `path` is a regular file, will return a `FileTree::Regular`.
/// If file at `path` is a directory file, `FileTree::Directory` (with .children).
///
/// # Errors:
/// - If `Io::Error` from `fs::metadata(path)`
/// - If it is a directory, and `Io::Error` from `fs::read_dir(path)` iterator usage
/// - If [unexpected file type] at `path`
///
/// This function traverses symlinks until final destination, and then reads it, so it can never
/// return `Ok(FileTree::Symlink { .. ]})`, if you wish otherwise, use
/// `FileTree::from_path_symlink` instead.
///
/// [unexpected file type]: docs.rs/file_type_enum
pub fn from_path(path: impl AsRef<Path>) -> Result<Self> {
Self::__from_path(path.as_ref(), true)
}
/// Builds a `FileTree` from `path`, follows symlinks.
///
/// Similar to `from_path_symlink`.
///
/// If file at `path` is a regular file, will return a `FileTree::Regular`.
/// If file at `path` is a directory file, `FileTree::Directory` (with `children` field).
/// If file at `path` is a symlink file, `FileTree::Symlink` (with `target_path` field).
///
/// # Errors:
/// - If `Io::Error` from `fs::metadata(path)`
/// - If it is a directory, and `Io::Error` from `fs::read_dir(path)` iterator usage
/// - If it is a symlink, and `Io::Error` from `fs::read_link(path)`
/// - If [unexpected file type] at `path`
///
/// If you wish to traverse symlinks until final destination, instead, use
/// `FileTree::from_path`.
///
/// [unexpected file type]: docs.rs/file_type_enum
pub fn from_path_symlink(path: impl AsRef<Path>) -> Result<Self> {
Self::__from_path(path.as_ref(), false)
}
// Internal
fn ___from_path_cd(path: &Path, follow_symlinks: bool) -> Result<Self> {
let previous_path = env::current_dir()?;
debug_assert!(path.is_absolute());
env::set_current_dir(path)?;
let result = Self::__from_path(Path::new("."), follow_symlinks);
env::set_current_dir(previous_path)?;
result
}
/// `cd` into path, run `from_path`, and come back.
///
/// TODO explain here why this is useful
pub fn from_path_cd(path: impl AsRef<Path>) -> Result<Self> {
Self::___from_path_cd(path.as_ref(), true)
}
/// `cd` into path, run `from_path_symlink`, and come back.
///
/// TODO explain here why this is useful
pub fn from_cd_symlink_path(path: impl AsRef<Path>) -> Result<Self> {
Self::___from_path_cd(path.as_ref(), false)
}
/// Splits a `Path` components into a `FileTree`.
///
/// Returns `None` if the string is empty.
///
/// Can only build Regular and Directory, not symlink.
///
/// Example:
///
/// ```
/// use fs_tree::FileTree;
///
/// let result = FileTree::from_path_text(".config/i3/file");
///
/// let expected = {
/// FileTree::new_directory(
/// ".config/",
/// vec![FileTree::new_directory(
/// ".config/i3/",
/// vec![FileTree::new_regular(".config/i3/file")],
/// )],
/// )
/// };
///
/// assert_eq!(result, Some(expected));
/// ```
pub fn from_path_text(path: impl AsRef<Path>) -> Option<Self> {
Self::from_path_pieces(path.as_ref().iter())
}
/// More generic version of `FileTree::from_path_text`.
pub fn from_path_pieces<I, P>(path_iter: I) -> Option<Self>
where
I: IntoIterator<Item = P>,
P: AsRef<Path>,
{
let mut path_iter = path_iter.into_iter();
let first_piece = path_iter.next()?;
let mut tree = Self::from_path_text_recursive_impl(first_piece, path_iter);
tree.make_paths_relative();
Some(tree)
}
fn from_path_text_recursive_impl<I, P>(piece: P, mut path_iter: I) -> Self
where
I: Iterator<Item = P>,
P: AsRef<Path>,
{
match path_iter.next() {
Some(next) => FileTree::new_directory(
piece.as_ref(),
vec![Self::from_path_text_recursive_impl(next, path_iter)],
),
None => FileTree::new_regular(piece),
}
}
/// Iterator of all `FileTree`s in the structure
pub fn files(&self) -> FilesIter {
FilesIter::new(self)
}
/// Shorthand for `self.files().paths()`, see link to [`.paths()`] method
///
/// [`.paths()`]: super::iter::FilesIter::paths
pub fn paths(&self) -> PathsIter {
self.files().paths()
}
/// Fix relative paths from each node piece.
///
/// If you manually build a structure like:
///
/// ```plain
/// "a": [
/// "b": [
/// "c",
/// ]
/// ]
/// ```
///
/// Using the create methods, then you need to run this function to make them relative paths.
///
/// ```plain
/// "a": [
/// "a/b": [
/// "a/b/c",
/// ]
/// ]
/// ```
///
/// Then, you can access any of the files only by looking at their path.
pub fn make_paths_relative(&mut self) {
// If this is a directory, update the path of all children
if let FileTreeType::Directory(children) = &mut self.file_type {
for child in children.iter_mut() {
// Update child's path
*child.path_mut() = self.path.join(child.path());
// Update target if it's a symlink
if let Some(target) = child.target_mut() {
*target = self.path.join(&target);
}
child.make_paths_relative();
}
}
}
/// Makes all paths in the tree absolute.
///
/// # Errors:
///
/// In case `std::fs::canonicalize` fails at any path, this function will stop and return an
/// IoError, leave the tree in a mixed state in terms of canonical paths.
pub fn make_paths_absolute(&mut self) -> Result<()> {
*self.path_mut() = self.path().canonicalize()?;
if let Some(children) = self.children_mut() {
for child in children.iter_mut() {
Self::make_paths_absolute(child)?;
}
}
Ok(())
}
/// Merge this tree with other `FileTree`.
///
/// This function is currently experimental and likely to change in future versions.
///
/// # Errors:
///
/// This errs if:
///
/// - The trees have different roots and thus cannot be merged.
/// - There are file conflicts.
pub fn merge(self, other: Self) -> Option<Self> {
if self.path() != other.path() {
return None;
}
let path = self.path;
match (self.file_type, other.file_type) {
(FileTreeType::Directory(left_children), FileTreeType::Directory(right_children)) => {
// TODO: Don't remake a trie here, we can use the trees directly
// this todo needs to be solved after migrating to a proper trie
let mut left_map: HashMap<PathBuf, FileTree> = left_children
.into_iter()
.map(|child| (child.path.clone(), child))
.collect();
let mut result_vec = vec![];
for child in right_children {
// If there is another one with the same path, merge them
match left_map.remove(child.path()) {
None => result_vec.push(child),
Some(left_equivalent) => {
if !child.has_same_type_as(&left_equivalent) {
return None;
} else if child.is_dir() && left_equivalent.is_dir() {
result_vec.push(left_equivalent.merge(child).unwrap());
} else {
result_vec.push(left_equivalent);
result_vec.push(child);
}
},
}
}
result_vec.extend(left_map.into_values());
Some(Self::new_directory(path, result_vec))
},
_ => None,
}
}
/// Reference to children vec if self.is_directory().
pub fn children(&self) -> Option<&Vec<Self>> {
match &self.file_type {
FileTreeType::Directory(children) => Some(children),
_ => None,
}
}
/// Reference to children vec if self.is_directory(), mutable.
pub fn children_mut(&mut self) -> Option<&mut Vec<Self>> {
match &mut self.file_type {
FileTreeType::Directory(children) => Some(children),
_ => None,
}
}
/// Reference to target_path if self.is_symlink().
pub fn target(&self) -> Option<&PathBuf> {
match &self.file_type {
FileTreeType::Symlink(target_path) => Some(target_path),
_ => None,
}
}
/// Reference to target_path if self.is_symlink(), mutable.
pub fn target_mut(&mut self) -> Option<&mut PathBuf> {
match &mut self.file_type {
FileTreeType::Symlink(target_path) => Some(target_path),
_ => None,
}
}
/// Apply a closure for each direct child of this FileTree.
///
/// Only 1 level deep.
pub fn apply_to_children0(&mut self, f: impl FnMut(&mut Self)) {
if let Some(children) = self.children_mut() {
children.iter_mut().for_each(f);
}
}
/// Apply a closure to all direct and indirect descendants inside of this structure.
///
/// Calls recursively for all levels.
pub fn apply_to_all_children1(&mut self, f: impl FnMut(&mut Self) + Copy) {
if let Some(children) = self.children_mut() {
children
.iter_mut()
.for_each(|x| x.apply_to_all_children1(f));
children.iter_mut().for_each(f);
}
}
/// Apply a closure to all direct and indirect descendants inside, also includes root.
///
/// Calls recursively for all levels.
pub fn apply_to_all(&mut self, mut f: impl FnMut(&mut Self) + Copy) {
f(self);
if let Some(children) = self.children_mut() {
for child in children.iter_mut() {
child.apply_to_all(f);
}
}
}
/// Gets a reference to the file path to this node.
pub fn path(&self) -> &PathBuf {
&self.path
}
/// Gets a mutable reference to the file path to this node.
pub fn path_mut(&mut self) -> &mut PathBuf {
&mut self.path
}
/// Shorthand for `file.file_type.is_regular()`
pub fn is_regular(&self) -> bool {
self.file_type.is_regular()
}
/// Shorthand for `file.file_type.is_dir()`
pub fn is_dir(&self) -> bool {
self.file_type.is_dir()
}
/// Shorthand for `file.file_type.is_symlink()`
pub fn is_symlink(&self) -> bool {
self.file_type.is_symlink()
}
/// Turn this node of the tree into a regular file.
///
/// Beware the possible recursive drop of nested nodes if this node was a directory.
pub fn to_regular(&mut self) {
self.file_type = FileTreeType::Regular;
}
/// Turn this node of the tree into a directory.
///
/// Beware the possible recursive drop of nested nodes if this node was a directory.
pub fn to_directory(&mut self, children: Vec<Self>) {
self.file_type = FileTreeType::Directory(children);
}
/// Turn this node of the tree into a symlink.
///
/// Beware the possible recursive drop of nested nodes if this node was a directory.
pub fn to_symlink(&mut self, target_path: impl AsRef<Path>) {
self.file_type = FileTreeType::Symlink(target_path.as_ref().to_owned());
}
/// Checks if the FileTree file type is the same as other FileTree.
pub fn has_same_type_as(&self, other: &FileTree) -> bool {
self.file_type.is_same_type_as(&other.file_type)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_merge() {
let left = FileTree::from_path_text(".config/i3/file").unwrap();
let right = FileTree::from_path_text(".config/i3/folder/file").unwrap();
let result = left.merge(right);
let expected = {
FileTree::new_directory(
".config",
vec![FileTree::new_directory(
".config/i3",
vec![
FileTree::new_directory(
".config/i3/folder",
vec![FileTree::new_regular(".config/i3/folder/file")],
),
FileTree::new_regular(".config/i3/file"),
],
)],
)
};
assert_eq!(result, Some(expected));
}
#[test]
fn test_partial_eq_fails() {
let left = FileTree::from_path_text(".config/i3/a").unwrap();
let right = FileTree::from_path_text(".config/i3/b").unwrap();
assert_ne!(left, right);
}
}