billy

README

go-billy

The missing interface filesystem abstraction for Go. Billy implements an interface based on the os standard library, allowing to develop applications without dependency on the underlying storage. Make virtually free implement an mocks and testing over filesystem operations.

Billy was born as part of src-d/go-git project.

Installation

go get -u gopkg.in/src-d/go-billy.v2/...

Why billy?

The library billy deals with storage systems and Billy is the name of a well-known, IKEA bookcase. That's it.

Usage

Billy exposes filesystems using the Filesystem interface. Each filesystem implementation gives you a New method, whose arguments depend on the implementation itself, that returns a new Filesystem.

The following example caches in memory all readable files in a directory from any billy's filesystem implementation.

func LoadToMemory(origin billy.Filesystem, path string) (*memory.Memory, error) {
	memory := memory.New()

	files, err := origin.ReadDir("/")
	if err != nil {
		return nil, err
	}

	for _, file := range files {
		if file.IsDir() {
			continue
		}

		src, err := origin.Open(file.Name())
		if err != nil {
			return nil, err
		}

		dst, err := memory.Create(file.Name())
		if err != nil {
			return nil, err
		}

		if _, err = io.Copy(dst, src); err != nil {
			return nil, err
		}

		if err := dst.Close(); err != nil {
			return nil, err
		}

		if err := src.Close(); err != nil {
			return nil, err
		}
	}

	return memory, nil
}

License

MIT, see LICENSE

Documentation

Index

• Variables
• func RemoveAll(fs Filesystem, path string) error
• func WriteFile(fs Filesystem, filename string, data []byte, perm os.FileMode) error
• type BaseFile
  • func (f *BaseFile) Filename() string
  • func (f *BaseFile) IsClosed() bool
• type File
• type FileInfo
• type Filesystem

Variables

var (
	ErrClosed       = errors.New("file: Writing on closed file.")
	ErrReadOnly     = errors.New("this is a read-only filesystem")
	ErrNotSupported = errors.New("feature not supported")
)

Functions

func RemoveAll

func RemoveAll(fs Filesystem, path string) error

RemoveAll removes path and any children it contains. It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error).

func WriteFile

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

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

Types

type BaseFile

type BaseFile struct {
	BaseFilename string
	Closed       bool
}

func (*BaseFile) Filename

func (f *BaseFile) Filename() string

func (*BaseFile) IsClosed

func (f *BaseFile) IsClosed() bool

type File

type File interface {
	Filename() string
	IsClosed() bool
	io.Writer
	io.Reader
	io.Seeker
	io.Closer
}

File implements io.Closer, io.Reader, io.Seeker, and io.Writer> Provides method to obtain the file name and the state of the file (open or closed).

type FileInfo

type FileInfo os.FileInfo

type Filesystem

type Filesystem interface {
	Create(filename string) (File, error)
	Open(filename string) (File, error)
	OpenFile(filename string, flag int, perm os.FileMode) (File, error)
	Stat(filename string) (FileInfo, error)
	ReadDir(path string) ([]FileInfo, error)
	TempFile(dir, prefix string) (File, error)
	Rename(from, to string) error
	Remove(filename string) error
	MkdirAll(filename string, perm os.FileMode) error
	Join(elem ...string) string
	Dir(path string) Filesystem
	Base() string
}

Filesystem abstract the operations in a storage-agnostic interface. It allows you to: * Create files. * Open existing files. * Get info about files. * List files in a directory. * Get a temporal file. * Rename files. * Remove files. * Create directories. * Join parts of path. * Obtain a filesystem starting on a subdirectory in the current filesystem. * Get the base path for the filesystem. Each method implementation varies from implementation to implementation. Refer to the specific documentation for more info.