Struct WalkOptions

Source

pub struct WalkOptions { /* private fields */ }

Expand description

Structure encoding the desired walking options

§Example

use fs_walk;

let w = fs_walk::WalkOptions::new()
    // we want to walk only files
    .files()
    // we want files with .o extension
    .extension("o")
    .walk("./");

assert!(w.count() > 0);

Implementations§

Source §

impl WalkOptions

Source

pub fn new() -> Self

Create default walking options. The default behaviour is to return both files and directories.

§Example

use fs_walk;
use std::path::PathBuf;

let o = fs_walk::WalkOptions::new();

let paths: Vec<PathBuf> = o.walk("./").flatten().collect();

assert!(paths.iter().any(|p| p.is_dir()));
assert!(paths.iter().any(|p| p.is_file()));

Source

pub fn dirs(&mut self) -> &mut Self

Configure walking option to return only directories

§Example

use fs_walk::WalkOptions;

for p in WalkOptions::new().dirs().walk("./").flatten() {
    assert!(p.is_dir());
}

Source

pub fn files(&mut self) -> &mut Self

Configure walking option to return only files

§Example

use fs_walk::WalkOptions;

for p in WalkOptions::new().files().walk("./").flatten() {
    assert!(p.is_file());
}

Source

pub fn follow_symlink(&mut self) -> &mut Self

Configures the walker to follow symbolic links during traversal.

By default, the walker does not follow symbolic links. When this option is enabled, the walker will recursively traverse into directories pointed to by symbolic links, as if they were real directories.

§Symlink Loop Protection

The walker is protected against infinite loops caused by cyclic symlinks. It uses the canonical path and a hash set of visited directories (via BLAKE3 hashing) to ensure each directory is only visited once, even if it is linked multiple times.

§Example

use fs_walk::WalkOptions;

// Create a walker that follows symlinks
let mut options = WalkOptions::new();
options.follow_symlink();

// Now symlinks to directories will be traversed
for entry in options.walk("./").flatten() {
    println!("{:?}", entry);
}

§Safety

While the walker is protected against symlink loops, be cautious when enabling this option in untrusted directories, as it may still expose your program to other symlink-based attacks.

Source

pub fn max_depth(&mut self, depth: u64) -> &mut Self

Configure a maximum depth for the walker. If no depth is specified the walker will walk through all directories in a BFS way.

§Example

use fs_walk::WalkOptions;
use std::path::Path;

for p in WalkOptions::new().max_depth(0).walk("./").flatten() {
    assert_eq!(p.parent(), Some(Path::new(".")));
}

Source

pub fn extension<S: AsRef<str>>(&mut self, ext: S) -> &mut Self

Configure walker to return only files matching file extension. For any file, if Path::extension is not None it will be checked against ext. This function can be called several times to return files matching one of the desired extension.

See Path::extension for the correct way to specify ext.

§Example

use fs_walk;
use std::path::PathBuf;
use std::ffi::OsStr;

let wk = fs_walk::WalkOptions::new()
    .files()
    .extension("o")
    .extension("rs")
    .walk("./");

let paths: Vec<PathBuf> = wk.flatten().collect();

assert!(paths.iter().any(|p| p.extension() == Some(OsStr::new("o"))));
assert!(paths.iter().any(|p| p.extension() == Some(OsStr::new("rs"))));
assert!(!paths.iter().any(|p| p.extension() == Some(OsStr::new("toml"))));
assert!(!paths.iter().any(|p| p.extension() == Some(OsStr::new("lock"))));

Source

pub fn ends_with<S: AsRef<str>>(&mut self, pat: S) -> &mut Self

Configure walker to return files ending with pattern pat For any file, if Path::to_string_lossy ends with pattern pat it is going to be returned.

This method can be used to match path with double extensions (i.e. .txt.gz) without having to do manual pattern matching on walker’s output.

See str::ends_with for more detail about matching

§Example

use fs_walk;
use std::path::PathBuf;
use std::ffi::OsStr;

let wk = fs_walk::WalkOptions::new()
    .files()
    .extension("o")
    // we can put . here not in extension
    // can be used to match path with double extensions
    .ends_with(".rs")
    .walk("./");

let paths: Vec<PathBuf> = wk.flatten().collect();

assert!(paths.iter().any(|p| p.extension() == Some(OsStr::new("o"))));
assert!(paths.iter().any(|p| p.extension() == Some(OsStr::new("rs"))));
assert!(!paths.iter().any(|p| p.extension() == Some(OsStr::new("toml"))));
assert!(!paths.iter().any(|p| p.extension() == Some(OsStr::new("lock"))));

Source

pub fn name<S: AsRef<str>>(&mut self, name: S) -> &mut Self

Configure walker to return only paths with Path::file_name matching name

§Example

use fs_walk;
use std::path::PathBuf;
use std::ffi::OsStr;

let wk = fs_walk::WalkOptions::new()
    .name("lib.rs")
    .walk("./");

let paths: Vec<PathBuf> = wk.flatten().collect();

assert!(paths.iter().all(|p| p.file_name() == Some(OsStr::new("lib.rs"))));
assert!(paths.iter().all(|p| p.is_file()));