fpath

Documentation

Overview

Package fpath implements path traversal relative to a *file.File. A path is a slash-separated string, which may optionally begin with "/".

Index

• Variables
• func Open(ctx context.Context, root *file.File, path string) (*file.File, error)
• func OpenPath(ctx context.Context, root *file.File, path string) ([]*file.File, error)
• func Remove(ctx context.Context, root *file.File, path string) error
• func Set(ctx context.Context, root *file.File, path string, opts *SetOptions) (*file.File, error)
• func Walk(ctx context.Context, root *file.File, visit func(Entry) error) error
• type Entry
• type FS
  • func NewFS(ctx context.Context, root *file.File) FS
  • func (fp FS) Open(path string) (fs.File, error)
  • func (fp FS) ReadDir(path string) ([]fs.DirEntry, error)
  • func (fp FS) Sub(dir string) (fs.FS, error)
• type SetOptions

Variables

var (
	// ErrEmptyPath is reported by Set when given an empty path.
	ErrEmptyPath = errors.New("empty path")

	// ErrNilFile is reported by Set when passed a nil file.
	ErrNilFile = errors.New("nil file")

	// ErrSkipChildren signals to the Walk function that the children of the
	// current node should not be visited.
	ErrSkipChildren = errors.New("skip child files")
)

Functions

func Open

func Open(ctx context.Context, root *file.File, path string) (*file.File, error)

Open traverses the given slash-separated path sequentially from root, and returns the resulting file or file.ErrChildNotFound. An empty path yields root without error.

func OpenPath

func OpenPath(ctx context.Context, root *file.File, path string) ([]*file.File, error)

OpenPath traverses the given slash-separated path sequentially from root, and returns a slice of all the files along the path, not including root itself. If any element of the path does not exist, OpenPath returns the prefix that was found along with an file.ErrChildNotFound error.

func Remove

func Remove(ctx context.Context, root *file.File, path string) error

Remove removes the file at the given slash-separated path beneath root. If any component of the path does not exist, it returns file.ErrChildNotFound.

func Set

func Set(ctx context.Context, root *file.File, path string, opts *SetOptions) (*file.File, error)

Set traverses the given slash-separated path sequentially from root and inserts a file at the end of it. An empty path is an error (ErrEmptyPath).

If opts.Create is true, any missing path entries are created; otherwise it is an error (file.ErrChildNotFound) if any path element except the last does not exist.

If opts.File != nil, that file is inserted at the end of the path; otherwise if opts.Create is true, a new empty file is inserted. If neither of these is true, Set reports ErrNilFile.

func Walk

func Walk(ctx context.Context, root *file.File, visit func(Entry) error) error

Walk walks the file tree rooted at root, depth-first, and calls visit with an entry for each file in the tree. The entry.Path gives the path of the file relative to the root. If an error occurred opening the file at that path, entry.File is nil and entry.Err contains the error; otherwise entry.File contains the file addressed by the path.

If visit reports an error other than ErrSkipChildren, traversal stops and that error is returned to the caller of Walk. If it returns ErrSkipChildren the walk continues but skips the descendant files of the current entry.

Types

type Entry

type Entry struct {
	Path string     // the path of this entry relative to the root
	File *file.File // the file for this entry (nil on error)
	Err  error
}

An Entry is the argument to the visit callback for the Walk function.

type FS

type FS struct {
	// contains filtered or unexported fields
}

FS implements the standard library fs.FS, fs.SubFS, and fs.ReadDirFS interfaces. Path traversal is rooted at a file assigned when the FS is created.

func NewFS

func NewFS(ctx context.Context, root *file.File) FS

NewFS constructs an FS rooted at the given file. The context is held by the FS and must be valid for the full extent of its use.

func (FS) Open

func (fp FS) Open(path string) (fs.File, error)

Open implements the fs.FS interface. The concrete type of the file returned by a successful Open call is *file.Cursor.

func (FS) ReadDir

func (fp FS) ReadDir(path string) ([]fs.DirEntry, error)

ReadDir implements the fs.ReadDirFS interface.

func (FS) Sub

func (fp FS) Sub(dir string) (fs.FS, error)

Sub implements the fs.SubFS interface.

type SetOptions

type SetOptions struct {
	// If true, create any path elements that do not exist along the path.
	Create bool

	// If not nil, this function is called for any intermediate path elements
	// created along the path. It is also called for the final element if a new
	// final element is not provided as File.
	SetStat func(*file.Stat)

	// If not nil, insert this element at the end of the path.  If nil, a new
	// empty file with default options is created.
	File *file.File
}

SetOptions control the behaviour of the Set function. A nil *SetOptions behaves as a zero-valued options structure.