looser OS interface; v2

README.md

@@ -8,6 +8,8 @@ Path pattern matching and globbing supporting `doublestar` (`**`) patterns.
 
 ## About
 
+### [Updating from v1 to v2?](UPDATING.md)
+
 **doublestar** is a [golang](http://golang.org/) implementation of path pattern
 matching and globbing with support for "doublestar" (aka globstar: `**`)
 patterns.
@@ -38,13 +40,13 @@ only match directories.
 **doublestar** can be installed via `go get`:
 
 ```bash
-go get github.com/bmatcuk/doublestar
+go get github.com/bmatcuk/doublestar/v2
 ```
 
 To use it in your code, you must import it:
 
 ```go
-import "github.com/bmatcuk/doublestar"
+import "github.com/bmatcuk/doublestar/v2"
 ```
 
 ## Usage

UPGRADING.md

@@ -0,0 +1,13 @@
+# Upgrading from v1 to v2
+
+The change from v1 to v2 was fairly minor: the return type of the `Open` method
+on the `OS` interface was changed from `*os.File` to `File`, a new interface
+exported by doublestar. The new `File` interface only defines the functionality
+doublestar actually needs (`io.Closer` and `Readdir`), making it easier to use
+doublestar with [go-billy](https://github.com/src-d/go-billy),
+[afero](https://github.com/spf13/afero), or something similar. If you were
+using this functionality, updating should be as easy as updating `Open's`
+return type, since `os.File` already implements `doublestar.File`.
+
+If you weren't using this functionality, updating should be as easy as changing
+your dependencies to point to v2.

doublestar.go

@@ -2,6 +2,7 @@ package doublestar
 
 import (
 	"fmt"
+	"io"
 	"os"
 	"path"
 	"path/filepath"
@@ -10,27 +11,33 @@ import (
 	"unicode/utf8"
 )
 
+// File defines a subset of file operations
+type File interface {
+	io.Closer
+	Readdir(count int) ([]os.FileInfo, error)
+}
+
 // An OS abstracts functions in the standard library's os package.
 type OS interface {
 	Lstat(name string) (os.FileInfo, error)
-	Open(name string) (*os.File, error)
+	Open(name string) (File, error)
 	PathSeparator() rune
 	Stat(name string) (os.FileInfo, error)
 }
 
-// StandardOS is a value that implements the OS interface by calling functions
-// in the standard libray's os package.
-var StandardOS OS = standardOS{}
-
 // A standardOS implements OS by calling functions in the standard library's os
 // package.
 type standardOS struct{}
 
 func (standardOS) Lstat(name string) (os.FileInfo, error) { return os.Lstat(name) }
-func (standardOS) Open(name string) (*os.File, error)     { return os.Open(name) }
+func (standardOS) Open(name string) (File, error)         { return os.Open(name) }
 func (standardOS) PathSeparator() rune                    { return os.PathSeparator }
 func (standardOS) Stat(name string) (os.FileInfo, error)  { return os.Stat(name) }
 
+// StandardOS is a value that implements the OS interface by calling functions
+// in the standard libray's os package.
+var StandardOS OS = standardOS{}
+
 // ErrBadPattern indicates a pattern was malformed.
 var ErrBadPattern = path.ErrBadPattern
 

go.mod

@@ -1,3 +1,3 @@
-module github.com/bmatcuk/doublestar
+module github.com/bmatcuk/doublestar/v2
 
 go 1.12