fs

README

Helpers to work with fs.FS

Globing

We use the excellent https://github.com/gobwas/glob to compile file listing patterns, and ** is supported to ignore the / delimiters

• Matcher a type alias of glob.Glob to keep the import-space clean
• GlobCompile compiles a list of patterns
• Glob walks a [fs.FS] and returns all matches of the specified patterns. If no pattern is provided all entries not giving a fs.Stat error will be returned.
• Match is similar to Glob but it takes a root value, which will be cleaned, and a list of compiled Matcher patterns. it will only fail if the root gives an error.
• MatchFunc is an alternative to Match which actually receives a checker function.

Paths

Clean

We offer an alternative to the standard [fs.Clean] which optionally supports paths starting with /, and also returns if the cleaned path satisfies [fs.ValidPath].

as leading ../ are supported, it can be used for concatenations and to clean absolute OS paths. /.. will be returned if the reduction lead to that.

Split

We also have a variant of [path.Split] which cleans the argument and splits dir and file without the trailing slash on dir.

Interfaces

This package provides aliases of the standard fs.FooFS and adds the missing ones to gain parity with the os package.

Aliases

• fs.FS
• fs.GlobFS
• fs.ReadDirFS
• fs.ReadFileFS
• fs.StatFS
• fs.SubFS

New

• ChmodFS
• ChtimesFS
• MkdirFS
• MkdirAllFS
• MkdirTempFS
• ReadlinkFS
• RemoveFS
• RemoveAllFS
• RenameFS
• SymlinkFS
• WriteFileFS

fs.File

• fs.File
• fs.ReadDirFile

Proxies

As this package is named fs and would shadow the standard io.fs package we include aliases and proxies of commonly used symbols.

Types

• fs.FileInfo
• fs.FileMode
• fs.DirInfo
• fs.PathError

Constants

• fs.ErrInvalid
• fs.ErrPermission
• fs.ErrExists
• fs.ErrNotExists
• fs.ErrClosed

Functions

• fs.ValidPath

Documentation

Overview

Package fs provides tools to work with fs.FS

Index

• Variables
• func Clean(path string) (string, bool)
• func Glob(fSys fs.FS, patterns ...string) ([]string, error)
• func Match(fSys fs.FS, root string, globs ...Matcher) ([]string, error)
• func MatchFunc(fSys fs.FS, root string, check func(string, fs.DirEntry) bool) ([]string, error)
• func ReadFile(fSys fs.FS, name string) ([]byte, error)
• func Split(path string) (dir, file string)
• func Stat(fSys fs.FS, name string) (fs.FileInfo, error)
• func ValidPath(name string) bool
• type ChmodFS
• type ChtimesFS
• type ClosedFile
  • func (*ClosedFile) Close() error
  • func (*ClosedFile) Read([]byte) (int, error)
  • func (*ClosedFile) Seek(int64, int) (int64, error)
  • func (f *ClosedFile) Stat() (fs.FileInfo, error)
  • func (*ClosedFile) Write([]byte) (int, error)
• type Closer
• type DirEntry
• type FS
• type File
• type FileInfo
• type FileMode
• type Flusher
• type GlobFS
• type Matcher
  • func GlobCompile(patterns ...string) ([]Matcher, error)
• type MkdirAllFS
• type MkdirFS
• type MkdirTempFS
• type PathError
• type ReadDirFS
• type ReadDirFile
• type ReadFileFS
• type ReadSeeker
• type Reader
• type ReadlinkFS
• type RemoveAllFS
• type RemoveFS
• type RenameFS
• type StatFS
• type SubFS
• type SymlinkFS
• type WriteCloseFlusher
• type WriteFileFS
• type WriteFlusher
• type Writer

Variables

var (
	// ErrInvalid is an alias of the standard [fs.ErrInvalid] constant.
	ErrInvalid = fs.ErrInvalid
	// ErrPermission is an alias of the standard [fs.ErrPermission] constant.
	ErrPermission = fs.ErrPermission
	// ErrExist is an alias of the standard [fs.ErrExist] constant.
	ErrExist = fs.ErrExist
	// ErrNotExist is an alias of the standard [fs.ErrNotExist] constant.
	ErrNotExist = fs.ErrNotExist
	// ErrClosed is an alias of the standard [fs.ErrClosed] constant.
	ErrClosed = fs.ErrClosed
)

Functions

func Clean

func Clean(path string) (string, bool)

Clean reduces a path and tells if it's a valid root for fs.FS operations.

func Glob

func Glob(fSys fs.FS, patterns ...string) ([]string, error)

Glob returns all entries matching any of the given patterns.

func Match

func Match(fSys fs.FS, root string, globs ...Matcher) ([]string, error)

Match returns all entries matching any of the given compiled glob patterns.

func MatchFunc

func MatchFunc(fSys fs.FS, root string, check func(string, fs.DirEntry) bool) ([]string, error)

MatchFunc returns all entries satisfying the given checker function. If no function is provided, all entries will be listed. Entries giving Stat error will be ignored.

func ReadFile

func ReadFile(fSys fs.FS, name string) ([]byte, error)

ReadFile is a proxy to the standard fs.ReadFile function which attempts to read the content of a file with a given name on the given file system.

func Split

func Split(path string) (dir, file string)

Split splits a path into two Clean fs.ValidPath components that make dir + "/" + file equivalent to the given path.

func Stat

func Stat(fSys fs.FS, name string) (fs.FileInfo, error)

Stat is a proxy to the standard fs.Stat function which attempts to get fs.FileInfo about the given name on the given file system.

func ValidPath

func ValidPath(name string) bool

ValidPath is a proxy to the standard fs.ValidPath which reports whether the given path name valid and clean for use in a call to Open().

Types

type ChmodFS

type ChmodFS interface {
	FS
	Chmod(path string, mode FileMode) error
}

ChmodFS is the interface implemented by a file system that provides the functionality of os.Chmod.

type ChtimesFS

type ChtimesFS interface {
	FS
	Chtimes(path string, atime, mtime time.Time) error
}

ChtimesFS is the interface implemented by a file system that provides the functionality of os.Chtimes.

type ClosedFile

type ClosedFile struct {
	FileInfo fs.FileInfo
}

ClosedFile always returns fs.ErrClosed

func (*ClosedFile) Close

func (*ClosedFile) Close() error

Close implements the fs.File interface, always succeeding as ClosedFile is always closed.

func (*ClosedFile) Read

func (*ClosedFile) Read([]byte) (int, error)

Read implements the io.ReadSeeker interface always returning fs.ErrClosed

func (*ClosedFile) Seek

func (*ClosedFile) Seek(int64, int) (int64, error)

Seek implements the io.ReadSeeker interface always returning fs.ErrClosed

func (*ClosedFile) Stat

func (f *ClosedFile) Stat() (fs.FileInfo, error)

Stat implements the fs.File interface, allowing the return of the original fs.FileInfo, or failing with fs.ErrInvalid if not known.

func (*ClosedFile) Write

func (*ClosedFile) Write([]byte) (int, error)

Write implements the io.Writer interface always returning fs.ErrClosed

type Closer

type Closer = io.Closer

Closer is an alias of the standard io.Closer interface.

type DirEntry

type DirEntry = fs.DirEntry

DirEntry is an alias of the standard fs.DirEntry type.

type FS

type FS = fs.FS

FS is an alias of the standard fs.FS interface.

type File

type File = fs.File

File is an alias of the standard fs.File interface.

type FileInfo

type FileInfo = fs.FileInfo

FileInfo is an alias of the standard fs.FileInfo type.

type FileMode

type FileMode = fs.FileMode

FileMode is an alias of the standard fs.FileMode type.

type Flusher

type Flusher interface {
	Flush() error
}

A Flusher implements the Flush() error interface to write whatever is left on the buffer.

type GlobFS

type GlobFS = fs.GlobFS

GlobFS is an alias of the standard fs.GlobFS interface.

type Matcher

type Matcher = glob.Glob

Matcher is a compiled globbing pattern from https://github.com/gobwas/glob

func GlobCompile

func GlobCompile(patterns ...string) ([]Matcher, error)

GlobCompile compiles a list of file globbing patterns using https://github.com/gobwas/glob

type MkdirAllFS

type MkdirAllFS interface {
	FS
	MkdirAll(path string, mode FileMode) error
}

MkdirAllFS is the interface implemented by a file system that provides the functionality of os.MkdirAll.

type MkdirFS

type MkdirFS interface {
	FS
	Mkdir(path string, mode FileMode) error
}

MkdirFS is the interface implemented by a file system that provides the functionality of os.Mkdir.

type MkdirTempFS

type MkdirTempFS interface {
	FS
	MkdirTemp(dir string, pattern string) error
}

MkdirTempFS is the interface implemented by a file system that provides the functionality of os.MkdirTemp.

type PathError

type PathError = fs.PathError

PathError is an alias of the standard fs.PathError type.

type ReadDirFS

type ReadDirFS = fs.ReadDirFS

ReadDirFS is an alias of the standard fs.ReadDirFS type.

type ReadDirFile

type ReadDirFile = fs.ReadDirFile

ReadDirFile is an alias of the standard fs.ReadDirFile interface.

type ReadFileFS

type ReadFileFS = fs.ReadFileFS

ReadFileFS is an alias of the standard fs.ReadFileFS type.

type ReadSeeker

type ReadSeeker = io.ReadSeeker

ReadSeeker is an alias of the standard io.ReadSeeker interface.

type Reader

type Reader = io.Reader

Reader is an alias of the standard io.Reader interface.

type ReadlinkFS

type ReadlinkFS interface {
	FS
	Readlink(path string) (string, error)
}

ReadlinkFS is the interface implemented by a file system that provides the functionality of os.Readlink.

type RemoveAllFS

type RemoveAllFS interface {
	FS
	RemoveAll(path string) error
}

RemoveAllFS is the interface implemented by a file system that provides the functionality of os.RemoveAll.

type RemoveFS

type RemoveFS interface {
	FS
	Remove(path string) error
}

RemoveFS is the interface implemented by a file system that provides the functionality of os.Remove.

type RenameFS

type RenameFS interface {
	FS
	Rename(oldPath, newPath string) error
}

RenameFS is the interface implemented by a file system that provides the functionality of os.Rename.

type StatFS

type StatFS = fs.StatFS

StatFS is an alias of the standard fs.StatFS type.

type SubFS

type SubFS = fs.SubFS

SubFS is an alias of the standard fs.ReadFileFS type.

type SymlinkFS

type SymlinkFS interface {
	FS
	Symlink(target, path string) error
}

SymlinkFS is the interface implemented by a file system that provides the functionality of os.Symlink.

type WriteCloseFlusher

type WriteCloseFlusher interface {
	Writer
	Closer
	Flusher
}

A WriteCloseFlusher implements io.Writer, io.Closer and Flusher.

type WriteFileFS

type WriteFileFS interface {
	FS
	WriteFile(path string, data []byte, perm FileMode) error
}

WriteFileFS is the interface implemented by a file system that provides the functionality of os.WriteFile.

type WriteFlusher

type WriteFlusher interface {
	Writer
	Flusher
}

A WriteFlusher implements io.Writer and Flusher.

type Writer

type Writer = io.Writer

Writer is an alias of the standard io.Writer interface.