afero

README

afero-lite

A lightweight FileSystem Abstraction System for Go

Modifications

This is afero, reorganized to avoid bloated binaries when a subset of features is used. The following modifications are made:

• tests removed
  • allfiles ending _test.go, as well as gcs_mocks.go
  • count on afero to do the testing
• full package created
  • all of afero moved here except that related to MemMapFs and HttpFs
• mem package now contains NewMemMapFs
• httpfs package created, with NewHttpFs moved here

Thus, the root package only defines the interfaces and allows using the OsFs via NewOsFs. This should keep the amount of imported code to a bare minimum if all you need is to abstract os usage. Use httpfs, knowing that net/http will be imported and increase binary size unless you need it. Use full for all other afero utilities.

Usage

The top-level package is simply named afero:

package main

import "github.com/tbhartman/afero-lite"

func main() {
	var myfs afero.Fs
	myfs = afero.NewOsFs()
	myfs.Stat("myfile")
}

If you need other functionality, import from full, and use as afero:

package main

import (
	"github.com/tbhartman/afero-lite/full"
)

func main() {
	var myfs afero.Fs
	myfs = afero.NewOsFs()
	myfs = afero.NewBasePath(myfs, "basepath")
	myfs.Stat("myfile")
}

If you need a MemMapFs, import from mem:

package main

import (
	"github.com/tbhartman/afero-lite/mem"
)

func main() {
	_ = mem.NewMemMapFs()
}

If you need a HttpFs, import from httpfs:

package main

import (
	"github.com/tbhartman/afero-lite/httpfs"
)

func main() {
	_ = httpfs.NewHttpFs()
}

Versioning

Versioning will follow major and minor releases of afero, but the patch version will update independently as patches to this repo are required!

Update instructions

This is all manual right now :(

• remove _test.go and mock.go files
• create httpfs and full directories
• move httpfs.go to httpfs
• move memmap.go to mem
• move all other root go files to full
• copy back some files to root:
  • afero.go
  • const_bsds.go
  • const_win_unix.go
  • lstater.go
  • os.go
  • symlink.go
  • unionFile.go
  • util.go
• keep only FilePathSeparator in root util.go
• remove copy* functions from root unionFile.go
• fix build errors
  • httpfs.go will need to import and use afero
  • memmap.go will need to import and use afero

Documentation

Index

• Constants
• Variables
• type Afero
• type DirsMerger
• type File
• type Fs
  • func NewOsFs() Fs
• type LinkReader
• type Linker
• type Lstater
• type OsFs
  • func (OsFs) Chmod(name string, mode os.FileMode) error
  • func (OsFs) Chown(name string, uid, gid int) error
  • func (OsFs) Chtimes(name string, atime time.Time, mtime time.Time) error
  • func (OsFs) Create(name string) (File, error)
  • func (OsFs) LstatIfPossible(name string) (os.FileInfo, bool, error)
  • func (OsFs) Mkdir(name string, perm os.FileMode) error
  • func (OsFs) MkdirAll(path string, perm os.FileMode) error
  • func (OsFs) Name() string
  • func (OsFs) Open(name string) (File, error)
  • func (OsFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)
  • func (OsFs) ReadlinkIfPossible(name string) (string, error)
  • func (OsFs) Remove(name string) error
  • func (OsFs) RemoveAll(path string) error
  • func (OsFs) Rename(oldname, newname string) error
  • func (OsFs) Stat(name string) (os.FileInfo, error)
  • func (OsFs) SymlinkIfPossible(oldname, newname string) error
• type Symlinker
• type UnionFile
  • func (f *UnionFile) Close() error
  • func (f *UnionFile) Name() string
  • func (f *UnionFile) Read(s []byte) (int, error)
  • func (f *UnionFile) ReadAt(s []byte, o int64) (int, error)
  • func (f *UnionFile) Readdir(c int) (ofi []os.FileInfo, err error)
  • func (f *UnionFile) Readdirnames(c int) ([]string, error)
  • func (f *UnionFile) Seek(o int64, w int) (pos int64, err error)
  • func (f *UnionFile) Stat() (os.FileInfo, error)
  • func (f *UnionFile) Sync() (err error)
  • func (f *UnionFile) Truncate(s int64) (err error)
  • func (f *UnionFile) Write(s []byte) (n int, err error)
  • func (f *UnionFile) WriteAt(s []byte, o int64) (n int, err error)
  • func (f *UnionFile) WriteString(s string) (n int, err error)

Constants

const BADFD = syscall.EBADFD

const FilePathSeparator = string(filepath.Separator)

Filepath separator defined by os.Separator.

Variables

var (
	ErrFileClosed        = errors.New("File is closed")
	ErrOutOfRange        = errors.New("Out of range")
	ErrTooLarge          = errors.New("Too large")
	ErrFileNotFound      = os.ErrNotExist
	ErrFileExists        = os.ErrExist
	ErrDestinationExists = os.ErrExist
)

var ErrNoReadlink = errors.New("readlink not supported")

ErrNoReadlink is the error that will be wrapped in an os.Path if a file system does not support the readlink operation either directly or through its delegated filesystem. As expressed by support for the LinkReader interface.

var ErrNoSymlink = errors.New("symlink not supported")

ErrNoSymlink is the error that will be wrapped in an os.LinkError if a file system does not support Symlink's either directly or through its delegated filesystem. As expressed by support for the Linker interface.

Types

type Afero

type Afero struct {
	Fs
}

type DirsMerger

type DirsMerger func(lofi, bofi []os.FileInfo) ([]os.FileInfo, error)

DirsMerger is how UnionFile weaves two directories together. It takes the FileInfo slices from the layer and the base and returns a single view.

type File

type File interface {
	io.Closer
	io.Reader
	io.ReaderAt
	io.Seeker
	io.Writer
	io.WriterAt

	Name() string
	Readdir(count int) ([]os.FileInfo, error)
	Readdirnames(n int) ([]string, error)
	Stat() (os.FileInfo, error)
	Sync() error
	Truncate(size int64) error
	WriteString(s string) (ret int, err error)
}

File represents a file in the filesystem.

type Fs

type Fs interface {
	// Create creates a file in the filesystem, returning the file and an
	// error, if any happens.
	Create(name string) (File, error)

	// Mkdir creates a directory in the filesystem, return an error if any
	// happens.
	Mkdir(name string, perm os.FileMode) error

	// MkdirAll creates a directory path and all parents that does not exist
	// yet.
	MkdirAll(path string, perm os.FileMode) error

	// Open opens a file, returning it or an error, if any happens.
	Open(name string) (File, error)

	// OpenFile opens a file using the given flags and the given mode.
	OpenFile(name string, flag int, perm os.FileMode) (File, error)

	// Remove removes a file identified by name, returning an error, if any
	// happens.
	Remove(name string) error

	// RemoveAll removes a directory path and any children it contains. It
	// does not fail if the path does not exist (return nil).
	RemoveAll(path string) error

	// Rename renames a file.
	Rename(oldname, newname string) error

	// Stat returns a FileInfo describing the named file, or an error, if any
	// happens.
	Stat(name string) (os.FileInfo, error)

	// The name of this FileSystem
	Name() string

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

	// Chown changes the uid and gid of the named file.
	Chown(name string, uid, gid int) error

	//Chtimes changes the access and modification times of the named file
	Chtimes(name string, atime time.Time, mtime time.Time) error
}

Fs is the filesystem interface.

Any simulated or real filesystem should implement this interface.

func NewOsFs

func NewOsFs() Fs

type LinkReader

type LinkReader interface {
	ReadlinkIfPossible(name string) (string, error)
}

LinkReader is an optional interface in Afero. It is only implemented by the filesystems saying so.

type Linker

type Linker interface {
	SymlinkIfPossible(oldname, newname string) error
}

Linker is an optional interface in Afero. It is only implemented by the filesystems saying so. It will call Symlink if the filesystem itself is, or it delegates to, the os filesystem, or the filesystem otherwise supports Symlink's.

type Lstater

type Lstater interface {
	LstatIfPossible(name string) (os.FileInfo, bool, error)
}

Lstater is an optional interface in Afero. It is only implemented by the filesystems saying so. It will call Lstat if the filesystem iself is, or it delegates to, the os filesystem. Else it will call Stat. In addtion to the FileInfo, it will return a boolean telling whether Lstat was called or not.

type OsFs

type OsFs struct{}

OsFs is a Fs implementation that uses functions provided by the os package.

For details in any method, check the documentation of the os package (http://golang.org/pkg/os/).

func (OsFs) Chmod

func (OsFs) Chmod(name string, mode os.FileMode) error

func (OsFs) Chown

func (OsFs) Chown(name string, uid, gid int) error

func (OsFs) Chtimes

func (OsFs) Chtimes(name string, atime time.Time, mtime time.Time) error

func (OsFs) Create

func (OsFs) Create(name string) (File, error)

func (OsFs) LstatIfPossible

func (OsFs) LstatIfPossible(name string) (os.FileInfo, bool, error)

func (OsFs) Mkdir

func (OsFs) Mkdir(name string, perm os.FileMode) error

func (OsFs) MkdirAll

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

func (OsFs) Name

func (OsFs) Name() string

func (OsFs) Open

func (OsFs) Open(name string) (File, error)

func (OsFs) OpenFile

func (OsFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

func (OsFs) ReadlinkIfPossible

func (OsFs) ReadlinkIfPossible(name string) (string, error)

func (OsFs) Remove

func (OsFs) Remove(name string) error

func (OsFs) RemoveAll

func (OsFs) RemoveAll(path string) error

func (OsFs) Rename

func (OsFs) Rename(oldname, newname string) error

func (OsFs) Stat

func (OsFs) Stat(name string) (os.FileInfo, error)

func (OsFs) SymlinkIfPossible

func (OsFs) SymlinkIfPossible(oldname, newname string) error

type Symlinker

type Symlinker interface {
	Lstater
	Linker
	LinkReader
}

Symlinker is an optional interface in Afero. It is only implemented by the filesystems saying so. It indicates support for 3 symlink related interfaces that implement the behaviors of the os methods:

• Lstat
• Symlink, and
• Readlink

type UnionFile

type UnionFile struct {
	Base   File
	Layer  File
	Merger DirsMerger
	// contains filtered or unexported fields
}

The UnionFile implements the afero.File interface and will be returned when reading a directory present at least in the overlay or opening a file for writing.

The calls to Readdir() and Readdirnames() merge the file os.FileInfo / names from the base and the overlay - for files present in both layers, only those from the overlay will be used.

When opening files for writing (Create() / OpenFile() with the right flags) the operations will be done in both layers, starting with the overlay. A successful read in the overlay will move the cursor position in the base layer by the number of bytes read.

func (*UnionFile) Close

func (f *UnionFile) Close() error

func (*UnionFile) Name

func (f *UnionFile) Name() string

func (*UnionFile) Read

func (f *UnionFile) Read(s []byte) (int, error)

func (*UnionFile) ReadAt

func (f *UnionFile) ReadAt(s []byte, o int64) (int, error)

func (*UnionFile) Readdir

func (f *UnionFile) Readdir(c int) (ofi []os.FileInfo, err error)

Readdir will weave the two directories together and return a single view of the overlayed directories. At the end of the directory view, the error is io.EOF if c > 0.

func (*UnionFile) Readdirnames

func (f *UnionFile) Readdirnames(c int) ([]string, error)

func (*UnionFile) Seek

func (f *UnionFile) Seek(o int64, w int) (pos int64, err error)

func (*UnionFile) Stat

func (f *UnionFile) Stat() (os.FileInfo, error)

func (*UnionFile) Sync

func (f *UnionFile) Sync() (err error)

func (*UnionFile) Truncate

func (f *UnionFile) Truncate(s int64) (err error)

func (*UnionFile) Write

func (f *UnionFile) Write(s []byte) (n int, err error)

func (*UnionFile) WriteAt

func (f *UnionFile) WriteAt(s []byte, o int64) (n int, err error)

func (*UnionFile) WriteString

func (f *UnionFile) WriteString(s string) (n int, err error)