fileglob

README

fileglob

A file globbing library.

What

fileglob is a glob library that uses gobwas/glob underneath and returns only matching files or direcories, depending on the configuration. Due to this great foundation, fileglob supports:

• Asterisk wildcards (*)
• Super-asterisk wildcards (**)
• Single symbol wildcards (?)
• Character list matchers with negation and ranges ([abc], [!abc], [a-c])
• Alternative matchers ({a,b})
• Nested globbing ({a,[bc]})
• Escapable wildcards (\{a\}/\* and fileglob.QuoteMeta(pattern))

By also building on top of fs.FS, a range of alternative filesystems as well as custom filesystems are supported.

Why

gobwas/glob is very well implemented: it has a lexer, compiler, and all that, which seems like a better approach than most libraries do: regex.

It doesn't have a Walk method though, and we needed it in a couple of places. So we decided to implement it ourselves, a little bit based on how mattn/go-zglob works.

Documentation

Overview

Package fileglob provides a filesystem glob API.

Index

• func ContainsMatchers(pattern string) bool
• func Glob(pattern string, opts ...OptFunc) ([]string, error)
• func MatchDirectoryAsFile(opts *globOptions)
• func MatchDirectoryIncludesContents(opts *globOptions)
• func MaybeRootFS(opts *globOptions)
• func QuoteMeta(opts *globOptions)
• func ValidPattern(pattern string) error
• type OptFunc
  • func WithFs(f fs.FS) OptFunc
  • func WriteOptions(w io.Writer) OptFunc

Functions

func ContainsMatchers

func ContainsMatchers(pattern string) bool

ContainsMatchers determines whether the pattern contains any type of glob matcher. It will also return false if the pattern is an invalid expression.

func Glob

func Glob(pattern string, opts ...OptFunc) ([]string, error)

Glob returns all files that match the given pattern in the current directory. If the given pattern indicates an absolute path, it will glob from `/` (or from the volume root, on Windows). If the given pattern starts with `../`, it will resolve to its absolute path and glob from `/`.

func MatchDirectoryAsFile

func MatchDirectoryAsFile(opts *globOptions)

MatchDirectoryAsFile makes a match on a directory match its name only.

Also check MatchDirectoryIncludesContents.

func MatchDirectoryIncludesContents

func MatchDirectoryIncludesContents(opts *globOptions)

MatchDirectoryIncludesContents makes a match on a directory match all files inside it as well.

This is the default behavior.

Also check MatchDirectoryAsFile.

func MaybeRootFS

func MaybeRootFS(opts *globOptions)

MaybeRootFS setups fileglob to walk from the root directory (/) or volume (on windows) if the given pattern is an absolute path.

Result will also be prepended with the root path or volume.

This is the default behavior, so this option is not needed anymore. It is kept for backwards compatibility.

func QuoteMeta

func QuoteMeta(opts *globOptions)

QuoteMeta quotes all glob pattern meta characters inside the argument text. For example, QuoteMeta for a pattern `{foo*}` sets the pattern to `\{foo\*\}`.

func ValidPattern

func ValidPattern(pattern string) error

ValidPattern determines whether a pattern is valid. It returns the parser error if the pattern is invalid and nil otherwise.

Types

type OptFunc

type OptFunc func(opts *globOptions)

OptFunc is a function that allow to customize Glob.

func WithFs

func WithFs(f fs.FS) OptFunc

WithFs allows to provide another fs.FS implementation to Glob.

Patterns are always relative to the root of the given fs.FS, so this also disables the default root filesystem handling of absolute patterns.

func WriteOptions

func WriteOptions(w io.Writer) OptFunc

WriteOptions write the current options to the given writer.