fsutils

README

fss

Tinkering with new fs.FS

Documentation

Overview

https://benjamincongdon.me/blog/2021/01/21/A-Tour-of-Go-116s-iofs-package/

The Go library allows for more complex behavior by providing other file- system interfaces that can be composed on top of the base fs.FS interface, such as ReadDirFS, which allows you to list the contents of a directory:

type ReadDirFS interface {
    FS
    ReadDir(name string) ([]DirEntry, error)
}

The FS.Open function returns the new fs.File “ReadStatCloser” interface type, which gives you access to some common file functions:

type File interface {
    Stat() (FileInfo, error)
    Read([]byte) (int, error)
    Close() error
}

However, one big caveat: conspicuously absent from the fs.File interface is any ability to write files. The fs package is a R/O interface for filesystems.

https://lobste.rs/s/kixqgi/tour_go_1_16_s_io_fs_package

fstest.TestFS does more than just assert that a few files exist. It walks the entire file tree in the file system you give it, checking that all the various methods it can find are well-behaved and diagnosing a bunch of common mistakes that file system implementers might make. For example it opens every file it can find and checks that Read+Seek and ReadAt give consistent results. And lots more. So if you write your own FS implementation, one good test you should write is a test that constructs an instance of the new FS and then passes it to fstest.TestFS for inspection.

Index

• type FileNordFSer
• type NordFSer

Types

type FileNordFSer

type FileNordFSer interface {
	NordFSer
	// InputFS is undefined for a TagTree.
	InputFS() fs.FS
	// DirCount returns zero if the FS is a TagTree.
	DirCount() int
	// FileCount returns zero if the FS is a TagTree.
	FileCount() int

	// Interface ReadFileFS is a file system providing a custom ReadFile(path).
	// ReadFile reads the named file and returns its contents.
	// A successful call returns a nil error, not io.EOF.
	ReadFile(path string) ([]byte, error)
	// Interface StatFS is a file system with a Stat method.
	// Stat returns a FileInfo describing the file.
	// Any error should be type *PathError.
	Stat(path string) (fs.FileInfo, error)
	// Interface ReadDirFS is a file system with a custom ReadDir(path).
	// ReadDir reads the named directory and returns a
	// list of directory entries sorted by filename.
	ReadDir(path string) ([]fs.DirEntry, error)
}

FileNordFSer is implemented by all types that assemble a tree of Nords and embed an fs.FS . For working with tags (or anything else that is not actual files and directories), use NordFSer instead. The godoc for this interface describes methods unique to FileNordFSer.

A FileTree NordFSer is a collection of files & directories - either (1) hierarchically gathered & organized (when a directory tree is walked, like in a fs.DirTreeFS), or (b) listed individually (like in a DITA map). The file or directory name is the last path element of either of (but maybe both) the absolute path and/or the relative path.

Note that fs.File is an interface that providess just three methods: Stat() (FileInfo, error) ; Read([]byte) (int, error) ; Close() error

type NordFSer

type NordFSer interface {
	// Interface fs.FS is the minimum required of an fs file system.
	// The Open(path) method is its only method. Iy opens the named
	// file. An error should be of type *PathError with the Op "open",
	// Path set to the path, and Err describing the problem.
	// Open should refuse to open a path that fails ValidPath(path),
	// returning a *PathError with Err set to ErrInvalid or ErrNotExist.
	Open(path string) (fs.File, error)
	// Size returns (for a FileTree) the combined number of files and dirs,
	// or (for a TagTree) the total number of tags.
	Size() int
	// RootAbsPath can return the the abs.FP of the markup file if the FS is a TagTree.
	RootAbsPath() string
	// AllPaths can be either all absolute paths or all relative paths.
	AllPaths() []string
	RootNord() ON.Norder
	AsSlice() []ON.Norder
	AsMap() map[string]ON.Norder
}

NordFSer is implemented by all types that assemble a tree of Nords. For working with actual files and directories, use FileNordFSer instead. The godoc for this interface describes methods common to both.

Tipicly a NordFSer is a tree of tags (e.g. an AST) parsed from an XML file. The tag name is the last tag element of the abs.path and/or the rel.path, but possibly the relative path is just the tag name. Furthermore, calling Open (the only method specified in the fs.FS interface) returns the tag's body (from opening tag to closing tag, inclusive) of that tag only, without the context of the larger tag tree.