contextual

package
v0.0.0-...-c199c2d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2026 License: MIT Imports: 10 Imported by: 1

Documentation

Overview

Package contextualfs provides extended filesystem interfaces that support write operations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Chmod 

func Chmod(ctx context.Context, fsys FS, name string, mode fs.FileMode) error

Chmod changes the mode of the named file to mode.

func Chown 

func Chown(ctx context.Context, fsys FS, name, owner, group string) error

Chown changes the owner and group of the named file.

func Chtimes 

func Chtimes(ctx context.Context, fsys FS, name string, atime, mtime time.Time) error

Chtimes changes the access and modification times of the named file.

func FromContextual 

func FromContextual(fsys FS, ctx context.Context) fs.FS

FromContextual converts a contextual FS to a non-contextual fs.FS. The returned filesystem satisfies fsx.FileSystem and all standard io/fs interfaces by using the provided context for every operation.

This is useful for integrating context-aware filesystems into existing non-contextual APIs or libraries that expect an fs.FS.

func Lchown 

func Lchown(ctx context.Context, fsys FS, name, owner, group string) error

Lchown changes the ownership of the named file.

func Mkdir 

func Mkdir(ctx context.Context, fsys FS, name string, perm fs.FileMode) error

Mkdir creates a new directory with the specified name and permission bits.

func MkdirAll 

func MkdirAll(ctx context.Context, fsys FS, name string, perm fs.FileMode) error

MkdirAll creates a directory named path, along with any necessary parents.

func Open 

func Open(ctx context.Context, fsys FS, name string) (fs.File, error)

Open opens the named file in the given filesystem.

func ReadDir 

func ReadDir(ctx context.Context, fsys FS, name string) ([]fs.DirEntry, error)

ReadDir reads the named directory and returns a list of directory entries sorted by filename.

func ReadFile 

func ReadFile(ctx context.Context, fsys FS, name string) ([]byte, error)

ReadFile reads the named file from the given filesystem and returns its contents. 

func ReadLink(ctx context.Context, fsys FS, name string) (string, error)

ReadLink returns the destination of the named symbolic link.

func Remove 

func Remove(ctx context.Context, fsys FS, name string) error

Remove removes the named file or (empty) directory from the filesystem.

func RemoveAll 

func RemoveAll(ctx context.Context, fsys FS, name string) error

RemoveAll removes path and any children it contains.

func Rename 

func Rename(ctx context.Context, fsys FS, oldname, newname string) error

Rename moves oldname to newname. 

func Symlink(ctx context.Context, fsys FS, oldname, newname string) error

Symlink creates a symbolic link at newname, pointing to oldname.

func Truncate 

func Truncate(ctx context.Context, fsys FS, name string, size int64) error

Truncate changes the size of the named file.

func WriteFile 

func WriteFile(ctx context.Context, fsys FS, name string, data []byte, perm fs.FileMode) error

WriteFile writes data to the named file, creating it if necessary.

Types

type ChangeFS 

type ChangeFS interface {
	WriterFS

	// Chown changes the numeric uid and gid of the named file.
	Chown(ctx context.Context, name, owner, group string) error

	// Chmod changes the file mode bits of the named file to the specified mode.
	Chmod(ctx context.Context, name string, mode fs.FileMode) error

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

ChangeFS is an interface that extends WriterFS to support modification operations like Chown, Chmod, and Chtimes.

type DirFS 

type DirFS interface {
	WriterFS
	ReadDirFS

	// Mkdir creates a new directory with the specified name and permission bits.
	Mkdir(ctx context.Context, name string, perm fs.FileMode) error
}

DirFS is an interface for filesystems that support creating directories.

type FS 

type FS interface {
	// Open opens the named file.
	//
	// When Open returns an error, it should be of type *fs.PathError
	// with the Op field set to "open", the Path field set to name,
	// and the Err field describing the problem.
	//
	// Open should reject attempts to open names that do not satisfy
	// fs.ValidPath(name), returning a *fs.PathError with Err set to
	// fs.ErrInvalid or fs.ErrNotExist.
	Open(ctx context.Context, name string) (fs.File, error)
}

FS is the interface implemented by a file system that supports context-aware Open.

It mirrors io/fs.FS but with a context parameter.

func ToContextual 

func ToContextual(fsys fs.FS) FS

ToContextual converts a non-contextual fs.FS to a contextual FS. The returned FS ignores the context.

type File 

type File = fsx.File

File is an open file that supports reading, writing, and truncation.

func Create 

func Create(ctx context.Context, fsys FS, name string) (File, error)

Create creates or truncates the named file in the given filesystem. If fsys implements WriterFS, it calls fsys.Create(ctx, name). Otherwise, it returns errors.ErrUnsupported.

func OpenFile 

func OpenFile(ctx context.Context, fsys FS, name string, flag int, mode fs.FileMode) (File, error)

OpenFile opens the named file with specified flag and mode in the given filesystem. If fsys implements WriterFS, it calls fsys.OpenFile(ctx, name, flag, mode). Otherwise, it attempts a fallback for read-only access.

type FileInfo 

type FileInfo = fsx.FileInfo

FileInfo extends the standard fs.FileInfo interface with additional metadata like ownership, access time, and change time.

func ExtendFileInfo 

func ExtendFileInfo(fi fs.FileInfo) FileInfo

ExtendFileInfo returns a FileInfo that wraps the provided fs.FileInfo, attempting to extract extended system-specific information.

func Lstat 

func Lstat(ctx context.Context, fsys FS, name string) (FileInfo, error)

Lstat returns a FileInfo describing the named file. If the file is a symbolic link, the returned FileInfo describes the symbolic link.

func Stat 

func Stat(ctx context.Context, fsys FS, name string) (FileInfo, error)

Stat returns a FileInfo describing the named file.

type FileSystem 

type FileSystem interface {
	FS
	ChangeFS
	DirFS
	LchownFS
	MkdirAllFS
	ReadDirFS
	ReadFileFS
	ReadLinkFS
	RemoveAllFS
	RenameFS
	StatFS
	SymlinkFS
	TruncateFS
	WriteFileFS
	WriterFS
}

type LchownFS 

type LchownFS interface {
	SymlinkFS

	// Lchown changes the ownership of the named file (or link).
	Lchown(ctx context.Context, name, owner, group string) error
}

LchownFS is an interface for filesystems that support changing the ownership of a symbolic link itself.

type MkdirAllFS 

type MkdirAllFS interface {
	DirFS

	// MkdirAll creates a directory named path, along with any necessary parents.
	MkdirAll(ctx context.Context, name string, perm fs.FileMode) error
}

MkdirAllFS is an interface for filesystems that support creating a directory along with any necessary parents.

type ReadDirFS 

type ReadDirFS interface {
	FS
	// ReadDir reads the named directory
	// and returns a list of directory entries sorted by filename.
	ReadDir(ctx context.Context, name string) ([]fs.DirEntry, error)
}

ReadDirFS is the interface implemented by a file system that supports context-aware ReadDir.

type ReadDirFile 

type ReadDirFile = fs.ReadDirFile

ReadDirFile is a file that supports reading directory entries.

type ReadFileFS 

type ReadFileFS interface {
	FS
	// ReadFile reads the named file and returns its contents.
	// A successful call returns a nil error, not io.EOF.
	// (Because ReadFile reads the whole file, the expected behavior
	// is to return the size of the file.)
	ReadFile(ctx context.Context, name string) ([]byte, error)
}

ReadFileFS is the interface implemented by a file system that supports context-aware ReadFile.

type ReadLinkFS 

type ReadLinkFS interface {
	FS
	// ReadLink returns the destination of the named symbolic link.
	// If there is an error, it should be of type *fs.PathError.
	ReadLink(ctx context.Context, name string) (string, error)

	// Lstat returns a FileInfo describing the named file.
	// If the file is a symbolic link, the returned FileInfo describes the symbolic link.
	// Lstat makes no attempt to follow the link.
	// If there is an error, it should be of type *fs.PathError.
	Lstat(ctx context.Context, name string) (fs.FileInfo, error)
}

ReadLinkFS is the interface implemented by a file system that supports context-aware ReadLink.

type RemoveAllFS 

type RemoveAllFS interface {
	WriterFS

	// RemoveAll removes path and any children it contains.
	RemoveAll(ctx context.Context, name string) error
}

RemoveAllFS is the interface implemented by a file system that supports an optimized RemoveAll method.

type RenameFS 

type RenameFS interface {
	WriterFS

	// Rename moves oldname to newname.
	Rename(ctx context.Context, oldname, newname string) error
}

RenameFS is the interface implemented by a file system that supports renaming files.

type StatFS 

type StatFS interface {
	FS
	// Stat returns a FileInfo describing the file.
	// If there is an error, it should be of type *fs.PathError.
	Stat(ctx context.Context, name string) (fs.FileInfo, error)
}

StatFS is the interface implemented by a file system that supports context-aware Stat.

type SymlinkFS 

type SymlinkFS interface {
	WriterFS
	ReadLinkFS

	// Symlink creates a symbolic link at newname, pointing to oldname.
	Symlink(ctx context.Context, oldname, newname string) error
}

SymlinkFS is an interface for filesystems that support creating symbolic links.

type TruncateFS 

type TruncateFS interface {
	WriterFS

	// Truncate changes the size of the named file.
	Truncate(ctx context.Context, name string, size int64) error
}

TruncateFS is the interface implemented by a file system that supports truncating files by name.

type WriteFileFS 

type WriteFileFS interface {
	WriterFS

	// WriteFile writes data to the named file, creating it if necessary.
	WriteFile(ctx context.Context, name string, data []byte, perm fs.FileMode) error
}

WriteFileFS is the interface implemented by a filesystem that provides an optimized WriteFile method.

type WriterFS 

type WriterFS interface {
	FS

	// Create creates or truncates the named file. If the file already exists,
	// it is truncated. If the file does not exist, it is created with mode 0666
	// (before umask). If successful, methods on the returned File can
	// be used for I/O; the associated file descriptor has mode O_RDWR.
	// If there is an error, it will be of type *fs.PathError.
	Create(ctx context.Context, name string) (File, error)

	// OpenFile is the generalized open call; most users will use Open
	// or Create instead. It opens the named file with specified flag
	// (O_RDONLY etc.) and perm (0666 etc.) if applicable. If successful,
	// methods on the returned File can be used for I/O.
	// If there is an error, it will be of type *fs.PathError.
	OpenFile(ctx context.Context, name string, flag int, mode fs.FileMode) (File, error)

	// Remove removes the named file or (empty) directory.
	// If there is an error, it will be of type *fs.PathError.
	Remove(ctx context.Context, name string) error
}

WriterFS is the interface implemented by a file system that supports write operations (Create, OpenFile, Remove) in addition to Open.

It corresponds to fsx.WriterFS but with context parameters.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.