vfs

package module
v0.0.0-...-3c572b2 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2019 License: Apache-2.0 Imports: 14 Imported by: 0

README

Virtual FileSystem (VFS) implemented in Go

Go Report Card Build Status GoDoc Coverage Status

Documentation

Index

Constants

View Source 
const (

	// RdOnlyFlag opens the file in read-only mode
	RdOnlyFlag OpenFlag = OpenFlag(os.O_RDONLY)

	// WrOnlyFlag opens the file in write-only mode
	WrOnlyFlag = OpenFlag(os.O_WRONLY)

	// RdWrFlag opens the file for reading and writing
	RdWrFlag = OpenFlag(os.O_RDWR)

	// AppendFlag will seek the open file to the end
	AppendFlag OpenFlag = OpenFlag(os.O_APPEND)

	// CreateFlag will create the file if it does not exist
	CreateFlag = OpenFlag(os.O_CREATE)

	// ExclFlag will prevent an existing file from being overwritten when CreateFlag is given
	ExclFlag = OpenFlag(os.O_EXCL)

	// TruncFlag will truncate a file when it is opened for writing
	TruncFlag = OpenFlag(os.O_TRUNC)
)
View Source 
const (
	// PathSeparator is the slash character
	PathSeparator = "/" // OS-specific path separator
)

Variables

View Source 
var (
	// ErrInvalidFlags indicates that the OpenFlags are set to an invalid combination.  For instance,
	// the O_WRONLY and O_RDWR flags were both set
	ErrInvalidFlags = errors.New("Invalid combination of flags")

	// ErrInvalidSeek indicates a seek that moves the offset before the beginning of the file
	ErrInvalidSeek = errors.New("seek before beginning of file")

	// ErrReadOnly indicates an operation that requires write flags was attempted on a file that
	// is open read-only
	ErrReadOnly = errors.New("file is open read only")

	// ErrWriteOnly is returned when an operation requiring read-only flags was attempted on a
	// file that was opened for writing
	ErrWriteOnly = errors.New("file is open write only")

	// ErrWhence is a seek error returned when an invalid whence value was passed to Seek.  The
	// valid whence values are io.SeekStart, io.SeekCurrent and io.SeekEnd
	ErrWhence = errors.New("invalid value for whence")

	// ErrExist is returned when a file exists but an exclusive create was attempted
	ErrExist = errors.New("file already exists")

	// ErrNotExist indicates a file was not found
	ErrNotExist = errors.New("no such file or directory")

	// ErrNotDir indicates a file is not a directory when a directory operation was
	// called (such as Readdirnames)
	ErrNotDir = errors.New("The path specified is not a directory")

	// ErrIsDir indicates a file is a directory, not a regular file.  This is returned
	// by directories when file I/O operations (read, write, seek) are called
	ErrIsDir = errors.New("The path specified is a directory")

	// ErrBadPattern indicates a pattern was malformed.
	ErrBadPattern = errors.New("syntax error in pattern")

	// ErrSize is returned when an invalid size is used.  For example, a negative size
	// given to the Truncate function
	ErrSize = errors.New("invalid size")

	// ErrClosed indicates a file was already closed and cannot be closed again
	ErrClosed = errors.New("file already closed")
)
View Source 
var ErrSkipDir = errors.New("skip this directory")

ErrSkipDir is used as a return value from WalkFuncs to indicate that the directory named in the call is to be skipped. It is not returned as an error by any function.

Functions

func Glob 

func Glob(fs FileSystem, pattern string) (matches []string, err error)

Glob returns the names of all files matching pattern or nil if there is no matching file. The pattern syntax is: 

pattern:
	{ term }
term:
	'*'         matches any sequence of non-Separator characters
	'?'         matches any single non-Separator character
	'[' [ '^' ] { character-range } ']'
	            character class (must be non-empty)
	c           matches character c (c != '*', '?', '\\', '[')
	'\\' c      matches character c

character-range:
	c           matches character c (c != '\\', '-', ']')
	'\\' c      matches character c
	lo '-' hi   matches character c for lo <= c <= hi

The pattern may describe hierarchical names such as /usr/*/bin/ed (assuming the Separator is '/').

Glob ignores file system errors such as I/O errors reading directories. The only possible returned error is ErrBadPattern, when pattern is malformed.

func IsError 

func IsError(want, got error) bool

IsError will check to see if got is the same type of error as want. If got is a *PathError then IsError will compare the underlying *PathError.Cause

func IsExist 

func IsExist(err error) bool

IsExist returns a boolean indicating whether the error is known to report that a file or directory already exists. It is satisfied by ErrExist as well as some syscall errors.

func IsNotExist 

func IsNotExist(err error) bool

IsNotExist returns a boolean indicating whether the error is known to report that a file or directory does not exist. It is satisfied by ErrNotExist as well as some syscall errors.

func MkdirAll 

func MkdirAll(fs FileSystem, dirname string, perm os.FileMode) error

MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The permission bits perm (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil.

func ReadFile 

func ReadFile(opener Opener, filename string) (data []byte, err error)

ReadFile reads the file named by filename, from the given filesystem, and returns the content A successful call returns err == nil, not err == EOF. Because ReadFile reads the whole file, it does not treat an EOF from Read as an error to be reported.

func Walk 

func Walk(fs FileSystem, root string, walkFn WalkFunc) error

Walk walks the file tree rooted at root, calling walkFn for each file or directory in the tree, including root. All errors that arise visiting files and directories are filtered by walkFn. The files are walked in lexical order, which makes the output deterministic but means that for very large directories Walk can be inefficient. Walk does not follow symbolic links.

func WriteFile 

func WriteFile(opener Opener, filename string, content []byte, perm os.FileMode) error

WriteFile writes data to a file named by filename. If the file does not exist, WriteFile creates it with permissions perm; otherwise WriteFile truncates it before writing.

Types

type Event 

type Event struct {
	Type  EventType
	Path  string
	Error error
}

func (*Event) String 

func (event *Event) String() string

type EventType 

type EventType uint32
const (
	CreateEvent EventType = 1 << iota
	ModifyEvent
	RemoveEvent
	RenameEvent
	AttributeEvent
	ErrorEvent
)

func (EventType) String 

func (i EventType) String() string

type File 

type File interface {
	io.ReadWriteSeeker

	// Name returns the name of the file as presented to Open.
	Name() string

	// Readdirnames reads and returns a slice of names from the directory f.
	//
	// If n > 0, Readdirnames returns at most n names. In this case, if
	// Readdirnames returns an empty slice, it will return a non-nil error
	// explaining why. At the end of a directory, the error is io.EOF.
	//
	// If n <= 0, Readdirnames returns all the names from the directory in
	// a single slice. In this case, if Readdirnames succeeds (reads all
	// the way to the end of the directory), it returns the slice and a
	// nil error. If it encounters an error before the end of the
	// directory, Readdirnames returns the names read until that point and
	// a non-nil error.
	Readdirnames(n int) (names []string, err error)

	// Readdir reads the contents of the directory associated with file and
	// returns a slice of up to n FileInfo values, as would be returned
	// by Lstat, in directory order. Subsequent calls on the same file will yield
	// further FileInfos.
	//
	// If n > 0, Readdir returns at most n FileInfo structures. In this case, if
	// Readdir returns an empty slice, it will return a non-nil error
	// explaining why. At the end of a directory, the error is io.EOF.
	//
	// If n <= 0, Readdir returns all the FileInfo from the directory in
	// a single slice. In this case, if Readdir succeeds (reads all
	// the way to the end of the directory), it returns the slice and a
	// nil error. If it encounters an error before the end of the
	// directory, Readdir returns the FileInfo read until that point
	// and a non-nil error.
	Readdir(n int) ([]os.FileInfo, error)
}

File represents an object that has most of the behaviour of an os.File

type FileSystem 

type FileSystem interface {
	Opener

	// Chmod changes the mode of the named file to mode.
	Chmod(filename string, mode os.FileMode) error

	// Create creates the named file with mode 0666 (before umask), truncating it if it already exists.  If
	// successful, an io.ReadWriteSeeker is returned
	Create(name string) (File, error)

	// Mkdir creates a new directory with the specified name and permission bits
	// (before umask). If there is an error, it will be of type *PathError.
	Mkdir(name string, perm os.FileMode) error

	// Remove removes the named file or (empty) directory. If there is an error,
	// it will be of type *PathError.
	Remove(name string) error

	// Rename renames (moves) oldpath to newpath.
	// If newpath already exists and is not a directory, Rename replaces it.
	// OS-specific restrictions may apply when oldpath and newpath are in different directories.
	// If there is an error, it will be of type *LinkError.
	Rename(oldpath, newpath string) error

	// Lstat returns a FileInfo describing the named file. If the file is a
	// symbolic link, the returned FileInfo describes the symbolic link.
	// Lstat makes no attempt to follow the link. If there is an error, it
	// will be of type *PathError.
	Lstat(name string) (os.FileInfo, error)

	// Stat returns the FileInfo structure describing file.
	Stat(filename string) (os.FileInfo, error)

	// Close will perform any implementation specific cleanup work and close the
	// filesystem.  It is assumed that the filesystem is unusable after being closed
	Close() error

	// Watcher will create a file watcher instance that can be used to watch
	// for events on paths of the file system.  The provided Event channel
	// must be initialized by the caller sized appropriately for buffering
	// events at the rate expected.  If the channel buffer becomes full a
	// Watcher will drop the event.  The provided channel will be closed by
	// the watcher instance when the watcher itself is closed
	Watcher(chan<- Event) (Watcher, error)
}

FileSystem is the primary interface that must be satisfied. A FileSystem abstracts away the basic operations of interacting with files including reading and writing files

func NewMemFs 

func NewMemFs() FileSystem

NewMemFs will instantiate a new in-memory virtual filesystem

func NewOsFs 

func NewOsFs(root string) FileSystem

NewOsFs will return a new FileSystem that is backed by the operating system functions in the 'os' package. The osfs filesystem will be rooted in the given path

func NewTempFs 

func NewTempFs() FileSystem

NewTempFs returns an Os backed filesystem rooted in a temp directory that is deleted when the filesystem is closed

type OpenFlag 

type OpenFlag int

OpenFlag is passed to Open functions to indicate any actions taken while opening a file

type Opener 

type Opener interface {
	// Open opens the named file for reading.  If successful, an io.ReadSeeker is returned
	Open(filename string) (File, error)

	// OpenFile is the generalized open call; most users will use Open or Create instead.
	// It opens the named file with specified flag (O_RDONLY etc.) and perm (before umask),
	// if applicable. If successful, an io.ReadWriteSeeker is returned.  If the OpenFlag was
	// set to O_RDONLY then the io.ReadWriteSeeker itself may not be writable.  This is
	// dependent on the implementation
	OpenFile(filename string, flag OpenFlag, perm os.FileMode) (File, error)
}

Opener is a FileSystem that has the ability to open files

type PathError 

type PathError struct {
	// Op is the name of the operation where the error occurred
	Op string

	// Path is the string path that caused the error
	Path string

	// Cause is the underlying error that occurred (ErrNotDir, ErrIsDir, etc)
	Cause error
}

PathError represents an error that occured while performing an operation on a given path

func (*PathError) Error 

func (pe *PathError) Error() string

Error returns information about the operation and path where an error occurred

type WalkFunc 

type WalkFunc func(path string, info os.FileInfo, err error) error

WalkFunc is the type of the function called for each file or directory visited by Walk. The path argument contains the argument to Walk as a prefix; that is, if Walk is called with "dir", which is a directory containing the file "a", the walk function will be called with argument "dir/a". The info argument is the os.FileInfo for the named path.

If there was a problem walking to the file or directory named by path, the incoming error will describe the problem and the function can decide how to handle that error (and Walk will not descend into that directory). In the case of an error, the info argument will be nil. If an error is returned, processing stops. The sole exception is when the function returns the special value ErrSkipDir. If the function returns ErrSkipDir when invoked on a directory, Walk skips the directory's contents entirely. If the function returns ErrSkipDir when invoked on a non-directory file, Walk skips the remaining files in the containing directory.

type Watcher 

type Watcher interface {
	Watch(path string) error
	Remove(path string) error
	Close() error
}

func Watch 

func Watch(fs FileSystem, path string, events chan<- Event) (watcher Watcher, err error)

Watch will setup a Watcher recursively watching the path and sending events down to the events channel.

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.