Documentation ¶
Overview ¶
Package vfs provides a virtual filesystem for GO. It is the main package providing the abstract interfaces and implementation-agnostic utility functions wrapped together with an implementation into a comprehensive user interface VFS. (see https://pkg.go.dev/github.com/mandelsoft/vfs)
- Copyright 2024 Mandelsoft. All rights reserved.
- This file is licensed under the Apache Software License, v. 2 except as noted
- otherwise in the LICENSE file *
- 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.
Index ¶
- Constants
- Variables
- func Abs(fs FileSystem, path string) (string, error)
- func AsIoFS(fs FileSystem) fs.ReadDirFS
- func Base(fs FileSystem, path string) string
- func Canonical(fs FileSystem, path string, exist bool) (string, error)
- func Clean(fs FileSystem, p string) string
- func Cleanup(fs FileSystem) error
- func Components(fs FileSystem, p string) (string, []string)
- func CopyDir(srcfs FileSystem, src string, dstfs FileSystem, dst string) error
- func CopyFile(srcfs FileSystem, src string, dstfs FileSystem, dst string) error
- func Dir(fs FileSystem, path string) string
- func DirExists(fs FileSystem, path string) (bool, error)
- func EvalSymlinks(fs FileSystem, path string) (string, error)
- func Exists(fs FileSystem, path string) (bool, error)
- func Exists_(err error) bool
- func FileExists(fs FileSystem, path string) (bool, error)
- func IsAbs(fs FileSystem, path string) bool
- func IsDir(fs FileSystem, path string) (bool, error)
- func IsErrExist(err error) bool
- func IsErrNotDir(err error) bool
- func IsErrNotExist(err error) bool
- func IsErrPermission(err error) bool
- func IsErrReadOnly(err error) bool
- func IsExist(err error) bool
- func IsFile(fs FileSystem, path string) (bool, error)
- func IsNotExist(err error) bool
- func IsPathSeparator(c uint8) bool
- func IsPermission(err error) bool
- func IsRoot(fs FileSystem, path string) bool
- func Join(fs FileSystem, elems ...string) string
- func MatchErr(err error, match ErrorMatcher, base error) bool
- func NewPathError(op string, path string, err error) error
- func ReadDir(fs FileSystem, path string) ([]os.FileInfo, error)
- func ReadFile(fs FileSystem, path string) ([]byte, error)
- func Rel(fs FileSystem, src, tgt string) (string, error)
- func Split(fs FileSystem, path string) (dir, file string)
- func SplitPath(fs FileSystem, path string) (string, []string, bool)
- func SplitVolume(fs FileSystem, path string) (string, string)
- func TempDir(fs FileSystem, dir, prefix string) (name string, err error)
- func Touch(fs FileSystem, path string, perm os.FileMode) error
- func Trim(fs FileSystem, path string) string
- func Walk(fs FileSystem, root string, walkFn WalkFunc) error
- func WriteFile(fs FileSystem, filename string, data []byte, mode os.FileMode) error
- type DirEntry
- type ErrorMatcher
- type File
- type FileInfo
- type FileMode
- type FileSystem
- type FileSystemCleanup
- type FileSystemWithWorkingDirectory
- type VFS
- type WalkFunc
Constants ¶
const ( // Exactly one of O_RDONLY, O_WRONLY, or O_RDWR must be specified. O_RDONLY = os.O_RDONLY // open the file read-only. O_WRONLY = os.O_WRONLY // open the file write-only. O_RDWR = os.O_RDWR // open the file read-write. // The remaining values may be or'ed in to control behavior. O_APPEND = os.O_APPEND // append data to the file when writing. O_CREATE = os.O_CREATE // create a new file if none exists. O_EXCL = os.O_EXCL // used with O_CREATE, file must not exist. O_SYNC = os.O_SYNC // open for synchronous I/O. O_TRUNC = os.O_TRUNC // truncate regular writable file when opened. )
Flags to OpenFile wrapping those of the underlying system. Not all flags may be implemented on a given system.
const ( SEEK_SET = io.SeekStart // seek relative to the origin of the file SEEK_CUR = io.SeekCurrent // seek relative to the current offset SEEK_END = io.SeekEnd // seek relative to the end )
Seek whence values.
Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
const ModePerm = os.ModePerm
const PathSeparatorChar = '/'
const PathSeparatorString = "/"
Variables ¶
var ErrExist = os.ErrExist
var ErrNotDir = errors.New("is no directory")
var ErrNotEmpty = errors.New("dir not empty")
var ErrNotExist = os.ErrNotExist
var ErrPermission = os.ErrPermission
var ErrReadOnly = errors.New("filehandle is not writable")
var SkipDir = filepath.SkipDir
Functions ¶
func Abs ¶
func Abs(fs FileSystem, path string) (string, error)
Abs returns an absolute representation of path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. Symbolic links in the given path will be resolved, but not in the current working directory, if used to make the path absolute. The denoted file may not exist. Abs never calls Clean on the result, so the resulting path will denote the same file as the argument.
func Base ¶
func Base(fs FileSystem, path string) string
Base extracts the last path component. For the root path it returns the root name, For an empty path . is returned If a FileSystem is given, the file systems volume. handling is applied, otherwise the path argument is handled as a regular plain path
func Canonical ¶
func Canonical(fs FileSystem, path string, exist bool) (string, error)
Canonical returns the canonical absolute path of a file. If exist=false the denoted file must not exist, but then the part of the initial path referring to a not existing directory structure is lexically resolved (like Clean) and does not consider potential symbolic links that might occur if the file is finally created in the future.
func Clean ¶
func Clean(fs FileSystem, p string) string
Clean returns the shortest path name equivalent to path by purely lexical processing. It applies the following rules iteratively until no further processing can be done:
- Replace multiple path separators with a single one.
- Eliminate each . path name element (the current directory).
- Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
- Eliminate .. elements that begin a rooted path: that is, replace "/.." by "/" at the beginning of a path.
The returned path ends in a slash only if it is the root "/".
If the result of this process is an empty string, Clean returns the string ".". If a FileSystem is given, the file systems volume. handling is applied, otherwise the path argument is handled as a regular plain path
func Cleanup ¶
func Cleanup(fs FileSystem) error
func Components ¶
func Components(fs FileSystem, p string) (string, []string)
Components splits a path into its volume part and a list of path components.
func CopyDir ¶
func CopyDir(srcfs FileSystem, src string, dstfs FileSystem, dst string) error
CopyDir recursively copies a directory tree, attempting to preserve permissions. Source directory must exist, destination directory may exist. Symlinks are ignored and skipped.
func CopyFile ¶
func CopyFile(srcfs FileSystem, src string, dstfs FileSystem, dst string) error
func Dir ¶
func Dir(fs FileSystem, path string) string
Dir returns the path's directory dropping the final element after removing trailing Separators, Dir does not call Clean on the path. If the path is empty, Dir returns "." or "/" for a rooted path. If the path consists entirely of Separators, Dir2 returns a single Separator. The returned path does not end in a Separator unless it is the root directory. This function is the counterpart of Base Base("a/b/")="b" and Dir("a/b/") = "a". If a FileSystem is given, the file systems volume. handling is applied, otherwise the path argument is handled as a regular plain path
func DirExists ¶
func DirExists(fs FileSystem, path string) (bool, error)
DirExists checks if a path exists and is a directory.
func EvalSymlinks ¶
func EvalSymlinks(fs FileSystem, path string) (string, error)
EvalSymlinks resolves all symbolic links in a path and returns a path not containing any symbolic link anymore. It does not call Clean on a non-canonical path, so the result always denotes the same file than the original path. If the given path is a relative one, a relative one is returned as long as there is no absolute symbolic link. It may contain `..`, if it is above the current working directory
func Exists ¶
func Exists(fs FileSystem, path string) (bool, error)
Exists checks if a file or directory exists.
func FileExists ¶
func FileExists(fs FileSystem, path string) (bool, error)
FileExists checks if a path exists and is a regular file.
func IsAbs ¶
func IsAbs(fs FileSystem, path string) bool
IsAbs return true if the given path is an absolute one starting with a Separator or is quailified by a volume name.
func IsDir ¶
func IsDir(fs FileSystem, path string) (bool, error)
IsDir checks if a given path is a directory.
func IsErrExist ¶
func IsErrNotDir ¶
func IsErrNotExist ¶
func IsErrPermission ¶
func IsErrReadOnly ¶
func IsFile ¶
func IsFile(fs FileSystem, path string) (bool, error)
IsFile checks if a given path is a file.
func IsNotExist ¶
func IsPathSeparator ¶
IsPathSeparator reports whether c is a directory separator character.
func IsPermission ¶
func IsRoot ¶
func IsRoot(fs FileSystem, path string) bool
IsRoot determines whether a given path is a root path. This might be the separator or the separator preceded by a volume name.
func Join ¶
func Join(fs FileSystem, elems ...string) string
Join joins any number of path elements into a single path, adding a Separator if necessary. Join never calls Clean on the result to assure the result denotes the same file as the input. Empty entries will be ignored. If a FileSystem is given, the file systems volume. handling is applied, otherwise the path argument is handled as a regular plain path
func ReadDir ¶
func ReadDir(fs FileSystem, path string) ([]os.FileInfo, error)
ReadDir reads the directory named by path and returns a list of directory entries sorted by filename.
func ReadFile ¶
func ReadFile(fs FileSystem, path string) ([]byte, error)
ReadFile reads the file named by filename and returns the contents. A successful call returns err == nil, not err == EOF. Because ReadFile reads the whole file, it does not treat an EOF from Read as an error to be reported.
func Rel ¶
func Rel(fs FileSystem, src, tgt string) (string, error)
Rel determines the relative path from a source folder to a target file.
func Split ¶
func Split(fs FileSystem, path string) (dir, file string)
Split splits path immediately following the final Separator, separating it into a directory and file name component. If there is no Separator in path, Split returns an empty dir and file set to path. In contrast to filepath.Split the directory path does not end with a trailing Separator, so Split can subsequently called for the directory part, again.
func SplitPath ¶
func SplitPath(fs FileSystem, path string) (string, []string, bool)
SplitPath splits a path into a volume and an array of the path segments
func SplitVolume ¶
func SplitVolume(fs FileSystem, path string) (string, string)
func TempDir ¶
func TempDir(fs FileSystem, dir, prefix string) (name string, err error)
TempDir creates a new temporary directory in the directory dir with a name beginning with prefix and returns the path of the new directory. If dir is the empty string, TempDir uses the default directory for temporary files (see os.TempDir). Multiple programs calling TempDir simultaneously will not choose the same directory. It is the caller's responsibility to remove the directory when no longer needed.
func Trim ¶
func Trim(fs FileSystem, path string) string
Trim eliminates trailing slashes from a path name. An empty path is unchanged. If a FileSystem is given, the file systems volume handling is applied, otherwise the path argument is handled as a regular plain path
Types ¶
type ErrorMatcher ¶
type File ¶
type File interface { io.Closer io.Reader io.ReaderAt io.Seeker io.Writer io.WriterAt Name() string ReadDir(count int) ([]DirEntry, error) Readdir(count int) ([]FileInfo, error) Readdirnames(n int) ([]string, error) Stat() (FileInfo, error) Sync() error Truncate(size int64) error WriteString(s string) (ret int, err error) }
func TempFile ¶
func TempFile(fs FileSystem, dir, pattern string) (f File, err error)
TempFile creates a new temporary file in the directory dir, opens the file for reading and writing, and returns the resulting *os.File. The filename is generated by taking pattern and adding a random string to the end. If pattern includes a "*", the random string replaces the last "*". If dir is the empty string, TempFile uses the default directory for temporary files (see os.TempDir). Multiple programs calling TempFile simultaneously will not choose the same file. The caller can use f.Name() to find the pathname of the file. It is the caller's responsibility to remove the file when no longer needed.
type FileSystem ¶
type FileSystem interface { // VolumeName returns leading volume name. // Given "C:\foo\bar" it returns "C:" on Windows. // Given "\\host\share\foo" it returns "\\host\share". // On other platforms it returns "". VolumeName(name string) string // FSTempDir (similar to os.TempDir) provides // the dir to use fortemporary files for this filesystem FSTempDir() string // Normalize returns a path in the normalized vfs path syntax Normalize(name string) string // Create creates a file in the filesystem, returning the file and an // error, if any happens. Create(name string) (File, error) // Mkdir creates a directory in the filesystem, return an error if any // happens. Mkdir(name string, perm FileMode) error // MkdirAll creates a directory path and all parents that does not exist // yet. MkdirAll(path string, perm FileMode) error // Open opens a file, returning it or an error, if any happens. Open(name string) (File, error) // OpenFile opens a file using the given flags and the given mode. OpenFile(name string, flags int, perm FileMode) (File, error) // Remove removes a file identified by name, returning an error, if any // happens. Remove(name string) error // RemoveAll removes a directory path and any children it contains. It // does not fail if the path does not exist (return nil). RemoveAll(path string) error // Rename renames a file. Rename(oldname, newname string) error // Stat returns a FileInfo describing the named file, or an error, if any // happens. Stat(name string) (FileInfo, error) // Lstat returns a FileInfo describing the named file, or an error, if any // happens. // If the file is a symbolic link, the returned FileInfo // describes the symbolic link. Lstat makes no attempt to follow the link. Lstat(name string) (FileInfo, error) // Create a symlink if supported Symlink(oldname, newname string) error // Read a symlink if supported Readlink(name string) (string, error) // Name returns the spec of this FileSystem Name() string // Chmod changes the mode of the named file to mode. Chmod(name string, mode FileMode) error // Chtimes changes the access and modification times of the named file Chtimes(name string, atime time.Time, mtime time.Time) error // Getwd return the absolute path of the working directory of the // file system Getwd() (string, error) }
type FileSystemCleanup ¶
type FileSystemCleanup interface { FileSystem // Cleanup should remove all temporary resources allocated // for this file system Cleanup() error }
type FileSystemWithWorkingDirectory ¶
type FileSystemWithWorkingDirectory interface { FileSystem Chdir(path string) error }
type VFS ¶
type VFS interface { FileSystemCleanup Join(elems ...string) string Split(path string) (string, string) Components(path string) (string, []string) Base(path string) string Dir(path string) string Clean(path string) string Trim(path string) string IsAbs(path string) bool IsRoot(path string) bool SplitVolume(path string) (string, string) SplitPath(path string) (vol string, elems []string, rooted bool) Canonical(path string, exist bool) (string, error) Abs(path string) (string, error) Rel(src, tgt string) (string, error) EvalSymlinks(path string) (string, error) Walk(path string, fn WalkFunc) error Exists(path string) (bool, error) FileExists(path string) (bool, error) DirExists(path string) (bool, error) IsDir(path string) (bool, error) IsFile(path string) (bool, error) ReadDir(path string) ([]FileInfo, error) ReadFile(path string) ([]byte, error) WriteFile(path string, data []byte, mode FileMode) error TempFile(dir, prefix string) (File, error) TempDir(dir, prefix string) (string, error) }
func New ¶
func New(fs FileSystem) VFS