Struct dowser::Dowser

pub struct Dowser { /* fields omitted */ }

Dowser is a very simple recursive file finder. Directories are read in parallel. Symlinks are followed. Hidden files and directories are read like any other. Matching files are canonicalized, deduped, and returned.

Filtering

Results can be filtered prior to being yielded with the use of either with_filter() — specifying a custom callback method — or with_regex() — to match against a (byte) pattern. (The latter requires the regexp crate feature be enabled.)

It is important to define the filter before adding any paths, because if those paths are files, they'll need to be filtered. Right? Right.

Filter callbacks should accept a &Path and return true to keep it, false to discard it. Ultimately, they get stored in the struct with the following type:

Box<dyn Fn(&Path) -> bool + 'static + Send + Sync>

Examples

use dowser::Dowser;
use std::os::unix::ffi::OsStrExt;
use std::path::PathBuf;

// Return all files under "/usr/share/man".
let res: Vec<PathBuf> = Dowser::default()
    .with_path("/usr/share/man")
    .build();

// Return only Gzipped files.
let res: Vec<PathBuf> = Dowser::default()
    .with_regex(r"(?i)[^/]+\.gz$")
    .with_path("/usr/share/man")
    .build();

// The same thing, done manually.
let res: Vec<PathBuf> = Dowser::default()
    .with_filter(|p: &Path| p.extension()
        .map_or(
            false,
            |e| e.as_bytes().eq_ignore_ascii_case(b"gz")
        )
    )
    .with_path("/usr/share/man")
    .build();

Implementations

impl Dowser

pub fn with_filter<F>(self, cb: F) -> Self where
    F: Fn(&Path) -> bool + 'static + Send + Sync, 

With Callback.

Define a custom filter callback to determine whether or not a given file path should be yielded. Return true to keep it, false to reject it.

Examples

use dowser::Dowser;
use std::path::PathBuf;

let files = Dowser::default()
    .with_filter(|p: &Path| { ... })
    .with_path("/my/dir")
    .build();

pub fn with_regex<R>(self, reg: R) -> Self where
    R: Borrow<str>, 

With a Regex Callback.

This is a convenience method for filtering files by regular expression. You supply only the expression, and Dowser will test it against the (full) path as a byte string, keeping any matches, rejecting the rest.

This method is only available when the regexp crate feature is enabled. This pulls down the regex crate to handle the details.

Speaking of, see here for syntax reference and other details.

Examples

use dowser::Dowser;

let files = Dowser::default()
    .with_regex(r"(?i).+\.jpe?g$")
    .with_path("/my/dir")
    .build();

pub fn with_paths<P, I>(self, paths: I) -> Self where
    P: AsRef<Path>,
    I: IntoIterator<Item = P>, 

With Paths.

Append files and/or directories to the finder. File paths will be checked against the filter callback (if any) and added straight to the results if they pass (i.e. immediately). Directories will be queued for later scanning (i.e. when you call Dowser::build).

Examples

use dowser::Dowser;

let files = Dowser::default()
    .with_paths(&["/my/dir"])
    .build();

pub fn with_path<P>(self, path: P) -> Self where
    P: AsRef<Path>, 

With Path.

Add a path to the finder. If the path is a file, it will be checked against the filter callback (if any) before being added to the results. If it is a directory, it will be queued for later scanning.

Examples

use dowser::Dowser;

let files = Dowser::default()
    .with_path("/my/dir")
    .build();

#[must_use]pub fn build(self) -> Vec<PathBuf>

Build!

Once everything is set up, call this method to consume the queue and collect the files into a Vec<PathBuf>.

Examples

use dowser::Dowser;

let files = Dowser::default()
    .with_path("/my/dir")
    .build();

Trait Implementations

impl Default for Dowser

fn default() -> Self

Returns the "default value" for a type.

impl<I, P> From<I> for Dowser where
    P: AsRef<Path>,
    I: IntoIterator<Item = P>, 

fn from(src: I) -> Self

From Paths.

This should only be used in cases where all paths are directories, or no file-filtering is going to take place. Otherwise, you should start with a Dowser::default, add your filter, then add the paths.