fsutil

Documentation

Overview

Package fsutil defines functions and interfaces for working with file systems. This package interoperates with and supplements the fs package in the standard library.

Index

• Constants
• Variables
• func MetaPrefix(pattern string) string
• func OpenRange(src fs.FS, name, etag string, off, width int64) (io.ReadCloser, error)
• func ToGlob(pattern string) (string, error)
• func ValidCaptureName(ident string) bool
• func VisitDir(f fs.FS, name, seek, pattern string, fn VisitDirFn) error
• func WalkDir(f fs.FS, name, seek, pattern string, fn WalkDirFn) error
• func WalkGlob(f fs.FS, seek, pattern string, walk WalkGlobFn) error
• type DirEntry
• type ETagFS
• type Matcher
  • func (m *Matcher) Expand(template string) ([]byte, error)
  • func (m *Matcher) Get(name string) string
  • func (m *Matcher) Match(pattern, name string) (bool, error)
• type NamedFile
  • func Named(f fs.File, name string) NamedFile
  • func OpenGlob(f fs.FS, pattern string) ([]NamedFile, error)
• type OpenRangeFS
• type VisitDirFS
• type VisitDirFn
• type WalkDirFn
• type WalkGlobFn

Constants

const MaxCaptureGroups = 8

MaxCaptureGroups is the maximum number of capture groups that can appear in a table name template.

Variables

var ErrBadPattern = errors.New("bad pattern")

ErrBadPattern is returned by functions when a bad pattern is encountered.

Functions

func MetaPrefix

func MetaPrefix(pattern string) string

MetaPrefix finds the longest directory path for which we can begin searching for a glob pattern.

func OpenRange

func OpenRange(src fs.FS, name, etag string, off, width int64) (io.ReadCloser, error)

OpenRange tries to open the byte range given by [off] to [off+width] of the file given by [name] with etag [etag].

The argument [src] must be either an OpenRangeFS or an ETagFS, and the file returned by [src.Open] must be either an io.ReaderAt or an io.Seeker.

func ToGlob

func ToGlob(pattern string) (string, error)

ToGlob converts a pattern like "foo-{bar}.json" into "foo-*.json".

func ValidCaptureName

func ValidCaptureName(ident string) bool

ValidCaptureName returns whether or not ident is a valid capture group name for a glob pattern.

func VisitDir

func VisitDir(f fs.FS, name, seek, pattern string, fn VisitDirFn) error

VisitDir calls fn for each entry in the directory specified by name, visiting each entry in lexicographical order.

If seek is provided, only entries with names lexically succeeding seek are visited.

If pattern is provided, only entries with names matching the pattern are visited.

If fn returns fs.SkipDir or fs.SkipAll, VisitDir returns immediately with a nil error.

If f implements VisitDirFS, f.VisitDir is called directly, allowing the implementation to use the seek and pattern arguments to accelerate directory listing if possible. Otherwise, this simply calls fs.ReadDir and then calls fn for each matching entry.

func WalkDir

func WalkDir(f fs.FS, name, seek, pattern string, fn WalkDirFn) error

WalkDir walks a file tree, calling fn for each file in the tree, including the root directory specified by name.

If seek is provided, only entries with paths lexically succeeding the seek path are visited.

If pattern is provided, only entries with paths matching the pattern are visited.

The name parameter and the optional seek and pattern parameters (if provided) must be valid paths according to fs.ValidPath or WalkDir will return an error.

WalkDir handles fs.SkipDir or fs.SkipAll returned by fn in the same way that fs.WalkDir does.

WalkDir is analogous to fs.WalkDir except that it uses VisitDir to walk the file tree, and accepts seek and pattern arguments which can be used to accelerate directory listing for file systems that implement VisitDirFS.

func WalkGlob

func WalkGlob(f fs.FS, seek, pattern string, walk WalkGlobFn) error

WalkGlob opens all of the non-directory files in f that match pattern. The seek parameter determines the full path at which walking begins, and pattern indicates the glob pattern against which file paths are matched before being passed to the walk callback.

WalkGlob uses WalkDir to walk the file tree. If it encounters an fs.DirEntry that implements fs.File, it will be passed to walk directly. Otherwise, fs.Open will be used.

Types

type DirEntry

type DirEntry interface {
	// Name is the file name of the file or
	// directory without additional path elements.
	Name() string
	// IsDir returns whether the entry is a
	// directory.
	IsDir() bool
	// Info returns the corresponding fs.FileInfo.
	Info() (fs.FileInfo, error)
}

A DirEntry is an entry from a directory visited by VisitDir. This is analogous to fs.DirEntry without the Type() method.

type ETagFS

type ETagFS interface {
	// ETag should return the ETag for the file
	// given by [name] with file info [info] that
	// has been produced by an [fs.Stat] call.
	ETag(name string, info fs.FileInfo) (string, error)
}

ETagFS is an fs.FS that is aware of ETags.

type Matcher

type Matcher struct {
	// Result holds the expanded template
	Result []byte // expanded template
	// contains filtered or unexported fields
}

Matcher holds the results of a call to match. The caller should copy out the results as needed, as the Result field will be reused across calls to match.

func (*Matcher) Expand

func (m *Matcher) Expand(template string) ([]byte, error)

Expand attempts to Expand a template from capture groups from the last call to match.

The resulting slice is reused by the matcher and may be invalidated by subsequent calls. The caller should arrange to copy the result if needed between calls.

func (*Matcher) Get

func (m *Matcher) Get(name string) string

Get gets a capture result from the last call to match. If a capture group with the given name was not found in the last call to match, this returns "".

func (*Matcher) Match

func (m *Matcher) Match(pattern, name string) (bool, error)

Match matches a pattern against the name. If template != "", this also attempts to expand the template with parts taken from name.

The pattern syntax is:

pattern:
  { term }
term:
  '*'         matches any sequence of characters
              within a path segment
  '?'         matches any single non-/ character
  '[' [ '^' ] { char-range } ']'
              character class (may not be empty)
  '{' ident '}'
              matches a non-empty sequence of characters
              within a segment and captures the result
  c           matches character c (c != '*', '\\')
  '\\' c      matches character c
char-range:
  c           matches character c (c != '\\', '-', ']')
  '\\' c      matches character c
  lo '-' hi   matches character c for lo <= c <= hi
ident:
  ident-char { ident-char }
ident-char:
  'a' - 'z' | 'A' - 'Z' | '0' - '9' | '_'

The template syntax is:

template:
  { term }
term:
  '$' '$'     expands to literal '$'
  '$' ident | '$' '{' ident '}'
              expands to the capture group
              named ident from pattern
  c           expands to character c (c != '$')
ident:
  ident-char { ident-char }
ident-char:
  'a' - 'z' | 'A' - 'Z' | '0' - '9' | '_'

Multi-character wildcard groups (* and {...}) will Match the shortest sequence possible. For example, the pattern "{x}-*-{y}" matched against "a-b-c-d" and expanded into the template "$x-y" will produce "a-c-d".

This returns ErrBadPattern if pattern is malformed or has more than MaxCaptureGroups capture groups.

type NamedFile

type NamedFile interface {
	fs.File
	Path() string
}

func Named

func Named(f fs.File, name string) NamedFile

Named produces a NamedFile with name from an ordinary fs.File.

func OpenGlob

func OpenGlob(f fs.FS, pattern string) ([]NamedFile, error)

OpenGlob performs a WalkGlob with the provided pattern and collects the results into a list of NamedFiles.

type OpenRangeFS

type OpenRangeFS interface {
	OpenRange(name, etag string, off, width int64) (io.ReadCloser, error)
}

OpenRangeFS is an fs.FS that can open a byte range of a named file at the same time that the etag of the file is checked against the etag of the file currently residing in the filesystem.

type VisitDirFS

type VisitDirFS interface {
	fs.FS
	VisitDir(name, seek, pattern string, fn VisitDirFn) error
}

VisitDirFS can be implemented by a file system that provides an optimized implementation of VisitDir.

VisitDirFS implementations do not need to to handle fs.SkipDir or fs.SkipAll specially; those errors may be returned directly if returned by fn.

type VisitDirFn

type VisitDirFn func(d DirEntry) error

VisitDirFn is called by VisitDir for each entry in a directory.

type WalkDirFn

type WalkDirFn func(path string, d DirEntry, err error) error

WalkDirFn is the callback called by WalkDir to visit each directory entry. It is analogous to fs.WalkDirFunc except that it takes a DirEntry from this package instead of fs.DirEntry.

type WalkGlobFn

type WalkGlobFn func(name string, file fs.File, err error) error

WalkGlobFn is the callback passed to WalkGlob that is called for each matching file.

If WalkGlob encounters an error opening a file, then WalkGlobFn is called with a nil file and the error encountered opening the file; WalkGlob will continue if the error returned from the walk function is nil. Similarly, if the WalkGlobFn returns a non-nil error, then walking will stop.