vfs

package
v0.4.3 Latest Latest
Warning

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

 Go to latest Published: Feb 23, 2024 License: Apache-2.0 Imports: 15 Imported by: 211

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

View Source 
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.

View Source 
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.

View Source 
const ModePerm = os.ModePerm
View Source 
const PathSeparatorChar = '/'
View Source 
const PathSeparatorString = "/"

Variables

View Source 
var ErrExist = os.ErrExist
View Source 
var ErrNotDir = errors.New("is no directory")
View Source 
var ErrNotEmpty = errors.New("dir not empty")
View Source 
var ErrNotExist = os.ErrNotExist
View Source 
var ErrPermission = os.ErrPermission
View Source 
var ErrReadOnly = errors.New("filehandle is not writable")
View Source 
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 AsIoFS 

func AsIoFS(fs FileSystem) fs.ReadDirFS

AsIoFS maps a virtual filesystem

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:

  1. Replace multiple path separators with a single one.
  2. Eliminate each . path name element (the current directory).
  3. Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
  4. 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(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 Exists_ 

func Exists_(err error) bool

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 IsErrExist(err error) bool

func IsErrNotDir 

func IsErrNotDir(err error) bool

func IsErrNotExist 

func IsErrNotExist(err error) bool

func IsErrPermission 

func IsErrPermission(err error) bool

func IsErrReadOnly 

func IsErrReadOnly(err error) bool

func IsExist 

func IsExist(err error) bool

func IsFile 

func IsFile(fs FileSystem, path string) (bool, error)

IsFile checks if a given path is a file.

func IsNotExist 

func IsNotExist(err error) bool

func IsPathSeparator 

func IsPathSeparator(c uint8) bool

IsPathSeparator reports whether c is a directory separator character.

func IsPermission 

func IsPermission(err error) bool

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 MatchErr 

func MatchErr(err error, match ErrorMatcher, base error) bool

func NewPathError 

func NewPathError(op string, path string, err error) error

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 Touch 

func Touch(fs FileSystem, path string, perm os.FileMode) error

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

func Walk 

func Walk(fs FileSystem, root string, walkFn WalkFunc) error

func WriteFile 

func WriteFile(fs FileSystem, filename string, data []byte, mode os.FileMode) error

WriteFile writes data to a file named by filename. If the file does not exist, WriteFile creates it with permissions perm (before umask); otherwise WriteFile truncates it before writing.

Types

type DirEntry 

type DirEntry = fs.DirEntry

type ErrorMatcher 

type ErrorMatcher func(err error) bool

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 FileInfo 

type FileInfo = os.FileInfo

type FileMode 

type FileMode = os.FileMode

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

type WalkFunc 

type WalkFunc = filepath.WalkFunc

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.