vfs

package module
v0.0.0-...-164487e Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2017 License: MPL-2.0 Imports: 18 Imported by: 0

README

vfs

vfs implements Virtual File Systems with read-write support in Go (golang)

GoDoc

Documentation

Overview

Package vfs implements Virtual File Systems with read-write support.

All implementatations use slash ('/') separated paths, with / representing the root directory. This means that to manipulate or construct paths, the functions in path package should be used, like path.Join or path.Dir. There's also no notion of the current directory nor relative paths. The paths /a/b/c and a/b/c are considered to point to the same element.

This package also implements some shorthand functions which might be used with any VFS implementation, providing the same functionality than functions in the io/ioutil, os and path/filepath packages: 

io/ioutil.ReadFile => ReadFile
io/ioutil.WriteFile => WriteFile
os.IsExist => IsExist
os.IsNotExist => IsNotExist
os.MkdirAll => MkdirAll
os.RemoveAll => RemoveAll
path/filepath.Walk => Walk

All VFS implementations are thread safe, so multiple readers and writers might operate on them at any time.

Index

Constants

View Source 
const (
	ModeCompress os.FileMode = 1 << 16
)

Variables

View Source 
var (
	// SkipDir is used by a WalkFunc to signal Walk that
	// it wans to skip the given directory.
	SkipDir = errors.New("skip this directory")
	// ErrReadOnly is returned from Write() on a read-only file.
	ErrReadOnly = errors.New("can't write to read only file")
	// ErrWriteOnly is returned from Read() on a write-only file.
	ErrWriteOnly = errors.New("can't read from write only file")
)
View Source 
var (
	// ErrReadOnlyFileSystem is the error returned by read only file systems
	// from calls which would result in a write operation.
	ErrReadOnlyFileSystem = errors.New("read-only filesystem")
)

Functions

func Clone 

func Clone(dst VFS, src VFS) error

Clone copies all the files from the src VFS to dst. Note that files or directories with all permissions set to 0 will be set to 0755 for directories and 0644 for files. If you need more granularity, use Walk directly to clone the file systems.

func Compress 

func Compress(fs VFS) error

Compress is a shorthand method for compressing all the files in a VFS. Note that not all file systems support transparent compression/decompression.

func IsExist 

func IsExist(err error) bool

IsExist returns wheter the error indicates that the file or directory already exists.

func IsNotExist 

func IsNotExist(err error) bool

IsExist returns wheter the error indicates that the file or directory does not exist.

func MkdirAll 

func MkdirAll(fs VFS, path string, perm os.FileMode) error

MkdirAll makes all directories pointed by the given path, using the same permissions for all of them. Note that MkdirAll skips directories which already exists rather than returning an error.

func ReadFile 

func ReadFile(fs VFS, path string) ([]byte, error)

ReadFile reads the file at the given path from the given fs, returning either its contents or an error if the file couldn't be read.

func RemoveAll 

func RemoveAll(fs VFS, path string) error

RemoveAll removes all files from the given fs and path, including directories (by removing its contents first).

func Walk 

func Walk(fs VFS, root string, fn WalkFunc) error

Walk iterates over all the files in the VFS which descend from the given root (including root itself), descending into any subdirectories. In each directory, files are visited in alphabetical order. The given function might chose to skip a directory by returning SkipDir.

func WriteFile 

func WriteFile(fs VFS, path string, data []byte, perm os.FileMode) error

WriteFile writes a file at the given path and fs with the given data and permissions. If the file already exists, WriteFile truncates it before writing. If the file can't be created, an error will be returned.

func WriteTar 

func WriteTar(w io.Writer, fs VFS) error

WriteTar writes the given VFS as a tar file to the given io.Writer.

func WriteTarGzip 

func WriteTarGzip(w io.Writer, fs VFS) error

WriteTarGzip writes the given VFS as a tar.gz file to the given io.Writer.

func WriteZip 

func WriteZip(w io.Writer, fs VFS) error

WriteZip writes the given VFS as a zip file to the given io.Writer.

Types

type Compressor 

type Compressor interface {
	IsCompressed() bool
	SetCompressed(c bool)
}

Compressor is the interface implemented by VFS files which can be transparently compressed and decompressed. Currently, this is only supported by the in-memory filesystems.

type Container 

type Container interface {
	// VFS returns the underlying VFS.
	VFS() VFS
}

Container is implemented by some file systems which contain another one.

type Dir 

type Dir struct {
	sync.RWMutex
	// Mode is the file or directory mode. Note that some filesystems
	// might ignore the permission bits.
	Mode os.FileMode
	// ModTime represents the last modification time to directory.
	ModTime time.Time
	// Entry names in this directory, in order.
	EntryNames []string
	// Entries in the same order as EntryNames.
	Entries []Entry
}

Type Dir represents an in-memory directory. Most in-memory VFS implementations should use this structure to represent their directories, in order to save work.

func (*Dir) Add 

func (d *Dir) Add(name string, entry Entry) error

Add ads a new entry to the directory. If there's already an entry ith the same name, an error is returned.

func (*Dir) FileMode 

func (d *Dir) FileMode() os.FileMode

func (*Dir) Find 

func (d *Dir) Find(name string) (Entry, int, error)

Find returns the entry with the given name and its index, or an error if an entry with that name does not exist in the directory.

func (*Dir) ModificationTime 

func (d *Dir) ModificationTime() time.Time

func (*Dir) Size 

func (d *Dir) Size() int64

func (*Dir) Type 

func (d *Dir) Type() EntryType

type Entry 

type Entry interface {
	// Type returns the entry type, either EntryTypeFile or
	// EntryTypeDir.
	Type() EntryType
	// Size returns the file size. For directories, it's always zero.
	Size() int64
	// FileMode returns the file mode as an os.FileMode.
	FileMode() os.FileMode
	// ModificationTime returns the last time the file or the directory
	// was modified.
	ModificationTime() time.Time
}

Entry is the interface implemented by the in-memory representations of files and directories.

type EntryInfo 

type EntryInfo struct {
	// Path is the full path to the entry in its VFS.
	Path string
	// Entry is the instance used by the VFS to represent
	// the in-memory entry.
	Entry Entry
}

EntryInfo implements the os.FileInfo interface wrapping a given File and its Path in its VFS.

func (*EntryInfo) IsDir 

func (info *EntryInfo) IsDir() bool

func (*EntryInfo) ModTime 

func (info *EntryInfo) ModTime() time.Time

func (*EntryInfo) Mode 

func (info *EntryInfo) Mode() os.FileMode

func (*EntryInfo) Name 

func (info *EntryInfo) Name() string

func (*EntryInfo) Size 

func (info *EntryInfo) Size() int64

func (*EntryInfo) Sys 

func (info *EntryInfo) Sys() interface{}

Sys returns the underlying Entry.

type EntryType 

type EntryType uint8

EntryType indicates the type of the entry. 

const (
	// EntryTypeFile indicates the entry is a file.
	EntryTypeFile EntryType = iota + 1
	// EntryTypeDir indicates the entry is a directory.
	EntryTypeDir
)

type File 

type File struct {
	sync.RWMutex
	// Data contains the file data.
	Data []byte
	// Mode is the file or directory mode. Note that some filesystems
	// might ignore the permission bits.
	Mode os.FileMode
	// ModTime represents the last modification time to the file.
	ModTime time.Time
}

Type File represents an in-memory file. Most in-memory VFS implementations should use this structure to represent their files, in order to save work.

func (*File) FileMode 

func (f *File) FileMode() os.FileMode

func (*File) ModificationTime 

func (f *File) ModificationTime() time.Time

func (*File) Size 

func (f *File) Size() int64

func (*File) Type 

func (f *File) Type() EntryType

type FileInfos 

type FileInfos []os.FileInfo

FileInfos represents an slice of os.FileInfo which implements the sort.Interface. This type is only exported for users who want to implement their own filesystems, since VFS.ReadDir requires the returned []os.FileInfo to be sorted by name.

func (FileInfos) Len 

func (f FileInfos) Len() int

func (FileInfos) Less 

func (f FileInfos) Less(i, j int) bool

func (FileInfos) Swap 

func (f FileInfos) Swap(i, j int)

type Mounter 

type Mounter struct {
	// contains filtered or unexported fields
}

Mounter implements the VFS interface and allows mounting different virtual file systems at arbitraty points, working much like a UNIX filesystem. Note that the first mounted filesystem must be always at "/".

func (*Mounter) Lstat 

func (m *Mounter) Lstat(path string) (os.FileInfo, error)

func (*Mounter) Mkdir 

func (m *Mounter) Mkdir(path string, perm os.FileMode) error

func (*Mounter) Mount 

func (m *Mounter) Mount(fs VFS, point string) error

Mount mounts the given filesystem at the given mount point. Unless the mount point is /, it must be an already existing directory.

func (*Mounter) Open 

func (m *Mounter) Open(path string) (RFile, error)

func (*Mounter) OpenFile 

func (m *Mounter) OpenFile(path string, flag int, perm os.FileMode) (WFile, error)

func (*Mounter) ReadDir 

func (m *Mounter) ReadDir(path string) ([]os.FileInfo, error)

func (*Mounter) Remove 

func (m *Mounter) Remove(path string) error

func (*Mounter) Stat 

func (m *Mounter) Stat(path string) (os.FileInfo, error)

func (*Mounter) String 

func (m *Mounter) String() string

func (*Mounter) Umount 

func (m *Mounter) Umount(point string) error

Umount umounts the filesystem from the given mount point. If there are other filesystems mounted below it or there's no filesystem mounted at that point, an error is returned.

type Opener 

type Opener interface {
	// Open returns a readable file at the given path. See also
	// the shorthand function ReadFile.
	Open(path string) (RFile, error)
	// OpenFile returns a readable and writable file at the given
	// path. Note that, depending on the flags, the file might be
	// only readable or only writable. See also the shorthand
	// function WriteFile.
	OpenFile(path string, flag int, perm os.FileMode) (WFile, error)
}

Opener is the interface which specifies the methods for opening a file. All the VFS implementations implement this interface.

type RFile 

type RFile interface {
	io.Reader
	io.Seeker
	io.Closer
}

RFile is the interface implemented by the returned value from a VFS Open method. It allows reading and seeking, and must be closed after use.

func NewRFile 

func NewRFile(f *File) (RFile, error)

NewRFile returns a RFile from a *File.

type TemporaryVFS 

type TemporaryVFS interface {
	VFS
	// Root returns the root directory for the temporary VFS.
	Root() string
	// Close removes all the files in temporary VFS.
	Close() error
}

TemporaryVFS represents a temporary on-disk file system which can be removed by calling its Close method.

func TmpFS 

func TmpFS(prefix string) (TemporaryVFS, error)

TmpFS returns a temporary file system with the given prefix and its root directory name, which might be empty. The temporary file system is created in the default temporary directory for the operating system. Once you're done with the temporary filesystem, you might can all its files by calling its Close method.

type VFS 

type VFS interface {
	Opener
	// Lstat returns the os.FileInfo for the given path, without
	// following symlinks.
	Lstat(path string) (os.FileInfo, error)
	// Stat returns the os.FileInfo for the given path, following
	// symlinks.
	Stat(path string) (os.FileInfo, error)
	// ReadDir returns the contents of the directory at path as an slice
	// of os.FileInfo, ordered alphabetically by name. If path is not a
	// directory or the permissions don't allow it, an error will be
	// returned.
	ReadDir(path string) ([]os.FileInfo, error)
	// Mkdir creates a directory at the given path. If the directory
	// already exists or its parent directory does not exist or
	// the permissions don't allow it, an error will be returned. See
	// also the shorthand function MkdirAll.
	Mkdir(path string, perm os.FileMode) error
	// Remove removes the item at the given path. If the path does
	// not exists or the permissions don't allow removing it or it's
	// a non-empty directory, an error will be returned. See also
	// the shorthand function RemoveAll.
	Remove(path string) error
	// String returns a human-readable description of the VFS.
	String() string
}

VFS is the interface implemented by all the Virtual File Systems.

func Chroot 

func Chroot(root string, fs VFS) (VFS, error)

Chroot returns a new VFS wrapping the given VFS, making the given directory the new root ("/"). Note that root must be an existing directory in the given file system, otherwise an error is returned.

func FS 

func FS(root string) (VFS, error)

FS returns a VFS at the given path, which must be provided as native path of the current operating system. The path might be either absolute or relative, but the fileSystem will be anchored at the absolute path represented by root at the time of the function call.

func Map 

func Map(files map[string]*File) (VFS, error)

Map returns an in-memory file system using the given files argument to populate it (which might be nil). Note that the files map does not need to contain any directories, they will be created automatically. If the files contain conflicting paths (e.g. files named a and a/b, thus making "a" both a file and a directory), an error will be returned.

func Memory 

func Memory() VFS

Memory returns an empty in memory VFS.

func Open 

func Open(filename string) (VFS, error)

Open returns an in-memory VFS initialized with the contents of the given filename, which must have one of the following extensions:

  • .zip
  • .tar
  • .tar.gz
  • .tar.bz2

func ReadOnly 

func ReadOnly(fs VFS) VFS

ReadOnly returns a read-only filesystem wrapping the given fs.

func Rewriter 

func Rewriter(fs VFS, rewriter func(oldPath string) (newPath string)) VFS

Rewriter returns a file system which uses the provided function to rewrite paths.

func Tar 

func Tar(r io.Reader) (VFS, error)

Tar returns an in-memory VFS initialized with the contents of the .tar file read from the given io.Reader.

func TarBzip2 

func TarBzip2(r io.Reader) (VFS, error)

TarBzip2 returns an in-memory VFS initialized with the contents of then .tar.bz2 file read from the given io.Reader.

func TarGzip 

func TarGzip(r io.Reader) (VFS, error)

TarGzip returns an in-memory VFS initialized with the contents of the .tar.gz file read from the given io.Reader.

func Zip 

func Zip(r io.Reader, size int64) (VFS, error)

Zip returns an in-memory VFS initialized with the contents of the .zip file read from the given io.Reader. Since archive/zip requires an io.ReaderAt rather than an io.Reader, and a known size, Zip will read the whole file into memory and provide its own buffering if r does not implement io.ReaderAt or size is <= 0.

type WFile 

type WFile interface {
	io.Reader
	io.Writer
	io.Seeker
	io.Closer
}

WFile is the interface implemented by the returned value from a VFS OpenFile method. It allows reading, seeking and writing, and must be closed after use. Note that, depending on the flags passed to OpenFile, the Read or Write methods might always return an error (e.g. if the file was opened in read-only or write-only mode).

func NewWFile 

func NewWFile(f *File, read bool, write bool) (WFile, error)

NewWFile returns a WFile from a *File.

type WalkFunc 

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

WalkFunc is the function type used by Walk to iterate over a VFS.

Source Files

View all Source files

Directories

Path Synopsis
Package buildfs allows plugging a VFS into a go/build.Context.
 Package buildfs allows plugging a VFS into a go/build.Context.

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.