README
¶
Walker 
Walker: File Ranger contains convenient iterators for walking a directory or fs.FS.
Documentation
¶
Overview ¶
Package Walker: File Ranger contains convenient iterators for walking a directory or fs.FS.
Index ¶
- type Entry
- type ErrorPolicy
- type FilterFunc
- func And(filters ...FilterFunc) FilterFunc
- func MatchExtension(extensions ...string) FilterFunc
- func MatchGlobName(patterns ...string) FilterFunc
- func MatchGlobPath(patterns ...string) FilterFunc
- func MatchPrefixName(prefix string) FilterFunc
- func MatchPrefixPath(prefix string) FilterFunc
- func MatchRegexp(re *regexp.Regexp) FilterFunc
- func MatchRegexpMust(re string) FilterFunc
- func Not(f FilterFunc) FilterFunc
- func Or(filters ...FilterFunc) FilterFunc
- type Ranger
- func (tr *Ranger) Entries() iter.Seq[Entry]
- func (tr *Ranger) Err() error
- func (tr *Ranger) Exclude(f FilterFunc)
- func (tr *Ranger) ExcludeDir(f FilterFunc)
- func (tr *Ranger) FileEntries() iter.Seq[Entry]
- func (tr *Ranger) FilePaths() iter.Seq[string]
- func (tr *Ranger) HasError() bool
- func (tr *Ranger) Include(f FilterFunc)
- func (tr *Ranger) IncludeDir(f FilterFunc)
- func (tr *Ranger) SkipDir()
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
Entry is a single path/fs.DirEntry pair yielded by a Ranger. It knows whether to use package filepath or package path for its methods.
func (Entry) Base ¶
Base returns the last element of Path, typically the filename. See path.Base and filepath.Base.
func (Entry) Dir ¶
Dir returns the directory of the Entry. Unlike path.Dir or filepath.Dir, it knows whether e represents a directory, in which case it returns its own path, not its parent directory.
func (Entry) Ext ¶
Ext returns the file name extension of Path. See path.Ext and filepath.Ext.
func (Entry) IsDir ¶
IsDir returns whether the DirEntry is a directory. If DirEntry is nil, it returns false.
func (Entry) Split ¶
Split splits path immediately following the final separator, separating it into a directory and file name component. See path.Split and filepath.Split.
type ErrorPolicy ¶
ErrorPolicy is a function that returns whether to continue (true) or halt (false) on error by examining the error and the current Entry.
var OnErrPermissionIgnore ErrorPolicy = func(err error, e Entry) bool { return errors.Is(err, fs.ErrPermission) }
OnErrPermissionIgnore is an ErrorPolicy that continues if an error is fs.ErrPermission; otherwise it halts on error.
var OnErrorHalt ErrorPolicy = onErrorHalt
OnErrorHalt is an ErrorPolicy that halts on any error.
var OnErrorIgnore ErrorPolicy = onErrorIgnore
OnErrorIgnore is an ErrorPolicy that always continues regardless of errors.
var OnErrorPanic ErrorPolicy = onErrorPanic
OnErrorPanic is an ErrorPolicy that panics on any error. Not recommended for production.
func OnErrorCollect ¶
func OnErrorCollect(errs *[]error) ErrorPolicy
OnErrorCollect returns an ErrorPolicy that collects errors into the provided slice while continuing.
type FilterFunc ¶
FilterFunc is a function type used to filter files and directories during the walk.
var MatchDotFile FilterFunc = MatchPrefixName(".")
MatchDotFile reports whether an Entry.Name() begins with a dot.
func And ¶
func And(filters ...FilterFunc) FilterFunc
And chains FilterFuncs and returns whether they are all true.
func MatchExtension ¶
func MatchExtension(extensions ...string) FilterFunc
MatchExtension creates a FilterFunc that filters files based on their extensions. It returns true if the file has any of the specified extensions. It is case insensitive.
func MatchGlobName ¶
func MatchGlobName(patterns ...string) FilterFunc
MatchGlobName returns true if Entry.Name() matches any of the glob patterns.
func MatchGlobPath ¶
func MatchGlobPath(patterns ...string) FilterFunc
MatchGlobPath returns true if the path matches any of the glob patterns.
func MatchPrefixName ¶
func MatchPrefixName(prefix string) FilterFunc
MatchPrefixName creates a FilterFunc that matches if Entry.Name() starts with the given prefix.
func MatchPrefixPath ¶
func MatchPrefixPath(prefix string) FilterFunc
MatchPrefixPath creates a FilterFunc that matches paths starting with the given prefix.
func MatchRegexp ¶
func MatchRegexp(re *regexp.Regexp) FilterFunc
MatchRegexp returns true if the path matches the regular expression.
func MatchRegexpMust ¶
func MatchRegexpMust(re string) FilterFunc
MatchRegexpMust compiles re using regexp.MustCompile and passes it to MatchRegexp.
func Or ¶
func Or(filters ...FilterFunc) FilterFunc
Or chains FilterFuncs and returns whether at least one is true.
type Ranger ¶
type Ranger struct {
// contains filtered or unexported fields
}
Ranger provides a convenient way to walk through a directory structure.
Example ¶
package main
import (
"fmt"
"testing/fstest"
"github.com/earthboundkid/walker"
)
func main() {
// Demo filesystem
fsys := fstest.MapFS{
".a-stuff/file-1.jpeg": &fstest.MapFile{},
"b-file-2.txt": &fstest.MapFile{},
"c/file-3.png": &fstest.MapFile{},
"d/file-4.jpeg": &fstest.MapFile{},
"e-file-5.txt": &fstest.MapFile{},
}
// Make a new Ranger that halts on error
tr := walker.New(fsys, ".", walker.OnErrorHalt)
fmt.Println("Files:")
for path := range tr.FilePaths() {
fmt.Println("-", path)
}
// Do a final error check
if tr.HasError() {
panic(tr.Err())
}
}
Output: Files: - .a-stuff/file-1.jpeg - b-file-2.txt - c/file-3.png - d/file-4.jpeg - e-file-5.txt
Example (Matching) ¶
package main
import (
"fmt"
"testing/fstest"
"github.com/earthboundkid/walker"
)
func main() {
// Demo filesystem
fsys := fstest.MapFS{
".a-stuff/file-1.jpeg": &fstest.MapFile{},
"b-file-2.txt": &fstest.MapFile{},
"c/file-3.png": &fstest.MapFile{},
"d/file-4.jpeg": &fstest.MapFile{},
"e-file-5.txt": &fstest.MapFile{},
}
// Make a new Ranger that ignores permission errors and halts for other problems
tr := walker.New(fsys, ".", walker.OnErrPermissionIgnore)
// Ignore dot files and dot directories
tr.Exclude(walker.MatchDotFile)
tr.ExcludeDir(walker.MatchDotFile)
// Only list PNG and JPEG files
tr.Include(walker.Or(
walker.MatchExtension(".png"),
walker.MatchExtension(".jpeg"),
))
fmt.Println("Files:")
for path := range tr.FilePaths() {
fmt.Println("-", path)
}
// Do a final error check
if tr.HasError() {
panic(tr.Err())
}
}
Output: Files: - c/file-3.png - d/file-4.jpeg
func New ¶
func New(fsys fs.FS, root string, erp ErrorPolicy) Ranger
New creates a new *Ranger with the given root directory. Pass a nil fsys to use filepath.WalkFunc and walk the OS filesystem instead of an fs.FS. The default Ranger includes all files and directories. There is no default ErrorPolicy.
func (*Ranger) Exclude ¶
func (tr *Ranger) Exclude(f FilterFunc)
Exclude tells the Ranger to exclude matching files when iterating. Files matched by Exclude take precedence over files matched by Include.
func (*Ranger) ExcludeDir ¶
func (tr *Ranger) ExcludeDir(f FilterFunc)
ExcludeDir tells the Ranger not to recursing into matching directories. Directories matched by ExcludeDir take precedence over directories matched by IncludeDir.
func (*Ranger) FileEntries ¶
FileEntries returns a sequence of Entries for matching files, ignoring directories.
func (*Ranger) HasError ¶
HasError returns true if an error has been encountered during the last walk.
func (*Ranger) Include ¶
func (tr *Ranger) Include(f FilterFunc)
Include tells the Ranger to include matching files when iterating. The default is to include all files.
func (*Ranger) IncludeDir ¶
func (tr *Ranger) IncludeDir(f FilterFunc)
IncludeDir tells the Ranger to recursing into matching directories. The default is to include all directories.
Source Files