realfs

README

go-real-fs

A real filesystem that behaves normally and implements fs.FS and wraps os.DirFS.

Using fs.FS to represent filesystems has many advantages, but it can be clunky to work with for reasons outlined in this rejected proposal.

go-real-fs implements this behaviour like so:

package main

import (
    "github.com/sean9999/go-real-fs"
)

func main(){

    realFs := realfs.New()
    data, _ := realFs.ReadFile("/etc/passwd")
    fmt.Println("here is the contents of /etc/passwd")
    os.Stdout.Write(data)

}

go-real-fs simply rewrites paths from context-dependant to root-relative:

func (rfs realFS) correctPath(relativePath string) (string, error) {

	fullPath, err := filepath.Abs(relativePath)
	if err != nil {
		return "", err
	}
	return filepath.Rel("/", fullPath)

}

It's power comes from the fact that it satisfies interfaces from the fs package, allowing for modularity and testability. Let's say you wanted to create a storage-agnostic and testable key-value store:

type Database struct {
    filesystem realfs.WritableFs
}

func (d *Database) Get(name string) ([]byte, error) {
    return d.filesystem.OpenFile(name)
}

func (d *Databse) Set(name string, content []byte) error {
    return d.filesystem.WriteFile(name, content, 0640)
}

func (d *Database) Delete(name string) error {
    return d.filesystem.Remove(name)
}

To instantiate a real Databse you can do:

db := Database{realfs.NewWritable()} 

And to test is equally easy:

func TestDatabase(t *testing.T) {

    


}

Documentation

Index

• func NewWritable() writableFs
• type NullDevice
  • func (b NullDevice) Open(_ string) (fs.File, error)
  • func (b NullDevice) OpenFile(name string, flag int, perm fs.FileMode) (WritableFile, error)
  • func (b NullDevice) Read(_ []byte) (int, error)
  • func (b NullDevice) ReadDir(_ string) ([]fs.DirEntry, error)
  • func (b NullDevice) ReadFile(_ string) ([]byte, error)
  • func (b NullDevice) Remove(_ string) error
  • func (b NullDevice) Stat(_ string) (fs.FileInfo, error)
  • func (b NullDevice) WriteFile(_ string, _ []byte, _ fs.FileMode) error
• type RealFS
  • func New() RealFS
• type TestFS
  • func NewTestFs() TestFS
  • func (tw TestFS) Open(name string) (fs.File, error)
  • func (tw TestFS) OpenFile(name string, _ int, _ fs.FileMode) (WritableFile, error)
  • func (tw TestFS) ReadDir(name string) ([]fs.DirEntry, error)
  • func (tw TestFS) ReadFile(name string) ([]byte, error)
  • func (tw TestFS) Remove(name string) error
  • func (tw TestFS) Stat(name string) (fs.FileInfo, error)
  • func (tw TestFS) WriteFile(name string, data []byte, mode fs.FileMode) error
• type TestFSFile
  • func (_ *TestFSFile) Close() error
  • func (f *TestFSFile) IsDir() bool
  • func (f *TestFSFile) Name() string
  • func (f *TestFSFile) Read(p []byte) (int, error)
  • func (f *TestFSFile) Seek(offest int64, whence int) (int64, error)
  • func (f *TestFSFile) Stat() (fs.FileInfo, error)
  • func (f *TestFSFile) Write(b []byte) (int, error)
• type WritableFile
• type WritableFs

Functions

func NewWritable

func NewWritable() writableFs

Types

type NullDevice

type NullDevice struct {
	io.Writer
}

func (NullDevice) Open

func (b NullDevice) Open(_ string) (fs.File, error)

func (NullDevice) OpenFile

func (b NullDevice) OpenFile(name string, flag int, perm fs.FileMode) (WritableFile, error)

func (NullDevice) Read

func (b NullDevice) Read(_ []byte) (int, error)

func (NullDevice) ReadDir

func (b NullDevice) ReadDir(_ string) ([]fs.DirEntry, error)

func (NullDevice) ReadFile

func (b NullDevice) ReadFile(_ string) ([]byte, error)

func (NullDevice) Remove

func (b NullDevice) Remove(_ string) error

func (NullDevice) Stat

func (b NullDevice) Stat(_ string) (fs.FileInfo, error)

func (NullDevice) WriteFile

func (b NullDevice) WriteFile(_ string, _ []byte, _ fs.FileMode) error

type RealFS

type RealFS interface {
	fs.StatFS
	fs.ReadFileFS
	fs.ReadDirFS
}

RealFS is real filesystem that wraps os.DirFS and implements fs.FS

func New

func New() RealFS

type TestFS

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

func NewTestFs

func NewTestFs() TestFS

func (TestFS) Open

func (tw TestFS) Open(name string) (fs.File, error)

func (TestFS) OpenFile

func (tw TestFS) OpenFile(name string, _ int, _ fs.FileMode) (WritableFile, error)

func (TestFS) ReadDir

func (tw TestFS) ReadDir(name string) ([]fs.DirEntry, error)

func (TestFS) ReadFile

func (tw TestFS) ReadFile(name string) ([]byte, error)

func (TestFS) Remove

func (tw TestFS) Remove(name string) error

func (TestFS) Stat

func (tw TestFS) Stat(name string) (fs.FileInfo, error)

func (TestFS) WriteFile

func (tw TestFS) WriteFile(name string, data []byte, mode fs.FileMode) error

type TestFSFile

type TestFSFile struct {
	*fstest.MapFile

	Info *finfo
	// contains filtered or unexported fields
}

func (*TestFSFile) Close

func (_ *TestFSFile) Close() error

func (*TestFSFile) IsDir

func (f *TestFSFile) IsDir() bool

func (*TestFSFile) Name

func (f *TestFSFile) Name() string

func (*TestFSFile) Read

func (f *TestFSFile) Read(p []byte) (int, error)

func (*TestFSFile) Seek

func (f *TestFSFile) Seek(offest int64, whence int) (int64, error)

func (*TestFSFile) Stat

func (f *TestFSFile) Stat() (fs.FileInfo, error)

func (*TestFSFile) Write

func (f *TestFSFile) Write(b []byte) (int, error)

type WritableFile

type WritableFile interface {
	fs.File
	io.Writer
	io.Seeker
	Name() string
}

type WritableFs

type WritableFs interface {
	RealFS
	WriteFile(string, []byte, fs.FileMode) error
	OpenFile(string, int, fs.FileMode) (WritableFile, error)
	Remove(string) error
}

WritableFs is a writable filesystem