README
¶
zzglob
A better glob library for Go
Goals
- ✅ Glob in a deterministic order, like
fs.WalkDir. - ✅ Support the classics like
?and*, and also modern conveniences like**,{x,y,z},[abc], and[^abc]. - ✅ Expand
~to the current user's homedir. - ✅ Optionally traverse directory symlinks.
- ✅ Avoid walking directories unnecessarily -
globbing
foo*/barshould only walk inside directories starting withfoo, not other directories. - ✅ Pass walk errors (e.g. permissions errors) to the callback.
- ✅ Supports globbing over any
io.FS, not just the host filesystem. - ✅ Supports globbing on Windows with Windows-style paths, by default.
Also the implementation shouldn't be totally inscrutable. It is based on a
state machine, and I have attempted to cleanly separate each parsing phase.
You can convert a pattern to GraphViz format, that you can then convert into a
diagram, by calling Pattern.WriteDot. zzglob includes a tool called zzdot
which can do this for you, e.g.:
go run ./cmd/zzdot '[abcd]{*g,h*,i/j}/**/k' | dot -Tsvg > example.svg
In progress
- ⌚️ Improving the tests.
- 🧠 Add support for even more syntax
Pattern syntax
\- used to escape the next character in the pattern.\xmatchesx,\*matches*./- the path separator. Separates segments of each path. Matches itself only.?- matches exactly one character, except for/.*- matches zero or more characters, except for/.**- matches zero or more characters, including/. Since it can be used to mean zero or more path components,/**/also matches/.{a,b,c}- matchesaorborc. A component can be empty, e.g.{,a,b}matches either nothing oraorb. Multiple path segments,*,**, etc are all allowed within{}. To specify a path containing,within{}, escape it (\,).[abc]- matches a single character (aorborc).[]is a shorter way to write a match for a single character than{}.~- is expanded to be current user's home directory.
Each syntax element can be enabled or disabled individually when calling
Parse, and the meaning of forward slash and backslash can be swapped
(enabled by default on Windows):
pattern, err := zzglob.Parse(`C:\Windows\Media\*.mid`,
zzglob.ExpandTilde(false),
zzglob.SwapSlashes(true),
zzglob.AllowEscaping(false),
)
Similarly, symlink traversal, slash conversion, and custom fs.FS can be
supplied to Glob:
err := pattern.Glob(myWalkDirFunc,
zzglob.TraverseSymlinks(false),
zzglob.TranslateSlashes(true),
zzglob.WithFilesystem(os.DirFS("/secrets/")),
)
Documentation
¶
Overview ¶
Package zzglob implements a file path walker.
Index ¶
- func MultiGlob(ctx context.Context, patterns []*Pattern, f fs.WalkDirFunc, opts ...GlobOption) error
- type GlobOption
- type ParseOption
- func AllowAlternation(enable bool) ParseOption
- func AllowCharClass(enable bool) ParseOption
- func AllowDoubleStar(enable bool) ParseOption
- func AllowEscaping(enable bool) ParseOption
- func AllowQuestion(enable bool) ParseOption
- func AllowStar(enable bool) ParseOption
- func ExpandTilde(enable bool) ParseOption
- func WithSwapSlashes(enable bool) ParseOption
- type Pattern
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MultiGlob ¶
func MultiGlob(ctx context.Context, patterns []*Pattern, f fs.WalkDirFunc, opts ...GlobOption) error
MultiGlob is like Pattern.Glob, but globs multiple patterns simultaneously. The main idea is to group the patterns by root to avoid multiple different calls to fs.WalkDir (reducing filesystem I/O), and then to use fs.WalkDir on each root in parallel. As a result, files can be walked globbed multiple times, but only if distinct overlapping roots appear in different input patterns. You should either make sure that the callback f is safe to call concurrently from multiple goroutines, or set GoroutineLimit to 1.
Types ¶
type GlobOption ¶
type GlobOption = func(*globConfig)
GlobOption functions optionally alter how Glob operates.
func GoroutineLimit ¶
func GoroutineLimit(n int) GlobOption
GoroutineLimit sets a concurrency limit for MultiGlob. By default there is no limit. MultiGlob will create at most n worker goroutines unless n <= 0.
func TranslateSlashes ¶
func TranslateSlashes(enable bool) GlobOption
TranslateSlashes enables or disables translating to and from fs.FS paths (always with forward slashes, / ) using filepath.FromSlash. This applies to both the matching pattern and filepaths passed to the callback, and is typically required on Windows. It usually has no effect on systems where forward slash is the path separator, so it is enabled by default.
func TraverseSymlinks ¶
func TraverseSymlinks(traverse bool) GlobOption
TraverseSymlinks enables or disables the traversal of symlinks during globbing. It is enabled by default.
func WalkIntermediateDirs ¶
func WalkIntermediateDirs(enable bool) GlobOption
WalkIntermediateDirs enables or disables calling the walk function with intermediate directory paths (in addition to complete pattern matches). Enabling this is needed in order to skip intermediate directories (by returning fs.SkipDir) based on custom logic in your walk callback.
Note that:
- Intermediate path components from the "pattern root" are not included (e.g. for the pattern "fixtures/a/b/**", the callback will receive the path "fixtures/a/b", but not "fixtures" or "fixtures/a".)
- The callback can be called with intermediate directories that ultimately do _not_ contain any completely matching paths (e.g. when globbing "fixtures/**/*_test", every subdirectory of "fixtures" will be passed to your callback whether or not there is a file named like "*_test" anywhere within).
- However, all intermediate directories seen during the glob will at least partially match the pattern (e.g. "fixtures/a" partially matches "fixtures/**/*_test").
Disabled by default.
func WithFilesystem ¶
func WithFilesystem(fs fs.FS) GlobOption
WithFilesystem allows overriding the default filesystem. By default os.DirFS is used to wrap file/directory access in an fs.FS.
func WithTraceLogs ¶
func WithTraceLogs(out io.Writer) GlobOption
WithTraceLogs logs debugging information for debugging Glob itself to the provided writer. Disabled by default.
type ParseOption ¶
type ParseOption = func(*parseConfig)
ParseOption functions optionally alter how patterns are parsed.
func AllowAlternation ¶
func AllowAlternation(enable bool) ParseOption
AllowAlternation changes how { } are parsed. If enabled, { and } delimit alternations. If disabled, { and } are treated as literals. Enabled by default.
func AllowCharClass ¶
func AllowCharClass(enable bool) ParseOption
AllowCharClass changes how [ ] are parsed. If enabled, [ and ] denote character classes. If disabled, [ and ] are treated as literals. Enabled by default.
func AllowDoubleStar ¶
func AllowDoubleStar(enable bool) ParseOption
AllowDoubleStar changes how ** is parsed, and applies only if AllowStar is enabled (the default). If disabled, ** is treated as two consecutive instances of * (equivalent to a single *). Enabled by default.
func AllowEscaping ¶
func AllowEscaping(enable bool) ParseOption
AllowEscaping changes how the escape character (usually backslash - see WithSwapSlashes), is parsed. If disabled, it is treated as a literal which does not escape the next character. By default, AllowEscaping is disabled if filepath.Separator is not / (i.e. on Windows) and enabled otherwise.
func AllowQuestion ¶
func AllowQuestion(enable bool) ParseOption
AllowQuestion changes how ? is parsed. If disabled, ? is treated as a literal. Enabled by default.
func AllowStar ¶
func AllowStar(enable bool) ParseOption
AllowStar changes how * is parsed. If disabled, * is treated as a literal. Enabled by default.
func ExpandTilde ¶
func ExpandTilde(enable bool) ParseOption
ExpandTilde changes how ~ is parsed. If enabled, ~ is expanded to the current user's home directory. If disabled, ~ is treated as a literal. Enabled by default.
func WithSwapSlashes ¶
func WithSwapSlashes(enable bool) ParseOption
WithSwapSlashes changes how \ and / are interpreted. If enabled, / becomes the escape character (which can be disabled with AllowEscaping), and \ becomes the path separator (typical on Windows). Note that after parsing, the pattern internally uses / to represent the path separator (which is consistent with io/fs). To receive the correct slashes from Match or Glob, be sure to use the TranslateSlashes option. By default, WithSwapSlashes is enabled if filepath.Separator is not / (i.e. on Windows) and disabled otherwise.
type Pattern ¶
type Pattern struct {
// contains filtered or unexported fields
}
Pattern is a parsed glob pattern.
func Parse ¶
func Parse(pattern string, opts ...ParseOption) (*Pattern, error)
Parse parses a pattern.
func (*Pattern) Glob ¶
func (p *Pattern) Glob(f fs.WalkDirFunc, opts ...GlobOption) error
Glob globs for files matching the pattern in a filesystem.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
zzdot
The zzdot command parses a glob pattern, and prints the underlying state machine in GraphViz DOT language.
|
The zzdot command parses a glob pattern, and prints the underlying state machine in GraphViz DOT language. |
|
zzglob
The zzglob command searches for files with paths matching a pattern.
|
The zzglob command searches for files with paths matching a pattern. |