walker

Documentation

Overview

Package walker provides a simple interface for traversing the filesystem by abstracting away IO and implementation naunces.

Index

• Constants
• func DepthFirst(root impath.Absolute, exclude Filter, cb Callback)
• type Callback
• type Filter
  • func (f *Filter) MatchFile(path string, mode fs.FileMode) bool
  • func (f *Filter) MatchPath(path string) bool
  • func (f Filter) String() string
• type PreAction
  • func (s PreAction) String() string
• type SymlinkAction
  • func (a SymlinkAction) String() string

Constants

const (
	// Access indicates that the walker should stat the path.
	Access PreAction = aRead

	// SkipPath indicates that the walker should skip the path and continue traversing.
	SkipPath PreAction = aSkip

	// Defer indicates that the walker should reschedule the path for another visit and continue traversing.
	Defer PreAction = aDefer

	// Follow indicates that the walker should follow the symlink.
	Follow SymlinkAction = aRead

	// Replace indicates that the walker should follow the symlink, but report every path from that sub-traversal as a descendant path of the symlink's path.
	//
	// For example: if /foo/bar was a symlink to /a/b, the walker would report the path of b as /foo/bar, and the path of a/b/c.d as /foo/bar/c.d.
	// This behavior is equivalent to copying the entire tree of the target in place of the symlink.
	Replace SymlinkAction = aReplace

	// SkipSymlink indicates that the walker should continue treversing without following the symlink.
	SkipSymlink SymlinkAction = aSkip
)

Functions

func DepthFirst

func DepthFirst(root impath.Absolute, exclude Filter, cb Callback)

DepthFirst walks the filesystem tree rooted at the specified root in depth-first-search style traversal. That is, every directory is visited after all its descendants have been visited.

Before visiting a path, the Pre callback is called. At this point, the client may instruct the walker to:

Skip the path;
Access and stat the path; or
Defer the path to be vistied after all its siblings have been visited.

Deferred paths block traversing back up the tree since a parent requires all its children to be processed before itself to honour the DFS contract.

If Pre returns Access, then either Symlink or Post is called after making a syscall to stat the path.

If the stat syscall returned an error, it is passed to Err callback to let the client decide whether to skip the path or cancel the entire walk.

If Symlink was called, the client may instruct the walker to:

Follow the symlink;
Replace the symlink with its target; or
Continue traversing without following the symlink.

The client may at any point return false from any callback to cancel the entire walk.

Types

type Callback

type Callback struct {
	// Pre is called before accessing the path. Returning false cancels the entire walk.
	Pre func(path impath.Absolute, realPath impath.Absolute) (PreAction, bool)

	// Symlink is called for symlinks. Returning false cancels the entire walk.
	Symlink func(path impath.Absolute, realPath impath.Absolute, info fs.FileInfo) (SymlinkAction, bool)

	// Post is called for non-symlinks. Returning false cancels the entire walk.
	Post func(path impath.Absolute, realPath impath.Absolute, info fs.FileInfo) bool

	// Err is called when an io error is encountered. Returning false cancels the entire walk.
	Err func(path impath.Absolute, realPath impath.Absolute, err error) bool
}

Callback defines the implementations that the client should provide for the walker. Returning false from any callback cancels the entire walk.

Defining a set of callbacks instead of a single shared one allows ensuring valid actions are returned at compile time. This is more robust than using implicit default actions or propagating errors at runtime.

type Filter

type Filter struct {
	// Path accepts a path, absolute or relative, and returns true if it's a match.
	Path func(path string) bool
	// File accepts a path, absolute or relative, and a mode and returns true if it's a match.
	File func(path string, mode fs.FileMode) bool
	// ID returns a unique identifier for this filter.
	// The identifier may be used by consumers to deduplicate filters so it must be unique within the consumers scope.
	ID func() string
}

Filter defines an interface for matching paths during traversal. The matching semantics, whether matches are included or excluded, is defined by the consumer.

func (*Filter) MatchFile

func (f *Filter) MatchFile(path string, mode fs.FileMode) bool

MatchFile delegates to File if set. Otherwise, returns false.

func (*Filter) MatchPath

func (f *Filter) MatchPath(path string) bool

MatchPath delegates to Path if set. Otherwise, returns false.

func (Filter) String

func (f Filter) String() string

String delegates to ID if set. Otherwise, returns the empty string.

type PreAction

type PreAction int

PreAction is an enum that defines the valid actions for the pre-access callback.

func (PreAction) String

func (s PreAction) String() string

String return a textual version of the action.

type SymlinkAction

type SymlinkAction int

SymlinkAction is an enum that defines the valid actions for a the symlink callback.

func (SymlinkAction) String

func (a SymlinkAction) String() string

String return a textual version of the action.