filesystem

package
v0.0.0-...-698a17d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 6, 2023 License: BSD-3-Clause Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PermissionBits = fs.ModePerm
)

Variables

View Source 
var (
	ErrInvalid    = fs.ErrInvalid
	ErrPermission = fs.ErrPermission
	ErrExist      = fs.ErrExist
	ErrNotExist   = fs.ErrNotExist
	ErrClosed     = fs.ErrClosed
)

Functions

func CopyAll 

func CopyAll(
	srcFS MinimalFileSystem,
	srcPath string,
	destFS MinimalFileSystem,
	destPath string,
	options ...Option,
) error

Recursively copy src to dest.

Behavior:

  1. src is a file: a. dest does not exist: copy src file to dest (try to create using src's permission if caller didn't specify file perm option) b. dest is a file: overwrite dest file with src (use dest's original permission) c. dest is a directory: error
  2. src is a directory: a. dest does not exist: recursively copy src directory to dest (try to create using src's permissions if caller didn't specify file/dir perm options) b. dest exist: error

(If we ignore file/directory metadata, e.g., permission, fs.Rename(src, dest) should be equivalent to fs.CopyAll(src, dest) follow by fs.RemoveAll(src).

This implementation only uses only MinimalFileSystem. File system implementor may use this to implement the CopyAll method.

func CopyFile 

func CopyFile(
	srcFS MinimalFileSystem,
	srcPath string,
	destFS MinimalFileSystem,
	destPath string,
	options ...Option,
) error

This Copies a src file to dest. If dest is a file, the file content is overwritten. if dest is a directory, this returns an error.

This implementation only uses only MinimalFileSystem. File system implementor may use this to implement the CopyFile method.

func Glob 

func Glob(
	minFS MinimalFileSystem,
	pattern string,
	options ...Option,
) (
	[]string,
	error,
)

A Glob implementation using only MinimalFileSystem. File system implementor may use this to implement the Glob method.

func IsExistError 

func IsExistError(err error) bool

func IsInvalidArgumentError 

func IsInvalidArgumentError(err error) bool

func IsNotExistError 

func IsNotExistError(err error) bool

func IsPermissionError 

func IsPermissionError(err error) bool

func MkdirAll 

func MkdirAll(
	minFS MinimalFileSystem,
	dirPath string,
	options ...Option,
) error

A MkdirAll implementation using only MinimalFileSystem. File system implementor may use this to implement the MkdirAll method.

func NewExistError 

func NewExistError(
	op string,
	path string,
	messageTemplate string,
	args ...any,
) error

func NewInvalidArgumentError 

func NewInvalidArgumentError(
	op string,
	path string,
	messageTemplate string,
	args ...any,
) error

func NewNotExistError 

func NewNotExistError(
	op string,
	path string,
	messageTemplate string,
	args ...any,
) error

func NewPermissionError 

func NewPermissionError(
	op string,
	path string,
	messageTemplate string,
	args ...any,
) error

func ReadFile 

func ReadFile(
	minFS MinimalFileSystem,
	filePath string,
	options ...Option,
) (
	[]byte,
	error,
)

A ReadFile implementation using only MinimalFileSystem. File system implementor may use this to implement the ReadFile method.

func RemoveAll 

func RemoveAll(
	minFS MinimalFileSystem,
	filePath string,
	options ...Option,
) error

A RemoveAll implementation using only MinimalFileSystem. File system implementor may use this to implement the RemoveAll method.

func ToFS 

func ToFS(fileSystem MinimalFileSystem, options []Option) fs.FS

This returns a fs.FS object usable by io/fs's functions that uses fs.FS as input. In general, this should not be used directly.

func WalkDir 

func WalkDir(
	minFS MinimalFileSystem,
	dirPath string,
	fn WalkDirFunc,
	options ...Option,
) error

A WalkDir implementation using only MinimalFileSystem. File system implementor may use this to implement the WalkDir method.

func WrapError 

func WrapError(
	op string,
	path string,
	err error,
) error

func WrapErrorf 

func WrapErrorf(
	op string,
	path string,
	err error,
	messageTemplate string,
	args ...any,
) error

func WriteFile 

func WriteFile(
	minFS MinimalFileSystem,
	filePath string,
	data []byte,
	options ...Option,
) error

A WriteFile implementation using only MinimalFileSystem. File system implementor may use this to implement the WriteFile method.

Types

type DirEntry 

type DirEntry = fs.DirEntry

Note: DirEntry's Type()/Info() usage should generally be avoided since type/info may not be fully populated. User should use Stat the actual file for accurate information.

func ReadDir 

func ReadDir(
	minFS MinimalFileSystem,
	dirPath string,
	options ...Option,
) (
	[]DirEntry,
	error,
)

A ReadDir implementation using only MinimalFileSystem. File system implementor may use this to implement the ReadDir method.

type FileInfo 

type FileInfo = fs.FileInfo

func Stat 

func Stat(
	minFS MinimalFileSystem,
	filePath string,
	options ...Option,
) (
	FileInfo,
	error,
)

A Stat implementation using only MinimalFileSystem. File system implementor may use this to implement the Stat method.

type FileMode 

type FileMode = fs.FileMode

Note: In general, only the PermissionBits in FileMode can be specified as argument; the file system implementator should ignore the non-permission bits. FileInfo/DirEntry's Mode() may include non-permission bits.

type FileReader 

type FileReader = fs.ReadDirFile

XXX: Maybe support Seek

Note: Unlike FileSystem's ReadDir, FileReader's ReadDir is unsorted.

Note: DirEntry's IsDir/Type/Info maybe not be fully populated by file system implementation. User must Stat the actual file for accurate information.

type FileSystem 

type FileSystem interface {
	MinimalFileSystem

	// This returns the path's FileInfo.
	Stat(filePath string, options ...Option) (FileInfo, error)

	// This returns a directory's content, sorted by filename.
	ReadDir(dirPath string, options ...Option) ([]DirEntry, error)

	// This walks a directory.
	WalkDir(dirPath string, fn WalkDirFunc, options ...Option) error

	// This globs a file pattern.
	Glob(pattern string, options ...Option) ([]string, error)

	// This returns a file's content.
	ReadFile(filePath string, options ...Option) ([]byte, error)

	// This writes a file.
	WriteFile(
		filePath string,
		data []byte,
		options ...Option,
	) error

	// Copy the file at srcFilePath to destFilePath.  If destFilePath is a file,
	// the file content is overwritten.  If destFilePath is a directory, this
	// returns error.
	CopyFile(
		srcFilePath string,
		destFilePath string,
		options ...Option,
	) error

	// Recursively copy src to dest.
	CopyAll(
		srcPath string,
		destPath string,
		options ...Option,
	) error

	// This recursively creates the directory dirPath.
	MkdirAll(dirPath string, options ...Option) error

	// This removes all files under filePath.
	RemoveAll(filePath string, options ...Option) error
}

FileSystem specify additional operations on top of MinimalFileSystem for ease of use.

Note: all path input must be absolute (i.e., not relative to local working directory) since the working directory is meaningless to all but the local file system implementation rooted at '/'. File system implementator must guard against non-absolute paths. 

var Local FileSystem = NewLocalFileSystem()

func ExtendMinimalFileSystem 

func ExtendMinimalFileSystem(minFS MinimalFileSystem) FileSystem

Given a MinimalFileSystem, which may or may not have fully implemented the full FileSystem interface, return a full FileSystem implementation.

func NewLocalFileSystem 

func NewLocalFileSystem() FileSystem

func NewReadOnlyFileSystem 

func NewReadOnlyFileSystem(fs FileSystem) FileSystem

func NewSubFileSystem 

func NewSubFileSystem(baseFS FileSystem, baseRootDir string) FileSystem

Return a new sub file system rooted at baseRootDir. Files outside of baseRootDir are inaccessible from the sub file system.

type FileWriter 

type FileWriter = io.WriteCloser

XXX: Maybe support Sync

type MinimalFileSystem 

type MinimalFileSystem interface {
	// Equivalent to path/filepath.Abs.  If the file system implementation
	// does not support working directory, this should return error when the
	// path is not absolute.  This should always return error when filePath
	// is an empty string.
	Abs(filePath string) (string, error)

	// This returns a FileReader that behaves as if it was opened with O_RDONLY.
	Open(filePath string, options ...Option) (FileReader, error)

	// This returns a FileWriter that behaves as if it was opened with
	// O_CREATE | O_WRONLY | O_TRUNC.  The default permission should be 0664 or
	// tighter if the file system supports unix style permission.
	//
	// If a file perm option is provided, the file system implementation may
	// place additional (umask) restriction on the provided permission.
	//
	// This returns an error if Create is not supported.
	Create(filePath string, options ...Option) (FileWriter, error)

	// This returns a FileWriter that behaves as if it was opened with
	// O_CREATE |O_WRONLY | O_APPEND.  The default permission should be 0664
	// or tighter if the file system supports unix style permission.
	//
	// If a file perm option is provided, the file system implementation may
	// place additional (umask) restriction on the provided permission.
	//
	// This returns an error if Append is not supported.
	Append(filePath string, options ...Option) (FileWriter, error)

	// This creates a directory.  The default permission should be 0775 or
	// tighter.
	//
	// If a dir perm option is provided, the file system implementation may
	// place additional (umask) restriction on the provided permission.
	//
	// This returns an error if Mkdir is not supported.
	Mkdir(dirPath string, options ...Option) error

	// This renames a file.
	//
	// This returns an error if Mkdir is not supported.
	// Note that Rename may not be an atomic operation (the implementation
	// could for example copy then delete).
	Rename(srcPath string, destPath string, options ...Option) error

	// This remove a file or an empty directory.
	//
	// This returns an error if Remove is not supported.
	Remove(filePath string, options ...Option) error

	// Intended for changing permission bits.  The file system implementor
	// should ignore non-permission file mode bits.
	Chmod(filePath string, perm FileMode, options ...Option) error
}

Similar to fs.FS, but extended to support write operations. All methods should return error on empty path string inputs.

Note: Windows-style backslash (and volume named) paths are not supported. User should use golang's "path" (instead of "path/filepath") for path manipulation, and use the file system's Abs method to resolve non-absolute paths.

Note: This is the minimal set of operations that the file system implementor must provide (The implementation should return error for unsupported functionalities). If the file system implementation does not implement the full set of FileSystem operations, the implementator should use ExtendMinimalFileSystem() to provide implementation for the remaining operations.

type Option 

type Option func(Options) error

Note that the user may pass in options not associated to the file system's method implementation, in which case, the implementation should ignore the option.

func WithContext 

func WithContext(ctx context.Context) Option

Applicable to all file system methods.

func WithDirPerm 

func WithDirPerm(perm FileMode) Option

Applicable to directory creation operations (Mkdir, MkdirAll, and CopyAll). File system implementation may place additional (umask) restriction on the given permission.

func WithFilePerm 

func WithFilePerm(perm FileMode) Option

Applicable to file creation operations (Create, Append, WriteFile, CopyFile, and CopyAll). File system implementation may place additional (umask) restriction on the given permission.

func WithLocalOpenFileFlag 

func WithLocalOpenFileFlag(flag int) Option

Applicable to Create Append, and WriteFile.

type Options 

type Options interface {
	SetContext(ctx context.Context)

	// File and dir permissions need to be separate in order to support Copy.
	SetFilePerm(perm FileMode)
	SetDirPerm(perm FileMode)

	// All other file system implementation specific options should be set via
	// this method (Standardizing the option setting interface simplifies
	// file system api forwarding/proxying).  File system implementation should
	// ignore unrelated options.  SetOption should only return error when
	// optionValue is invalid.
	SetOption(fsImplName string, optionName string, optionValue string) error
}

Standard options across all implementations. (The implementation may choose to ignore these options, but must expose the api anyway).

type PathError 

type PathError = fs.PathError

type WalkDirFunc 

type WalkDirFunc = fs.WalkDirFunc

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.