dir

Documentation

Overview

Package dir exposes globing and scanning functions that walk the filesystem and find files and folder that match specific patterns. Patterns are defined using an extended glob pattern that can match deep subdirectories.

Extended glob patterns always use `/` as path separator and `\` as escape character, regardless of the OS native filename format.

Extended glob patterns are interpreted as a sequence of one or more path fragments. Each path fragment can be matched against either a literal sequence of characters or a glob pattern.

`*` matches zero or more occurrences of any character within a path fragment, `?` matches one occurrence of any character within a path fragment, `[<range>]` matches one occurrence of any listed character within a path fragment, and `{foo,bar}` matches one occurrence of either `foo` or `bar` within a path fragment

`**/` allows the subsequent fragment to be matched anywhere within the directory tree. It should always be followed by another fragment matching expression.

Index

• Variables
• func Glob(pattern string) (matches []string, err error)
• func GlobFrom(basepath, pattern string) (matches []string, err error)
• func Scan(pattern string, walkFn fs.WalkDirFunc) error
• func ScanFrom(basepath, pattern string, walkFn fs.WalkDirFunc) error
• func Walk(prefix, root string, fn fs.WalkDirFunc) error
• type GlobMatcher
  • func NewGlobMatcher(pattern string) (m *GlobMatcher, err error)
  • func (m *GlobMatcher) Glob() (matches []string, err error)
  • func (m *GlobMatcher) GlobFrom(basepath string) (matches []string, err error)
  • func (m *GlobMatcher) Match(filename string) bool
  • func (m *GlobMatcher) PrefixMatch(filename string) bool
  • func (m *GlobMatcher) Scan(walkFn fs.WalkDirFunc) error
  • func (m *GlobMatcher) ScanFrom(basepath string, walkFn fs.WalkDirFunc) error

Variables

var ErrRecursiveSymlink = errors.Sentinel("ErrRecursiveSymlink")

ErrRecursiveSymlink is a sentinel error returned during symlink traversal if the target path is a symlink that has already been visited.

var SkipDir = filepath.SkipDir

SkipDir is an alias of `filepath.SkipDir`, used as a sentinel during directory traversal to prevent any deeper recursion into a directory.

Functions

func Glob

func Glob(pattern string) (matches []string, err error)

Glob scans the file tree and returns a list of filenames matching `pattern` which must be specified according to the extended glob pattern described in this package.

func GlobFrom

func GlobFrom(basepath, pattern string) (matches []string, err error)

GlobFrom scans the file tree starting at `basepath` and returns a list of filenames matching `pattern`, which must be specified according to the extended glob pattern described in this package. If the pattern is relative, the resulting filenames are relative to `basepath`. If the pattern is absolute, the basepath is ignored and the the resulting filenames are absolute.

func Scan

func Scan(pattern string, walkFn fs.WalkDirFunc) error

Scan scans the file tree for filenames matching `pattern` and calls `walkFn` for every match. The pattern must be specified according to the extended glob pattern described in the package level documentation.

func ScanFrom

func ScanFrom(basepath, pattern string, walkFn fs.WalkDirFunc) error

ScanFrom scans the file tree starting at `basepath` for filenames matching `pattern` and calls `walkFn` for every match. The pattern must be specified according to the extended glob pattern described in this package. If the pattern is relative, filenames are reported relative to `basepath`. If the pattern is absolute, the basepath is ignored and filenames are reported with an absolute path.

func Walk

func Walk(prefix, root string, fn fs.WalkDirFunc) error

Walk is similar to `filepath.WalkDir()`, but it follows symlinks and takes an additional `prefix` argument. The walk starts at '<prefix>/<root>' and the paths are reported relative to `prefix`; the starting path is always recursed into, but never reported unless an error occurs during filesystem operation. Either or both of `prefix` and `root` can be empty, a relative path or an absolute path; if `root` is an absolute path, `prefix` is ignored, and all reported paths are absolute. In a path refers to a directory, it is reported with a trailing path separator.

When symlinks are encountered, the path is reported with the FileInfo of the destination, and if it is a directory, it is traversed unless an error is returned. Any error that occurs while evaluating the symlink is reported to the client. If the symlink points back to a folder along the current path, the client is called with ErrRecursiveSymlink and the link evaluation stops there.

Types

type GlobMatcher

type GlobMatcher struct {
	// contains filtered or unexported fields
}

GlobMatcher is a pre-compiled matcher for a glob pattern

func NewGlobMatcher

func NewGlobMatcher(pattern string) (m *GlobMatcher, err error)

NewGlobMatcher compiles an extended glob pattern into a GlobMatcher

func (*GlobMatcher) Glob

func (m *GlobMatcher) Glob() (matches []string, err error)

Glob scans the file tree and returns a list of filenames matching the pattern. The pattern must be specified according to the extended glob pattern described in the package level documentation.

func (*GlobMatcher) GlobFrom

func (m *GlobMatcher) GlobFrom(basepath string) (matches []string, err error)

GlobFrom scans the file tree and returns a list of filenames matching the pattern. The pattern must be specified according to the extended glob pattern described in the package level documentation.

func (*GlobMatcher) Match

func (m *GlobMatcher) Match(filename string) bool

Match returns true if the provided filename matches the compiled glob expressions

func (*GlobMatcher) PrefixMatch

func (m *GlobMatcher) PrefixMatch(filename string) bool

PrefixMatch returns true if the provided filename, most likely a directory name, is a prefix partial match for the compiled glob expressions. This function can be used during scanning to skip over directories that cannot math the full pattern.

func (*GlobMatcher) Scan

func (m *GlobMatcher) Scan(walkFn fs.WalkDirFunc) error

Scan scans the file tree for filenames matching the pattern and call the walkFn function for every match. The pattern must be specified according to the extended glob pattern described in the package level documentation.

func (*GlobMatcher) ScanFrom

func (m *GlobMatcher) ScanFrom(basepath string, walkFn fs.WalkDirFunc) error

ScanFrom scans the file tree for filenames matching the pattern and call the walkFn function for every match. The pattern must be specified according to the extended glob pattern described in the package level documentation.