Trait wax::walk::FileIterator

pub trait FileIterator: HierarchicalIterator<Feed = (Result<Self::Entry, WalkError>, TreeResidue<Self::Residue>)> + Iterator<Item = Result<Self::Entry, WalkError>> {
    type Entry: Entry;
    type Residue: Entry + From<Self::Entry>;

    // Provided methods
    fn filter_entry<F>(self, f: F) -> FilterEntry<Self, F> 
       where Self: Sized,
             F: FnMut(&dyn Entry) -> Option<EntryResidue> { ... }
    fn not<'t, I>(self, patterns: I) -> Result<Not<Self>, BuildError>
       where Self: Sized,
             I: IntoIterator,
             I::Item: Pattern<'t> { ... }
}

Available on crate feature walk only.

An Iterator over files in a directory tree.

This iterator is aware of its hierarchical structure and can cancel traversal into directories that are discarded by filter combinators to avoid unnecessary work. The contents of discarded directories are not read from the file system.

The iterators constructed by PathExt::walk, Glob::walk, etc. implement this trait.

Required Associated Types

type Entry: Entry

The file entry type yielded by the iterator.

FileIterators implement Iterator where the associated Item type is Result<Self::Entry, WalkError>.

type Residue: Entry + From<Self::Entry>

Provided Methods

fn filter_entry<F>(self, f: F) -> FilterEntry<Self, F> where Self: Sized, F: FnMut(&dyn Entry) -> Option<EntryResidue>,

Filters file entries and controls the traversal of the directory tree.

This function constructs a combinator that filters file entries and furthermore specifies how iteration proceeds to traverse the directory tree. It accepts a function that, when discarding an entry, returns an EntryResidue. If an entry refers to a directory and the filtering function returns EntryResidue::Tree, then iteration does not descend into that directory and the tree is not read from the file system.

The filtering function is called even when a composing filter has already discarded a file entry. This allows filtering combinators to observe previously filtered entries and potentially discard a directory tree regardless of how they are composed. Filtering is monotonic, meaning that filtered entries can only progress forward from unfiltered None to filtered file Some(EntryResidue::File) to filtered tree Some(EntryResidue::Tree). An entry cannot be “unfiltered” and if a subsequent combinator specifies a lesser filter, then it has no effect.

Prefer this combinator over functions like Iterator::filter when discarded directories need not be read.

Examples

The FilterEntry combinator can apply arbitrary and non-nominal filtering that avoids unnecessary directory reads. The following example filters out hidden files on Unix and Windows. On Unix, hidden files are filtered out nominally via not. On Windows, filter_entry instead detects the hidden attribute. In both cases, the combinator does not read conventionally hidden directory trees.

use wax::walk::{Entry, FileIterator};
use wax::Glob;

let glob = Glob::new("**/*.(?i){jpg,jpeg}").unwrap();
let walk = glob.walk("./Pictures");
// Filter out nominally hidden files on Unix. Like `filter_entry`, `not` does not perform
// unnecessary reads of directory trees.
#[cfg(unix)]
let walk = walk.not(["**/.*/**"]).unwrap();
// Filter out files with the hidden attribute on Windows.
#[cfg(windows)]
let walk = walk.filter_entry(|entry| {
    use std::os::windows::fs::MetadataExt as _;
    use wax::walk::EntryResidue;

    const ATTRIBUTE_HIDDEN: u32 = 0x2;

    let attributes = entry.metadata().unwrap().file_attributes();
    if (attributes & ATTRIBUTE_HIDDEN) == ATTRIBUTE_HIDDEN {
        // Do not read hidden directory trees.
        Some(EntryResidue::Tree)
    }
    else {
        None
    }
});
for entry in walk {
    let entry = entry.unwrap();
    println!("JPEG: {:?}", entry.path());
}

fn not<'t, I>(self, patterns: I) -> Result<Not<Self>, BuildError>where Self: Sized, I: IntoIterator, I::Item: Pattern<'t>,

Filters file entries against negated glob expressions.

This function constructs a combinator that discards files with paths that match any of the given glob expressions. When matching a Glob against a directory tree, this allows for broad negations that cannot be achieved using a positive glob expression alone.

The combinator does not read directory trees from the file system when a directory matches an exhaustive glob expression such as **/private/** or hidden/<<?>/>*.

Prefer this combinator over matching each file entry against Programs, since it avoids potentially large and unnecessary reads.

Errors

Returns an error if any of the inputs fail to build. If the inputs are a compiled Program type such as Glob, then this only occurs if the compiled program is too large (i.e., there are too many component patterns).

Examples

Because glob expressions do not support general negations, it is sometimes impossible to express patterns that deny particular paths. In such cases, not can be used to apply additional patterns as a filter.

use wax::walk::FileIterator;
use wax::Glob;

// Find image files, but not if they are beneath a directory with a name that suggests that
// they are private.
let glob = Glob::new("**/*.(?i){jpg,jpeg,png}").unwrap();
for entry in glob.walk(".").not(["**/(?i)<.:0,1>private/**"]).unwrap() {
    let entry = entry.unwrap();
    // ...
}

Implementors

impl<T, R, I> FileIterator for Iwhere T: Entry, R: Entry + From<T>, I: HierarchicalIterator<Feed = (Result<T, WalkError>, TreeResidue<R>)> + Iterator<Item = Result<T, WalkError>>,

type Entry = T

type Residue = R