doublestar

README

doublestar

Path pattern matching and globbing supporting doublestar (**) patterns.

About

Upgrading to v2? To v3?

doublestar is a golang implementation of path pattern matching and globbing with support for "doublestar" (aka globstar: **) patterns.

doublestar patterns match files and directories recursively. For example, if you had the following directory structure:

grandparent
`-- parent
    |-- child1
    `-- child2

You could find the children with patterns such as: **/child*, grandparent/**/child?, **/parent/*, or even just ** by itself (which will return all files and directories recursively).

Bash's globstar is doublestar's inspiration and, as such, works similarly. Note that the doublestar must appear as a path component by itself. A pattern such as /path** is invalid and will be treated the same as /path*, but /path*/** should achieve the desired result. Additionally, /path/** will match all directories and files under the path directory, but /path/**/ will only match directories.

Installation

doublestar can be installed via go get:

go get github.com/bmatcuk/doublestar/v2

To use it in your code, you must import it:

import "github.com/bmatcuk/doublestar/v2"

Usage

Match

func Match(pattern, name string) (bool, error)

Match returns true if name matches the file name pattern (see below). name and pattern are split on forward slash (/) characters and may be relative or absolute.

Note: Match() is meant to be a drop-in replacement for path.Match(). As such, it always uses / as the path separator. If you are writing code that will run on systems where / is not the path separator (such as Windows), you want to use PathMatch() (below) instead.

PathMatch

func PathMatch(pattern, name string) (bool, error)

PathMatch returns true if name matches the file name pattern (see below). The difference between Match and PathMatch is that PathMatch will automatically use your system's path separator to split name and pattern.

PathMatch() is meant to be a drop-in replacement for filepath.Match().

Glob

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

Glob finds all files and directories in the filesystem that match pattern (see below). pattern may be relative (to the current working directory), or absolute.

Glob() is meant to be a drop-in replacement for filepath.Glob().

Patterns

doublestar supports the following special terms in the patterns:

Special Terms	Meaning
*	matches any sequence of non-path-separators
**	matches any sequence of characters, including path separators
?	matches any single non-path-separator character
[class]	matches any single non-path-separator character against a class of characters (see below)
{alt1,...}	matches a sequence of characters if one of the comma-separated alternatives matches

Any character with a special meaning can be escaped with a backslash (\).

A mid-pattern doublestar (**) behaves like bash's globstar option: a pattern such as path/to/**.txt would return the same results as path/to/*.txt. The pattern you're looking for is path/to/**/*.txt.

Character Classes

Character classes support the following:

Class	Meaning
[abc]	matches any single character within the set
[a-z]	matches any single character in the range
[^class]	matches any single character which does not match the class

Abstracting the os package

doublestar by default uses the Open, Stat, and Lstat, functions and PathSeparator value from the standard library's os package. To abstract this, for example to be able to perform tests of Windows paths on Linux, or to interoperate with your own filesystem code, it includes the functions GlobOS and PathMatchOS which are identical to Glob and PathMatch except that they operate on an OS interface:

type OS interface {
    Lstat(name string) (os.FileInfo, error)
    Open(name string) (*os.File, error)
    PathSeparator() rune
    Stat(name string) (os.FileInfo, error)
}

StandardOS is a value that implements this interface by calling functions in the standard library's os package.

License

MIT License

Documentation

Index

• Variables
• func Glob(pattern string) (matches []string, err error)
• func GlobOS(vos OS, pattern string) (matches []string, err error)
• func Match(pattern, name string) (bool, error)
• func PathMatch(pattern, name string) (bool, error)
• func PathMatchOS(vos OS, pattern, name string) (bool, error)
• type File
• type OS

Variables

var ErrBadPattern = path.ErrBadPattern

ErrBadPattern indicates a pattern was malformed.

Functions

func Glob

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

Glob returns the names of all files matching pattern or nil if there is no matching file. The syntax of pattern is the same as in Match. The pattern may describe hierarchical names such as /usr/*/bin/ed (assuming the Separator is '/').

Glob ignores file system errors such as I/O errors reading directories. The only possible returned error is ErrBadPattern, when pattern is malformed.

Your system path separator is automatically used. This means on systems where the separator is '\\' (Windows), escaping will be disabled.

Note: this is meant as a drop-in replacement for filepath.Glob().

func GlobOS

func GlobOS(vos OS, pattern string) (matches []string, err error)

GlobOS is like Glob except that it operates on vos.

func Match

func Match(pattern, name string) (bool, error)

Match returns true if name matches the shell file name pattern. The pattern syntax is:

pattern:
  { term }
term:
  '*'         matches any sequence of non-path-separators
  '**'        matches any sequence of characters, including
              path separators.
  '?'         matches any single non-path-separator character
  '[' [ '^' '!' ] { character-range } ']'
        character class (must be non-empty)
  '{' { term } [ ',' { term } ... ] '}'
  c           matches character c (c != '*', '?', '\\', '[')
  '\\' c      matches character c

character-range:
  c           matches character c (c != '\\', '-', ']')
  '\\' c      matches character c
  lo '-' hi   matches character c for lo <= c <= hi

Match requires pattern to match all of name, not just a substring. The path-separator defaults to the '/' character. The only possible returned error is ErrBadPattern, when pattern is malformed.

Note: this is meant as a drop-in replacement for path.Match() which always uses '/' as the path separator. If you want to support systems which use a different path separator (such as Windows), what you want is the PathMatch() function below.

func PathMatch

func PathMatch(pattern, name string) (bool, error)

PathMatch is like Match except that it uses your system's path separator. For most systems, this will be '/'. However, for Windows, it would be '\\'. Note that for systems where the path separator is '\\', escaping is disabled.

Note: this is meant as a drop-in replacement for filepath.Match().

func PathMatchOS

func PathMatchOS(vos OS, pattern, name string) (bool, error)

PathMatchOS is like PathMatch except that it uses vos's path separator.

Types

type File

type File interface {
	io.Closer
	Readdir(count int) ([]os.FileInfo, error)
}

File defines a subset of file operations

type OS

type OS interface {
	Lstat(name string) (os.FileInfo, error)
	Open(name string) (File, error)
	PathSeparator() rune
	Stat(name string) (os.FileInfo, error)
}

An OS abstracts functions in the standard library's os package.

var StandardOS OS = standardOS{}

StandardOS is a value that implements the OS interface by calling functions in the standard libray's os package.