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
- type NamedFile
- 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 ¶
MetaPrefix finds the longest directory path for which we can begin searching for a glob pattern.
func OpenRange ¶
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 ValidCaptureName ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 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 ¶
VisitDirFn is called by VisitDir for each entry in a directory.
type WalkDirFn ¶
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 ¶
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.
Source Files