Crate globset

Expand description

The globset crate provides cross platform single glob and glob set matching.

Glob set matching is the process of matching one or more glob patterns against a single candidate path simultaneously, and returning all of the globs that matched. For example, given this set of globs:

*.rs
src/lib.rs
src/**/foo.rs

and a path src/bar/baz/foo.rs, then the set would report the first and third globs as matching.

§Example: one glob

This example shows how to match a single glob against a single file path.

use globset::Glob;

let glob = Glob::new("*.rs")?.compile_matcher();

assert!(glob.is_match("foo.rs"));
assert!(glob.is_match("foo/bar.rs"));
assert!(!glob.is_match("Cargo.toml"));

§Example: configuring a glob matcher

This example shows how to use a GlobBuilder to configure aspects of match semantics. In this example, we prevent wildcards from matching path separators.

use globset::GlobBuilder;

let glob = GlobBuilder::new("*.rs")
    .literal_separator(true).build()?.compile_matcher();

assert!(glob.is_match("foo.rs"));
assert!(!glob.is_match("foo/bar.rs")); // no longer matches
assert!(!glob.is_match("Cargo.toml"));

§Example: match multiple globs at once

This example shows how to match multiple glob patterns at once.

use globset::{Glob, GlobSetBuilder};

let mut builder = GlobSetBuilder::new();
// A GlobBuilder can be used to configure each glob's match semantics
// independently.
builder.add(Glob::new("*.rs")?);
builder.add(Glob::new("src/lib.rs")?);
builder.add(Glob::new("src/**/foo.rs")?);
let set = builder.build()?;

assert_eq!(set.matches("src/bar/baz/foo.rs"), vec![0, 2]);

§Syntax

Standard Unix-style glob syntax is supported:

? matches any single character. (If the literal_separator option is enabled, then ? can never match a path separator.)
* matches zero or more characters. (If the literal_separator option is enabled, then * can never match a path separator.)
** recursively matches directories but are only legal in three situations. First, if the glob starts with **/, then it matches all directories. For example, **/foo matches foo and bar/foo but not foo/bar. Secondly, if the glob ends with /**, then it matches all sub-entries. For example, foo/** matches foo/a and foo/a/b, but not foo. Thirdly, if the glob contains /**/ anywhere within the pattern, then it matches zero or more directories. Using ** anywhere else is illegal (N.B. the glob ** is allowed and means “match everything”).
{a,b} matches a or b where a and b are arbitrary glob patterns. (N.B. Nesting {...} is not currently allowed.)
[ab] matches a or b where a and b are characters. Use [!ab] to match any character except for a and b.
Metacharacters such as * and ? can be escaped with character class notation. e.g., [*] matches *.
When backslash escapes are enabled, a backslash (\) will escape all meta characters in a glob. If it precedes a non-meta character, then the slash is ignored. A \\ will match a literal \\. Note that this mode is only enabled on Unix platforms by default, but can be enabled on any platform via the backslash_escape setting on Glob.

A GlobBuilder can be used to prevent wildcards from matching path separators, or to enable case insensitive matching.

Structs§

Candidate: A candidate path for matching.
Error: Represents an error that can occur when parsing a glob pattern.
Glob: Glob represents a successfully parsed shell glob pattern.
GlobBuilder: A builder for a pattern.
GlobMatcher: A matcher for a single pattern.
GlobSet: GlobSet represents a group of globs that can be matched together in a single pass.
GlobSetBuilder: GlobSetBuilder builds a group of patterns that can be used to simultaneously match a file path.

Enums§

ErrorKind: The kind of error that can occur when parsing a glob pattern.