Crate capturing_glob

Support for matching file paths against Unix shell style patterns.

The glob and glob_with functions allow querying the filesystem for all files that match a particular pattern (similar to the libc glob function). The methods on the Pattern type provide functionality for checking if individual paths match a particular pattern (similar to the libc fnmatch function).

For consistency across platforms, and for Windows support, this module is implemented entirely in Rust rather than deferring to the libc glob/fnmatch functions.

Examples

To print all jpg files in /media/ and all of its subdirectories, extracting stem and a directory name while matching.

use capturing_glob::glob;

for entry in glob("/media/(**/*).jpg").expect("Failed to read glob pattern") {
    match entry {
        Ok(entry) => {
            println!("{:?} -> {:?}", entry.path().display(),
                entry.group(1).unwrap());
        }
        Err(e) => eprintln!("{:?}", e),
    }
}

To print all files containing the letter “a”, case insensitive, in a local directory relative to the current working directory. This ignores errors instead of printing them.

use capturing_glob::glob_with;
use capturing_glob::MatchOptions;

let options = MatchOptions {
    case_sensitive: false,
    require_literal_separator: false,
    require_literal_leading_dot: false,
};
for entry in glob_with("local/*a*", &options).unwrap() {
    if let Ok(entry) = entry {
        println!("{:?}", entry.path().display())
    }
}

Substitute Names

Reverse conversion where you have a name and pattern and want to get a full path is also possible:

use capturing_glob::Pattern;

assert_eq!(Pattern::new("images/(*).jpg")?.substitute(&["cat"])?,
           "images/cat.jpg");
assert_eq!(Pattern::new("images/(*.jpg)")?.substitute(&["cat.jpg"])?,
           "images/cat.jpg");

Note: we don’t check substituted pattern. So the following is possible:

use capturing_glob::Pattern;

let pattern = Pattern::new("images/(*.jpg)")?;
assert_eq!(pattern.substitute(&["cat.png"])?, "images/cat.png");
assert!(!pattern.matches(&pattern.substitute(&["cat.png"])?));

Structs

Entries

An iterator that yields Entry’ies that match a particular pattern.

Entry

Entry that contains file path as well as all capture groups if any

GlobError

A glob iteration error.

MatchOptions

Configuration options to modify the behaviour of Pattern::matches_with(..).

Pattern

A compiled Unix shell style pattern.

PatternError

A pattern parsing error.

Enums

SubstitutionError

A pattern substitution error

Functions

glob

Return an iterator that produces all the paths and capture groups that match the given pattern using default match options, which may be absolute or relative to the current working directory.

glob_with

Return an iterator that produces all the paths with capture groups that match the given pattern using the specified match options, which may be absolute or relative to the current working directory.

Type Aliases

GlobResult

An alias for a glob iteration result.