README
¶
fsx
Extended filesystem abstractions for golang!
About
fsx provides a package that extends the io/fs package from the standard
library with functionality to create and modify files and directories.
The package defines an interface fsx.FS that embeds fs.FS and adds methods to modify files and
directories. Those methods have been modeled after the corresponding functions from the os package. In
addition an interface fsx.File embeds fs.File and adds methods found on os.File type.
Similar to fs, which defines additional interfaces for implementations that provide specific functionality
(i.e. to read a directory, such as fs.ReadDirFS) this package defines extra interfaces for operations like
- create file
- write file
- create symlink
- remove file
- remove dir
Installation
go get github.com/halimath/fsx
Usage examples
osfs
The following example demonstrates how to use the osfs subpackage which
provides fsx compatible abstractions using the os package to access
files and directories from the local fs.
// Create a temporary directory to use as a root
dir, err := os.MkdirTemp("", "fsx_example_*")
if err != nil {
panic(err)
}
// Make sure the directory is removed at the end of the test.
defer os.RemoveAll(dir)
// Create a fsx.FS using the temp dir.
fsys := osfs.DirFS(dir)
// Create a file inside the fsys.
f, err := fsx.Create(fsys, "test.md")
if err != nil {
panic(err)
}
// Write some content to the file.
if _, err := f.Write([]byte("# fsx example test\n\nThis is just an example.")); err != nil {
panic(err)
}
if err := f.Close(); err != nil {
panic(err)
}
// Create a symlink inside the fsys
if err := fsys.Symlink("test.md", "README.md"); err != nil {
panic(err)
}
// Now try to read the symlinked file using os functions.
content, err := os.ReadFile(filepath.Join(dir, "README.md"))
if err != nil {
panic(err)
}
memfs
The subpackage memfs provides an in-memory implementation of fsx
interfaces.
// Create a fsx.FS using the temp dir.
fsys := memfs.New()
// Create a file inside the fsys.
f, err := fsx.Create(fsys, "test.md")
if err != nil {
panic(err)
}
// Write some content to the file.
if _, err := f.Write([]byte("# fsx example test\n\nThis is just an example.")); err != nil {
panic(err)
}
if err := f.Close(); err != nil {
panic(err)
}
// Create a symlink inside the fsys
if err := fsys.Symlink("test.md", "README.md"); err != nil {
panic(err)
}
// Now try to read the symlinked file using fs.ReadFile
content, err := fs.ReadFile(fsys, "README.md")
if err != nil {
panic(err)
}
License
Copyright 2023 Alexander Metzner.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation
¶
Overview ¶
Package fsx provides types and functions that extend the functionality provided by the fs package. The extension provides capabilities to create, write and delete files and to create and delete directories.
The API has been modelled after the API provided by the os package. Thus, not all OS-specific features are provided by fsx. Stil, this package provides enough to allow a lot of applications to benefit from an additional abstraction layer.
Index ¶
- Constants
- Variables
- func Chmod(fsys FS, name string, mode fs.FileMode) error
- func Chown(fsys FS, name string, uid, gid int) error
- func MkdirAll(fsys FS, path string, perm fs.FileMode) error
- func RemoveAll(fsys FS, name string) error
- func WriteFile(fsys FS, name string, data []byte, perm fs.FileMode) error
- type ChmodFS
- type ChownFS
- type ChtimesFS
- type FS
- type File
- type LinkFS
- type MkdirAllFS
- type RemoveAllFS
- type WriteFileFS
Constants ¶
const ( // open the file read-only. O_RDONLY = os.O_RDONLY // open the file write-only. O_WRONLY = os.O_WRONLY // open the file read-write. O_RDWR = os.O_RDWR // append data to the file when writing. O_APPEND = os.O_APPEND // create a new file if none exists. O_CREATE = os.O_CREATE // used with O_CREATE, file must not exist. O_EXCL = os.O_EXCL // open for synchronous I/O. O_SYNC = os.O_SYNC // truncate regular writable file when opened. O_TRUNC = os.O_TRUNC Separator = '/' )
Flags to OpenFile wrapping those of the underlying system. Not all flags may be implemented on a given system.
const ( // Value for whence passed to Seek to position relative to origin. SeekWhenceRelativeOrigin = 0 // Value for whence passed to Seek to position relative to current offset. SeekWhenceRelativeCurrentOffset = 1 // Value for whence passed to Seek to position relative to end of file. SeekWhenceRelativeEnd = 2 )
Variables ¶
var (
ErrInvalidWhence = errors.New("invalid whence")
)
Functions ¶
func Chmod ¶
Chmod changes the mode of the named file to mode. It works in analogy to os.Chmod. Chmod checks if fsys statisfies ChmodFS. If so, it simply delegates. Otherwise it uses OpenFile and Chmod of the file's handle.
func Chown ¶
Chown changes ownership of the named file to uid and gid. If fsys stasfies ChownFS its implementation is used. If not, the named file will be opened and have ownership changed.
If changing a file's ownership is not supported by the underlying fsys implementation this function returns nil and effectively becomes a no-op.
func MkdirAll ¶
MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The permission bits perm (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil. This function works in analogy to os.MkdirAll.
If fsys statisfies MkdirAllFS the call is simply delegated. Otherwise a default implementation is used.
func RemoveAll ¶
RemoveAll removes path and any children it contains. If fsys satisfies RemoveAllFS the call is simply delegated. Otherwise, RemoveAll removes everything nested under name including name itself but returns the first error it encounters. If the name does not exist, RemoveAll returns nil (no error).
This function works in analogy to os.RemoveAll.
Types ¶
type ChmodFS ¶
ChmodFS defines an interface of FS that support direct update of a file's mode (i.e. permission) directly.
type ChownFS ¶
type ChownFS interface {
FS
// Chown changes ownership of the named file to the numeric values given
// as uid and gid.
//
// If changing a file's ownership is not supported this method must return
// a nil error. This is to make sure that code using this abstraction remains
// portable.
Chown(name string, uid, gid int) error
}
ChownFS defines an interface for filesystems that provide optimized support to change a file's ownership.
type ChtimesFS ¶
type ChtimesFS interface {
FS
// Chtimes changes the access and modification time of the named file. A
// zero value for either atime of mtime causes these values to be kept.
Chtimes(name string, atime, mtime time.Time) error
}
ChtimesFS defines an interface for filesystems that support changing a file's access and modification time.
Note that in contrast to other extension interfaces defined here there is no corresponding package function named Chtimes. If the FS does not support this operation on a filesystem level, you have to open the file on order to update the times.
type FS ¶
type FS interface {
fs.FS
// OpenFile opens the file named name. flag defines how the file should
// be opened. Exactly one of O_RDONLY, O_WRONLY, or O_RDWR must be
// specified. Other flags may be or'ed to control behavior.
// perm defines the file's permission.
OpenFile(name string, flag int, perm fs.FileMode) (File, error)
// Mkdir creates a directory named name with permission perm. Mkdir returns
// an error if any parent directory does not exist.
Mkdir(name string, perm fs.FileMode) error
// Remove removes the named file or (empty) directory.
Remove(name string) error
// Rename renames oldpath to newpath.
Rename(oldpath, newpath string) error
// SameFile returns true iff fi1 and fi2 both represent the same
// filesystem's file.
SameFile(fi1, fi2 fs.FileInfo) bool
}
FS defines the interface for types that provide a writable filesystem implementation. The interface is a composition of fs.FS and additional functions.
type File ¶
type File interface {
fs.File
io.Writer
// Chmod changes the file's permission or mode.
Chmod(mode fs.FileMode) error
// Chown changes ownership of this file to the numeric values uid for owning
// user and gid for owning group.
//
// If changing a file's ownership is not supported this method must return
// a nil error. This is to make sure that code using this abstraction remains
// portable.
Chown(uid, gid int) error
// Seek sets the offset for the next Read or Write on file to offset,
// interpreted according to whence:
//
// - 0 means relative to the origin of the file,
// - 1 means relative to the current offset, and
// - 2 means relative to the end.
//
// It returns the new offset and an error, if any.
// The behavior of Seek on a file opened with O_APPEND is not specified.
Seek(offset int64, whence int) (ret int64, err error)
}
File defines the interface for a writable file in a FS. It composes fs.File and thus provides an extended yet compatible interface. It also composes io.Writer to support a wide range of writing primitives. In addition, a file's permission can be changed with Chmod.
It is suggested for implementations to also implement the following interfaces if applicable to improve performance when operating with a File:
- io.ReaderAt - io.ReaderFrom - io.WriterAt - io.WriterTo
type LinkFS ¶
type LinkFS interface {
FS
// Readlink returns the target of link name or an error.
Readlink(name string) (string, error)
// Link creates a hardlink newname pointing to oldname.
Link(oldname, newname string) error
// Symlink creates a symbolic link newname pointing to oldname. The behavior
// when creating a symbolic link to a non-existing target is not specified.
Symlink(oldname, newname string) error
}
LinkFS defines an interface for filesystem implementations that support links (both hardlinks and symlinks).
The functions defined by LinkFS are modeled after the link functions provided by package os.
type MkdirAllFS ¶
MkdirAllFS defines an interface for FS that support direct creation of all directories in a hierarchy.
type RemoveAllFS ¶
RemoveAllFS defines an interface for fsx.FS implementations, that provide built-in support to remove a directory including its children. When passed to RemoveAll, this interface' method will be used instead of the default behavior implemented by RemoveAll.
type WriteFileFS ¶
WriteFileFS defines an interface for fsx.FS implementations that provide specialized support for writing a file. fsx.WriteFile checks if the passed fsx.FS implements this interface. If so it simply delegates to the WriteFile methode. Otherwise it uses OpenFile, Write and Close to write the file.
Source Files
Directories