vfs

package module
v0.0.0-...-6666ad1 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2022 License: NCSA Imports: 13 Imported by: 11

README

VFS: A Virtual File System

go/vfs provides a virtual file system implementation for Go that is robust, extensive, and provides compatibility with multiple Go versions.

Why this Library?

This library predates the Go 1.16 efforts to add an FS layer to the io/fs package and, as such, contains some anachronisms that may seem somewhat surprising to users familiar with the post-1.16 standard library. However, with recent updates to go/vfs, we are now mostly at parity with io/fs.

This library is different in that users may target pre- or post-Go 1.16, toggling compatibility features on or off using the go116 build tag (go build -tags=go116) to enable compatibility with Go 1.16+. By default, go/vfs targets Go versions prior to 1.16, though this default will be changing possibly by the Go 1.17 release.

In particular, we have exposed mostly identical interfaces for constructs like DirEntry and similar such that using go/vfs will require virtually no changes to your code if you migrate to later versions of Go. Likewise, backporting your code using go/vfs should require few changes when targeting earlier pre-1.16 Go installs.

go/vfs also provides, out of the box, a .zip-based VFS layer, a VFS layer that interacts with most file systems, and a layered VFS type that can transparently merge multiple VFSes into a single interface with the option to override missing or older files with newer entries.

In particular, we also offer a Chroot() and SetRoot() functionality that changes the internal root of the VFS to "lock" the file system view to a particular path, inhibiting alternations to paths that exist outside that root while using the same VFS object. These are similar to io/fs.Sub().

Likewise, our persistent FS type deliberately eschews a traditional file system view and will lock itself to the path you've configured during its initialization. You can confidently interact with VFS instances knowing that errant path specifications will not expose other parts of your file system.

Core Interfaces

VFS exposes three primary interfaces: FS, VFS, and MutableFS.

FS is mostly compatible with io/fs, exposing a unified type that contains each of the core methods that appear in various segregated interfaces in io/fs (with the exception of SubFS) and may act as a stand-in for each of the interfaces presented in this package. SubFS is deliberately not included in go/vfs.FS as implementers of our VFS interface may choose whether to support the SetRoot/Chroot mechanics independently of SubFS or they may choose to expose Sub for SubFS compatibility.

FS also differs from the file system interface types in io/fs by requiring that its constituents implement Lstat as well. This is not included in the io/fs package for any file system type.

VFS is the primary wrapper type for the go/vfs library and is the target type that implementers should focus on when authoring their own VFS backends. This type provides--and requires--all of the expected primitives that would be available in your typical file system, such as Abs, Cwd, and a few other utility methods like ReadOnly and SetReadOnly. Some methods like MaskedAbs are explained elsewhere in this document.

MutableFS exposes methods that provide mutational capabilities for the underlying file system. File systems that expose these methods should provide some backing for their intended functions; e.g., Mkdir should do something analogously to creating a directory, and OpenFile should provide a File implementation that handles Write. Implementers may choose to chain together other constructs, like bytes.Buffer for backing stores that don't provide a byte stream or anything analogous to one (such as databases).

Not all file systems may expose all interfaces at any given time. In fact, we have supplyed a WrapAsMutable() function that returns any type implementing VFS inside a type that implements MutableFS with all mutable functions returning an ErrReadOnly when called. This wrapper may be used for VFS types that are only intended to interact with read only constructs, such as archives, saving the developer some time when offering compatibility with each of the go/vfs interfaces.

Quick Start

go/vfs is quite easy to use. This section highlight the most basic usage patterns to help you get started as fast as possible. More detailed documentation may be found in the docs/ directory included with every go/vfs distribution.

Loading a File System

To load and attach a file system:

fs, err := vfs.NewVFS("path/to/directory")
if err != nil {
    // Handle errors.
}

// ...
fp, err := vfs.Open("somefile.txt")

// ... do something with `fp` ...

// Read the entire contents of a file. Note that ReadFile is analogous to
// io.ReadFile or ioutils.ReadFile.
contents, err := vfs.ReadFile(fs, "anotherfile.txt")

// vfs.WriteFile is analogous to ioutil.WriteFile an io.WriteFile.
if err := vfs.WriteFile(fs, "writeme.txt", []byte("Hello!"), os.FileMode(0644); err != nil {
    // Handle error... note that `fs` must implement MutableFS or else an error
    // will be raised here.
}

// Get a mutable instance of the file system to do naughty things with:
mut, err := fs.Mutable()
if err == nil {
    if err := mut.Mkdir("bananas"); err == nil {
        vfs.WriteFile(mut, "tasty.txt", []byte("Tasty bananas."), os.FileMode(0644)
    }
}

Loading an Archive

Presently, VFS supports loading .zip archives out of the box:

fs, err := vfs.NewZipFS("path/to/zipfile.zip")
if err != nil {
    // Handle errors.
}

if content, err := vfs.ReadFile(fs, "some/file.txt"); err == nil {
    fmt.Println(content)
}

Loading Multiple File Systems

It's possible layer multiple file systems together. The first file system supplied to the AddFS method will be checked first for files.

Given a directory structured:

animals/cats/
animals/cats/mainecoon.jpg
animals/cats/funny_cat.png
animals/dogs/
animals/dogs/barking.mp4

and an archive containing:

animals.zip => animals/birds/dancing.mp4
animals.zip => animals/dogs/barking.mp4

we can layer these file systems as:

fs := vfs.NewLayeredFS()
if ffs, err := vfs.NewVFS("animals"); err == nil {
    fs.AddFS(ffs)
}
if zipfs, err := vfs.NewZipFS("animals.zip"); err == nil {
    fs.AddFS(zipfs)
}

In this example, the first file system (persistent FS; using the host file system on disk) will take precdence over the .zip archive. This means that these calls will succeed and read the requested files from the file system:

contents, err := vfs.ReadFile(fs, "cats/mainecoon.jpg")

while this call will read from the .zip archive:

contents, err := vfs.ReadFile(fs, "birds/dancing.mp4")

and this call will read barking.mp4 from the file system rather than the ZIP file:

contents, err := vfs.ReadFile(fs, "dogs/barking.mp4")

File System Types

In this distribution, there are three primary file system types, each of which were highlighted above:

Persistent File System: vfs.NewVFS

The persistent file system type accepts a single directory as its argument. This argument is bound as the VFS "root" directory and files or directories that exist outside this structure cannot be read. Only those files and directoreis present in the working directory of the persistent file system root or its children can be viewed.

Symlinks are handled differently depending on how this VFS is configured. We expose a HandleSymlinks() function that accepts a single boolean argument. If this argument is set to true, the persistent VFS will attempt to resolve and follow symbolic links if and only if they exist within the confines of the VFS file system. If the argument to HandleSymlinks() is false or otherwise left untouched (this is the default), symlinks are ignored and no effort is made to resolve their target.

Zip Archive File System: vfs.NewZipFS

Layered File System: vfs.NewLayeredFS

License

go/vfs is distributed under the terms and conditions of the NCSA license. See LICENSE for details.

In short, the NCSA is analogous to both the 2-clause BSD and MIT licenses with additional dispensations made for included documentation.

Documentation

Overview

This file contains interfaces, wrappers, and imports from Golang versions prior to v1.16. It also exposes interfaces that can be used on previous versions analogously to those introduced in Go 1.16+. These interfaces are compatible with later versions and may be used anywhere they're required in code targeting Go 1.16 (where appropriate).

Index

Constants

This section is empty.

Variables

View Source 
var ErrCreate = errors.NewError("error creating pathspec")

ErrCreate is returned whenever the underlying VFS was unable to create the object requested per the pathspec. This may be a file or directory depending on the function that returned it.

Not all VFS layers are capable of returning this error.

View Source 
var ErrCwd = errors.NewError("error reading current working directory")

ErrCwd is returned whenever the current working directory cannot be read.

View Source 
var ErrFileExceedsMaxRead = errors.NewError("maximum read exceeded")
View Source 
var ErrInvalidPath = errors.NewError("not a valid path")

ErrInvalidPath is returned whenever the requested path is not valid as per the context of the current VFS.

The specific meaning of this error depends on the underlying VFS that returned it.

View Source 
var ErrModify = errors.NewError("error modifying path")

ErrModify is returned if an attempt to modify an attribute of the specified path has failed.

View Source 
var ErrNoInfo = errors.NewError("no FileInfo available")

ErrNoInfo should be returned by Stat() methods for which no FileInfo can be obtained for the underlying type.

Care should be taken to return this *only* if the underlying type cannot be persuaded to yield a FileInfo-compatible interface, such as if the entry does actually exist, but for whatever reason no further information may be divined.

In most cases, ErrNotExists should be returned instead.

View Source 
var ErrNotADirectory = errors.NewError("not a directory")

ErrNotADirectory is returned when a directory is expected but a different file system object was received instead.

View Source 
var ErrNotExists = errors.NewError("path does not exist")

ErrNotExists is returned when an attempt is made to open or stat a file or directory that does not exist.

View Source 
var ErrOpeningFile = errors.NewError("error opening file")

ErrOpeningFile is returned whenever an attempt to open a file, either for reading or writing, has failed.

View Source 
var ErrRandom = errors.NewError("error in underlying random number implementation")

ErrRandom may be returned by the random file name generator if the OS random entropy source has failed.

View Source 
var ErrReadOnly = errors.NewError("read only file system")

ErrReadOnly is returned by file system manipulation methods that were called on a VFS instance flagged as read only.

View Source 
var ErrReadingPath = errors.NewError("error reading path")

ErrReadingPath is returned if the underlying file system primitives are unable to read the path. What this means and what triggers this condition is determined by the VFS implementation. e.g., VFSZip returning this error may indicate an unreadable .zip file.

View Source 
var ErrRemove = errors.NewError("error removing pathspec")

ErrRemove is returned whenever the underlying VFS was unable to remove the object as requested per the pathspec. This may be a file or directory depending on the nature of the object and a Stat() would be required to determine the type of the object.

View Source 
var ErrRename = errors.NewError("error renaming pathspec")

ErrRename is returned whenever the underlying VFS was unable to rename the object as requested per its pathspec. The nature of the target depends on its underlying implementation, but generally the error can be drilled down for further information as to the cause.

View Source 
var ErrSeekNotSupported = errors.NewError("seek is not supported for this type")

ErrSeekNotSupported is returned if the current VFS or file type does not support seeking.

View Source 
var ErrWriteFailed = errors.NewError("write failed")

ErrWriteFailed is returned by helper functions or other methods that write to a file handle if either the write itself failed or the write was incomplete.

View Source 
var MaxPlaceholderReplacements = 10
View Source 
var MaxReadFileSize = 1024 * 1024 * 8

MaxReadFilesSize of 8 megabytes. This may be changed by client code.

Functions

func Clean 

func Clean(path string) string

Clean operates similarly to filepath.Clean with the exception that it also trims leading "../" components.

func DefaultTempFileGenerator 

func DefaultTempFileGenerator(length int) (string, error)

DefaultTempFileGenerator is the default generator for creating randomize file name components.

func DefaultTempFilePatternParser 

func DefaultTempFilePatternParser(pattern string, length int, fn RandomNameFunc) string

DefaultTempFilePatternParser is the default pattern parser for TempFile.

This parser replaces all instances of "*" with a `length` character random string using `fn` as the random character generator. Up to MaxPlaceholderReplacements will be performed.

func Glob 

func Glob(pattern string, fs FS) (matches []string, err error)

Glob match the specified pattern against the contents of fs.

TODO: Consider implementing recursive globbing via "**" operators, e.g.: `**/*.txt` would match all .txt files in the current directory and below.

func HTTPDir 

func HTTPDir(fs FS) *httpdir

HTTPDir returns a VFS wrapper usable with net/http.FileServer.

Note: This implementation does NOT implement the ExtendedFS interface as it is intended strictly to support loading content from a VFS.

func IsNotDir 

func IsNotDir(err error) bool

IsNotDir returns true if the error matches ErrNotExists or ErrNotADirectory. If the error is nil or of any other value this will return false.

func IsNotExists 

func IsNotExists(err error) bool

IsNotExists returns true if the error indicates the path does not exist. For VFS errors, these will match ErrNotExists.

This function wraps os.IsNotExists to ensure compatibility.

The choice of "exists" rather than "exist" is deliberate.

func NewLayeredFS 

func NewLayeredFS() *layeredFS

func NewVFS 

func NewVFS(basepath string) (*persistentFS, error)

NewVFS returns a new file system-based VFS instance.

If basepath does not exist it will be created with the FileMode 0755. To change this, call Chmod(".", mode).

func NewZipFS 

func NewZipFS(path string) (*zipfs, error)

func NewZipFromVFS 

func NewZipFromVFS(path string, vfs FS) (*zipfs, error)

func NumDirs 

func NumDirs(fs FS, path string) (i int, err error)

func ReadFile 

func ReadFile(fs FS, path string) (buf []byte, err error)

ReadFile is a helper function that reads `path`'s content into a byte slice, returning the slice or an error, depending on which happens first.

ReadFile is analogous to its counterparts in the standard library with the exception that it accepts a FS as its first argument which is also a file system from which it will attempt to read. Unlike WriteFile, this accepts anything that implements the base FS interface, which is compatible with some parts of the Go standard library. This allows us to consume data from other sources including those that are outside VFS.

ReadFile returns primarily the ErrReadingPath error regardless of outcome. However, this error may wrap other errors (such as permission errors), and it may include additional metadata such as the number of bytes read ("read") versus the number of bytes that were expected ("expected"). These values can be obtained from the go/errors type method Get().

func RenameFile 

func RenameFile(fs FS, file File, to string) error

RenameFile renames the specified file to the target path using the specified VFS.

This differs from calling vfs.Rename in that the `file` entity is updated with its target name changed.

If `file` implements VFSFile, `file.Rename()` will be invoked instead. Otherwise, this will return a new VFSFile instance.

func SafeClean 

func SafeClean(path string) string

SafeClean is like clean except that it also trims leading "/" components.

This is mostly useful for sanitizing paths that will be ultimately interact with a physical file system and cannot escape from a given root directory.

func Walk 

func Walk(efs VFS, path string, fn WalkDirFunc) error

Walks the path specified calling `fn` for each iteration using the VFS `efs`.

This is ported from the Go 1.16 standard library and works identically to filepath.WalkDir. See CREDITS.md.

See also: https://golang.org/pkg/path/filepath/#WalkDir

func WrapFS 

func WrapFS(fs FS) *fsWrapper

WrapFS wraps any type implementing the full FS wrapper and returns a simulated VFS instance with most methods performing analogously to their intended purpose. In circumstances where this isn't possible, a sensible error type will be returned instead.

func WriteFile 

func WriteFile(efs VFS, path string, data []byte, perm os.FileMode) error

WriteFile is a helper that writes the content `data` to the file located at `path`. If the file does not exist, it will be created.

WriteFile will return either ErrOpeningFile if the file cannot be opened (permissions, read only file system, etc) or ErrWriteFailed if the write could not be performed. Both error types can be unfurled and inspected for further information.

ErrOpeningFile may contain a further ErrReadOnly if an effort was made to write to a read-only file system.

If a write is incomplete, ErrWriteFailed will be returned with the attributes "written" and "expected" configured with the number of bytes written to the file system versus the number expected to be written, respectively.

Types

type DirEntry 

type DirEntry interface {
	Name() string
	IsDir() bool
	Type() FileMode
	Info() (FileInfo, error)
}

func MakeDirEntry 

func MakeDirEntry(info FileInfo) DirEntry

type FS 

type FS interface {
	// Open the file specified by name returning a file handle or error.
	//
	// Implements Go's io/fs.FS type.
	Open(name string) (ReadOnlyFile, error)

	// Glob returns a list of matching file names contained by the current FS
	// implementation.
	//
	// Implements Go's io/fs.GlobFS type.
	Glob(pattern string) (matches []string, err error)

	// ReadDir reads a path name and returns a collection of DirEntry(ies)
	// constrained by the specified path.
	//
	// Implements Go's io/fs.ReadDirFS type.
	ReadDir(name string) ([]DirEntry, error)

	// Stat returns a FileInfo instance for the specified path (or file.).
	//
	// Implements Go's io/fs.StatFS type.
	Stat(name string) (FileInfo, error)

	// Lstat returns a FileInfo instance for the specified path. This does not
	// follow links. If a symbolic link is requested via this function, FileInfo
	// will contain only information related to the symbolic link and not the
	// link target.
	Lstat(name string) (FileInfo, error)
}

func Must 

func Must(fs FS, err error) FS

type FSFileInfo 

type FSFileInfo interface {
	os.FileInfo

	// FS returns the underlying file system instance type, if it was
	// set.
	FS() FS

	// MutableFS returns the underlying file system instance type cast
	// as an MutableFS interface. If casting is not possible or the
	// file system instance is not set, nil will be returned instead.
	MutableFS() MutableFS

	// VFS returns the underlying VFS implementation, if possible, or nil if it
	// cannot be converted.
	VFS() VFS
}

type File 

type File interface {
	MutableFile
	ReadOnlyFile
}

func NoopMutable 

func NoopMutable(f ReadOnlyFile, seterr bool) File

NoopMutable returns a File with all mutable functions (like Write) set to return an ErrReadOnly if `seterr` is true. If `seterr` is false, these methods will fail silently.

func TempFile 

func TempFile(efs VFS, dir, pattern string) (File, error)

TempFile generates a new temporary file in the specified directory and returns a File type capable of reading and writing. This is similar to the (now-deprecated) ioutil/TempFile function except that the specified directory *cannot* be the empty string (go/vfs has no concept currently of a system temporary directory, and even if it did, it would be unable to use it).

As with ioutil.TempFile, if pattern contains an asterisk ("*"), it will be replaced with the generated random pattern. Unlike ioutil.TempFile, any asterisk will be replaced with a generated random pattern, with each pattern unique to each asterisk.

efs must be a VFS implementation that can be converted to a MutableFS type, otherwise an error will be returned.

Random patterns will only contain alphanumeric patterns. Future implementation may allow alteration of the randomizer function and random character pools.

type FileInfo 

type FileInfo = os.FileInfo

type FileMode 

type FileMode = os.FileMode

type GoFS 

type GoFS interface {
	Open(name string) (GoFile, error)
}

type GoFile 

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

type LayeredFS 

type LayeredFS interface {
	VFS

	// AddFS attaches a file system to the implementation supporting this
	// layered FS.
	AddFS(FS) LayeredFS
}

type MutableFS 

type MutableFS interface {
	VFS

	// Chmod changes the permissions for the object specified by path to mode.
	// Not all MutableFS implementations may support all FileMode values.
	Chmod(path string, mode FileMode) error

	// Mkdir creates a new directory within the confines of the current VFS
	// layer. For VFS-FS this will always be constrained to the base path even
	// if the path attempts to create itself under the root ("/") directory.
	//
	// This will fail for read only file systems, like .zip files, or for any
	// other VFS layer that was flagged as read only via SetReadOnly(true).
	//
	// For VFS collection types, this call will cascade until it succeeds or
	// ultimately fails. This allows for creating mutable file systems that can
	// be modified by a client while retaining the ability to merge a stacked
	// VFS collection with pre-existing images.
	//
	// See os.Mkdir.
	Mkdir(string, FileMode) error

	// MkdirAll creates a new directory and all of its intermediate path
	// components, as required, within the current VFS layer. For VFS-FS this
	// will always be constrained to the base path even if the path specified
	// attempts to create itself under the root ("/") directory.
	//
	// this will fail for read only file systems, like .zip files, or for any
	// other VFS layer that was flagged as read only via SetReadOnly(true).
	//
	// As with Mkdir, for VFS collection types, this call will cascade until it
	// either ultimately succeeds or fails.
	//
	// See os.MkdirAll.
	MkdirAll(string, FileMode) error

	// MkdirTemp creates a new temporary directory, returning the generated name
	// or any error state. This will be constrained to the current VFS layer.
	//
	// See Mkdir, MkdirAll, and os.MkdirTemp.
	MkdirTemp(string, string) (string, error)

	// OpenFile opens or creates a new File with the specified flags and file
	// mode.
	//
	// The semantics of what exactly "flags" and "mode" imply depend on the
	// underlying VFS. For the persistent FS, these are passed through to the
	// native os.OpenFile call. For read only VFS layers like VFSZip, this will
	// return a read only File handle as if os.O_RDONLY were set.
	OpenFile(path string, flags int, mode FileMode) (File, error)

	// Remove the file or directory. See os.Remove.
	//
	// The behavior of this function depends on the underlying VFS primitives.
	// For the persistent FS, this may return an *os.PathError when used on a
	// read only file system. Likewise, this will return an error if called on a
	// ZIP file or VFSCollection.
	Remove(string) error

	// RemoveAll path components. See os.RemoveAll.
	//
	// The behavior of this function depends on the underlying VFS primitives.
	// For the persistent FS, this may return an *os.PathError when used on a
	// read only file system. Likewise, this will return an error if called on a
	// ZIP file or VFSCollection.
	RemoveAll(string) error

	// Rename a given path from its current name to a new name.
	//
	// If `to` includes a new pathspec and is a file, if the target directory
	// exists, it will be moved.
	//
	// Returns an error for VFS types that are configured as ReadOnly().
	Rename(from, to string) error
}

func WrapAsMutable 

func WrapAsMutable(fs VFS) MutableFS

WrapAsMutable accepts a VFS argument and returns it as a MutableFS with all methods configured to return an ErrReadOnly.

type MutableFile 

type MutableFile interface {
	Chmod(FileMode) error
	Write([]byte) (int, error)
}

type NotifierFS 

type NotifierFS interface {
	ReleasingFS
	Watch(func()) error
}

NotifierFS exposes implementations that may utilize certain primitives to notify listeners of file system changes. At present, only the persistent FS implements this via fsnotify.

NotifierFS types must also implement ReleasingFS, which provides a mechanism for releasing the resources associated with the underlying notification primitives.

type NullableFS 

type NullableFS interface {
	IsEmpty() bool
}

NullableFS should be implemented for those types that could potentially be returned in a null state wherein such circumstances may be disguised by the interface. Usually implementing this with 

func (t *Type) IsEmpty() bool {
    return t == nil
}

is considered sufficient.

Because interface types cannot be compared with nil without knowing the underlying type, this is the best option to protect against potential misuse.

type PersistableFileSystem 

type PersistableFileSystem interface {
	Path() string
}

type RandomNameFunc 

type RandomNameFunc func(length int) (string, error)

type Raw 

type Raw interface {
	RawFile() *os.File
}

Raw is a File-associated interface that unveils the raw *os.File underlying the given type. Not all returned Files will support this, depending on their implementation.

Presently supported only by file system-based VFS instances.

type ReadOnlyFile 

type ReadOnlyFile interface {
	Reader
	io.Seeker
	io.Closer

	Name() string
	Stat() (FileInfo, error)
}

func NoopCloser 

func NoopCloser(f ReadSeeker, info FileInfo) ReadOnlyFile

NoopCloser returns a ReadOnlyFile with a Close method attached that does nothing.

This function will usually be used for readers returned by archives or other implementations where the byte stream generated doesn't supply a Close type but one is needed to fulfill other interfaces in this package.

type ReadSeeker 

type ReadSeeker interface {
	Reader
	io.Seeker
}

type Reader 

type Reader interface {
	io.Reader
	io.ReaderAt
}

type ReleasingFS 

type ReleasingFS interface {
	// Release attempts to remove, release, or nil out any references held by
	// this VFS instance. Not all VFS layers may support Release(). If they do,
	// calling this can provide hints to the Golang GC that the file system
	// instance may be collected when no longer in use.
	//
	// Not guaranteed to release or close any or all open file handles.
	Release() error
}

ReleasingFS implementations expose a Release() method that closes, releases, or otherwise sets to nil any references that may be held open indefinitely even when the file system instance is no longer in use, thus preventing the GC from releasing resources associated with the file system object.

It is up to the caller to decide when it is appropriate to call Release().

type SortableDirEntry 

type SortableDirEntry []DirEntry

func (SortableDirEntry) Len 

func (s SortableDirEntry) Len() int

func (SortableDirEntry) Less 

func (s SortableDirEntry) Less(i, j int) bool

func (SortableDirEntry) Swap 

func (s SortableDirEntry) Swap(i, j int)

type SubFS 

type SubFS interface {
	Sub(dir string) (GoFS, error)
}

type VFS 

type VFS interface {
	FS

	// Abs returns the absolute path of the given component within the virtual
	// file system. If using the VFS-FS layer, this will only return the
	// absolute path if it is part of the configured base path when locked or an
	// error if it is not. When not using a locked VFS-FS layer, this will
	// always return the absolute path if it exists.
	Abs(string) (string, error)

	// Chdir changes the current in-memory directory of the virtual file system.
	// The semantics of this call limit file system views to the VFS' configured
	// root. Ergo, for VFS-FS, Chdir() cannot be used to view file system
	// entries above the configured base. Chdir("/") in all implementations will
	// reset the current working directory to the root of the VFS.
	Chdir(string) error

	// Chroot binds the VFS instance to the specified root directory.
	//
	// Implementations should, at minmum, Clone() or optionally replicate their
	// current instance when invoking this call.
	//
	// Implementations may call Clone() and Chdir() internally to accomplish the
	// same as above.
	Chroot(root string) (VFS, error)

	// SetRoot sets the immutable root path of the VFS layer to the string root,
	// if the path exists as a subpath of the current VFS and resolves to a
	// directory and is readable.
	//
	// SetRoot behave similarly to Chroot with the exception that it acts on the
	// current VFS instance.
	SetRoot(root string) error

	// Clone the file system.
	Clone() VFS

	// Cwd returns the current working directory for the VFS layer.
	//
	// This cannot return an error, because 1) VFS implementations should not
	// Chdir unless the target path is readable, and 2) VFS implementations
	// should fail if they are bound to a path that is not readable.
	Cwd() string

	// MaskedAbs returns a masked absolute path, if it exists within the
	// configured VFS layer. For VFS-FS, the base path will be masked; for
	// VFS-zip, the zip file name will be masked; and for VFS-HTTP, the URL will
	// be masked. Masked strings will be replaced with "vfs://".
	MaskedAbs(string) (string, error)

	// Mutable returns a MutableFS instance of the file system or ErrReadOnly if
	// the file system is read-only.
	//
	// Errors returned from this function are independent of whether or not the
	// underlying file system actually supports mutability; for example, if a
	// mutable file system implements the MutableFS interface, this will return
	// an ErrReadOnly if the ReadOnly() method returns true.
	Mutable() MutableFS

	// ReadOnly returns the read only state of the current VFS layer. As of this
	// writing, only the persistent FS may return false.
	ReadOnly() bool

	// SetReadOnly state for the current VFS.
	SetReadOnly(bool)
}

func Auto 

func Auto(path string) (VFS, error)

Auto attempts to deduce the nature of `path` and returns the appropriate file system type.

type VFSFile 

type VFSFile interface {
	Base() string
	FS() FS
	VFS() VFS
	MutableFS() MutableFS
}

type WalkDirFunc 

type WalkDirFunc func(string, DirEntry, error) error

Source Files

View all Source files

Directories

Path Synopsis

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.