Path Glob Patterns

PathGlobPattern::compile() returns an immutable PathGlobPatternPtr suitable for concurrent matching. Compilation and matching do not access the filesystem. Paths need not exist. String candidates behave exactly like constructing Path{text}; empty or invalid candidates never match. Matching is case-sensitive, uses decoded characters, and includes dotfiles.

Matching Modes

fullMatch() consumes all non-root components. suffixMatch() starts at a component boundary and reaches the end. match(path, mode) selects the same behavior at runtime using PathGlobMatchMode::Full or Suffix. Each operation also accepts a String.

Pattern	Candidate	Full	Suffix
`*.cpp`	`src/main.cpp`	False	True
`/*.cpp`	`src/main.cpp`	False	False
`foo`	`a/foo/child`	False	False
`/foo/`	`a/foo/child`	True	True

A leading slash anchors suffix matching to the first non-root component; full matching ignores this anchor. Drive letters and UNC root identity do not participate in matching. Literal roots in patterns are removed and anchor suffix matching. Wildcards in roots are rejected. A standalone slash matches a zero-component root. To constrain filesystem locations, combine matching with explicit path or access checks.

Syntax and Compilation Flags

* matches zero or more characters within one component, ? matches one character, and Core [a-z] or [^a-z] sets match one character. Backslash escapes ?, *, [, ], backslash, ;, and #. Use slash separators on every platform. Character sets and escaped characters are never list delimiters.

Whole-component ** matches zero or more components. a/**/b includes a/b and a/x/y/b; a/** also matches a itself. Multiple recursive components are allowed. Embedded **, runs of three stars, malformed sets, unsupported escapes, and trailing slashes are rejected. Standalone / is the trailing-slash exception.

The default flags are RecursiveWildcard | TrimWhitespace. Explicit flags replace this default set.

Flag	Effect
`RecursiveWildcard`	Permit whole-component `**`.
`TrimWhitespace`	Trim bare spaces and tabs from the outer edges of each alternative, preserving interior component whitespace.
`MultiplePatterns`	Allow LF or CRLF between OR alternatives; ignore empty alternatives.
`SemicolonSeparator`	Also allow semicolon separators; requires `MultiplePatterns`.
`IgnoreComments`	Ignore lines starting with `#`, after leading spaces/tabs only when trimming is enabled.

Comment lines, including their line endings, are discarded without parsing their contents. Inline hashes, including after a semicolon on a noncomment line, stay literal. Use \# for a literal leading hash. Sets such as [ ] preserve boundary whitespace. Disabled unescaped separators raise ParseError. An invalid flag combination raises ParameterFailure. Empty or comment-only input raises ParseError. Parse errors retain code-point positions in the original source, including earlier alternatives and comments. These options do not implement ignore-rule negation, precedence, or directory-only syntax.

using namespace el::text::literals;
using Flag = el::PathGlobPatternFlag;
const auto sources = el::PathGlobPattern::compile(
    "# Source files\n **/*.cpp ; **/*.hpp\n"_el,
    el::PathGlobPatternFlags{
        Flag::Default, Flag::MultiplePatterns, Flag::SemicolonSeparator, Flag::IgnoreComments});
const auto accepted = sources->fullMatch("src/main.cpp"_el);

Walking and Pruning

mayMatchDescendant(directory, mode) tests whether a strict descendant could match. False guarantees that pruning is safe; true may conservatively retain a branch, without testing whether that branch exists. An unanchored suffix pattern can start again farther down the tree.

PathWalkOptions::setGlobPattern() accepts a compiled pointer or a string plus compile flags. A string is compiled before replacing the previous option; failure leaves that option unchanged. setGlobMatchMode() selects Full (the default) or Suffix. Matching is relative to the starting directory.

const auto options = el::PathWalkOptions{}
    .setGlobPattern("src/**/*.cpp"_el)
    .setTypes(el::PathType::RegularFile);
root.walker().walkOrThrow(callback, options);

The glob runs before reporting filters and additional metadata requests. Its descendant check runs before descent filters. Nonmatching ancestors remain traversable. Pruned branches do not reach user callbacks. See File-System Paths for symlink, callback, and error policies.

Interface

enum class erbsland::path::PathGlobMatchMode : std::uint8_t

Select which component boundary starts a path-glob match.

Values:

enumerator Full: Consume every non-root component.

enumerator Suffix: Start at any component boundary, unless the pattern is anchored.

class PathGlobPattern

An immutable, case-sensitive path glob, safe for concurrent matching without filesystem access.

See: Path Glob Patterns

Public Functions

~PathGlobPattern(): Release the compiled program when its last shared owner releases the pattern.

bool fullMatch(const Path &path) const

Match every non-root component, ignoring the pattern’s leading anchor.

Parameters:: path – Candidate path; empty paths never match.
Returns:: Whether the complete path matches any alternative.

bool suffixMatch(const Path &path) const

Match a suffix beginning at a component boundary and reaching the path end.

Parameters:: path – Candidate path; anchored alternatives start at its first non-root component.
Returns:: Whether any alternative matches.

bool match(const Path &path, PathGlobMatchMode mode) const

Match using a runtime-selected mode.

Parameters:

path – Candidate path; roots do not participate in matching.
mode – Full or suffix matching.

Returns:

Whether any alternative matches.

auto mayMatchDescendant(const Path &directory, PathGlobMatchMode mode = PathGlobMatchMode::Full) const -> bool

Test whether a strict descendant could match, without accessing the filesystem.

False guarantees that pruning is safe; true may conservatively retain a branch.

Parameters:

directory – Candidate directory, independent of its filesystem type or existence.
mode – Matching mode to use for descendants.

Returns:

Whether a matching descendant remains possible; false for an empty path.

bool fullMatch(const text::String &text) const

Match text after the same lexical parsing as Path{text}.

Parameters:: text – Candidate path spelling.
Returns:: Whether the complete parsed path matches.

bool suffixMatch(const text::String &text) const

Match a suffix of a lexically parsed path.

Parameters:: text – Candidate path spelling.
Returns:: Whether a suffix matches.

bool match(const text::String &text, PathGlobMatchMode mode) const

Match a lexically parsed path with a selected mode.

Parameters:

text – Candidate path spelling.
mode – Full or suffix matching.

Returns:

Whether the parsed path matches.

auto mayMatchDescendant(const text::String &text, PathGlobMatchMode mode = PathGlobMatchMode::Full) const -> bool

Test descendant feasibility after lexical path parsing.

Parameters:

text – Candidate directory spelling.
mode – Matching mode to use for descendants.

Returns:

Whether a strict descendant could match.

Public Static Functions

static auto compile(text::AnyString pattern, PathGlobPatternFlags flags = PathGlobPatternFlag::Default) -> PathGlobPatternPtr 

Compile path components and optional OR alternatives using Core character-set syntax.

Parameters:

pattern – Pattern text in any supported encoding.
flags – Enabled syntax; explicit flags replace the default set.

Throws:

err::ParseError – If syntax is invalid or no alternatives remain.

Returns:

A fully compiled immutable pattern.

using erbsland::path::PathGlobPatternPtr = std::shared_ptr<const PathGlobPattern>: A shared, immutable, thread-safe compiled path glob.

enum class erbsland::path::PathGlobPatternFlag : std::uint8_t

Select syntax accepted when compiling a path glob.

Values:

enumerator None: Disable every optional syntax feature.

enumerator RecursiveWildcard: Permit whole-component **.

enumerator TrimWhitespace: Trim outer bare spaces and tabs from each alternative.

enumerator MultiplePatterns: Permit newline-separated alternatives.

enumerator SemicolonSeparator: Permit semicolon separators; requires MultiplePatterns.

enumerator IgnoreComments: Ignore lines starting with # after optional whitespace trimming.

enumerator Default: Default single-pattern syntax.

using erbsland::path::PathGlobPatternFlags = util::EnumFlags<PathGlobPatternFlag>: Flags controlling path-glob compilation.