walker

README

Walker

Package walker is a wrapper around fs.WalkDir using custom fs.WalkDirFunc to pass results of recursive directory walk to caller through a channel.

It makes easier to use the result concurrenly.

The package is quite small and presumably does not need extensive documentation. Just browse it on https://pkg.go.dev/github.com/dmfed/walker to see what is has to offer.

Also take a look at the examples in examples dir of the repository for an overview.

Documentation

Index

• type Action
• type FilterFunc
  • func DiscardDirs() FilterFunc
  • func DiscardRegular() FilterFunc
  • func SkipDirs(paths ...string) FilterFunc
• type Info
• type Walker
  • func New() Walker

Types

type Action

type Action uint

const (
	Pass    Action = iota // Pass tells that Info should be sent to output chan
	Discard               // Disard tell to silently discard Info and NOT send it to output chan
	SkipDir               // SkipDir tells to skip directory.
	SkipAll               // SkipAll tells Walker to stop completely.
)

type FilterFunc

type FilterFunc func(Info) Action

FilterFunc is intended to use with Walker. It must return one of Actions which tell Walker how to proceed. If FilterFunc returns Pass, the Info is sent to output chan, Discard tells Walker to not sent Info to output, SkipDir tells to not visit the directory (but proceed with walk), SkipAll stops Walker (no further entries are read).

func DiscardDirs

func DiscardDirs() FilterFunc

DiscardDirs returns FilterFunc which removes directories from output when Info.DirEntry.IsDir().

func DiscardRegular

func DiscardRegular() FilterFunc

DiscardRegular return FilterFunc which removes regular files files from output when Info.DirEntry.Type().IsRegular().

func SkipDirs

func SkipDirs(paths ...string) FilterFunc

SkipDirs returns FilterFunc which tells Walker to skip directory (and all subdirectories) when Info.Path equals any of paths passed as arguments.

type Info

type Info struct {
	Path     string
	DirEntry fs.DirEntry
}

Info represents and entry located by fs.WalkDir Path is always relative to base path supplied to Walker for example if Walk is called with path == "/tmp" the returned entries will not contain "/tmp" in Path field.

type Walker

type Walker interface {
	// Walk runs fs.WalkDir under the hood and returns chan of Info.
	// All items found by fs.WalkDir are returned as is. Basically
	// Walk is a custom fs.WalkDirFunc and a wrapper around WalkDir intended
	// to send result to a channel. It also computes lazily waiting for reader
	// to pull results from the channel as opposed to fs.WalkDir (fire and forget,
	// then wait for all recursive calls to finish).
	// Walker should not be used concurrently. Create new instance of Walker instead.
	// However, concurrent reads from output chan are ok.
	Walk(ctx context.Context, path string) <-chan Info

	// WithFilters adds FilterFuncs to an existing Walker and returns instance of Walker.
	// FilerFuncs are run for each entry Walker finds in the same order as passed to this method.
	// When one of funcs returns Action not equal to Pass this action is applied and other
	// checks are not perfomed.
	WithFilters(funcs ...FilterFunc) Walker

	// Err explains why chan returned by Walk was closed. If context was
	// cancelled or context deadline exceeded or whatewer error the
	// WalkDirFunc function encountered it is returned by this method.
	// Err will return nil if chan Info has not yet been closed.
	Err() error
}

Walker crawls the specified path using fs.WalkDir and sends all encountered items as Info to the channel returned by Walk method.

func New

func New() Walker