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.

§Crate Features

This crate includes optional features that can be enabled if necessary. These features are not required but may be useful depending on the use case.

The following features are available:

arbitrary - Enabling this feature introduces a public dependency on the arbitrary crate. Namely, it implements the Arbitrary trait from that crate for the Glob type. This feature is disabled by default.

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.

Functions§

escape: Escape meta-characters within the given glob pattern.

Crate globsetCopy item path