Skip to content

os.md

Latest commit

 

History

History
560 lines (387 loc) · 16.3 KB

os.md

File metadata and controls

560 lines (387 loc) · 16.3 KB
Raw

os

import "github.com/c2fo/vfs/v7/backend/os"

Package os - built-in os lib VFS implementation.

Usage

The OS backend interacts directly with the local operating system's file system.

It can be initialized using the backend registry:

import(
    "github.com/c2fo/vfs/v7/backend"
    _os "github.com/c2fo/vfs/v7/backend/os"
)

func UseFs() error {
    fs := backend.Backend(_os.Scheme)
    // Use fs
    ...
}

Or by calling directly:

import _os "github.com/c2fo/vfs/v7/backend/os"

func DoSomething() {
    fs := _os.NewFileSystem()

    // Or with a custom temporary directory
    fsWithOpts := _os.NewFileSystem(
        _os.WithTempDir{TempDir: "/path/to/my/temp"},
    )
    ...
}

Options

The OS backend supports the following options for NewFileSystem:

  • WithTempDir: Specifies a custom directory path for temporary files used during write operations. If not provided, the backend uses the system temp directory when it's on the same device as the target file, or falls back to the target file's parent directory.

Read\-only files

Reading does not require write access. Read and Seek open the existing file with os.O_RDONLY (and never create it), so files the process cannot write to can be read, seeked and copied from. Writes are staged in a temp file and renamed over the original on Close, and Close only needs the original's name, so replacing a read-only file requires write permission on its directory rather than on the file itself. (On Windows the rename is refused while the file carries the read-only attribute.)

See Also

See: https://golang.org/pkg/os/

Index

Constants

Scheme defines the file system type.

const Scheme = "file"

type File

File implements vfs.File interface for os fs.

type File struct {
    // contains filtered or unexported fields
}

func (*File) Close

func (f *File) Close() error

Close implements the io.Closer interface, closing the underlying *os.File. its an error, if any.

func (*File) CopyToFile

func (f *File) CopyToFile(file vfs.File) error

CopyToFile copies the file to a new File. It accepts a vfs.File and returns an error, if any.

func (*File) CopyToLocation

func (f *File) CopyToLocation(location vfs.Location) (vfs.File, error)

CopyToLocation copies existing File to new Location with the same name. It accepts a vfs.Location and returns a vfs.File and error, if any.

func (*File) Delete

func (f *File) Delete(_ ...options.DeleteOption) error

Delete unlinks the file returning any error or nil.

func (*File) Exists

func (f *File) Exists() (bool, error)

Exists true if the file exists on the file system, otherwise false, and an error, if any.

func (*File) LastModified

func (f *File) LastModified() (*time.Time, error)

LastModified returns the timestamp of the file's mtime or error, if any.

func (*File) Location

func (f *File) Location() vfs.Location

Location returns the underlying os.Location.

func (*File) MoveToFile

func (f *File) MoveToFile(file vfs.File) error

MoveToFile move a file. It accepts a target vfs.File and returns an error, if any.

func (*File) MoveToLocation

func (f *File) MoveToLocation(location vfs.Location) (vfs.File, error)

MoveToLocation moves a file to a new Location. It accepts a target vfs.Location and returns a vfs.File and an error, if any.

func (*File) Name

func (f *File) Name() string

Name returns the base name of the file path.

For `file:///some/path/to/file.txt`, it would return `file.txt`

func (*File) Path

func (f *File) Path() string

Path returns absolute path, including filename, For `file:///some/path/to/file.txt`, it would return `/some/path/to/file.txt`

If the directory portion of a file is desired, call

someFile.Location().Path()

func (*File) Read

func (f *File) Read(p []byte) (int, error)

Read implements the io.Reader interface. It returns the bytes read and an error, if any.

func (*File) Seek

func (f *File) Seek(offset int64, whence int) (int64, error)

Seek implements the io.Seeker interface. It accepts an offset and "whence" where 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.

func (*File) Size

func (f *File) Size() (uint64, error)

Size returns the size (in bytes) of the File or any error.

func (*File) String

func (f *File) String() string

String implement fmt.Stringer, returning the file's URI as the default string.

func (*File) Touch

func (f *File) Touch() error

Touch creates a zero-length file on the vfs.File if no File exists. Update File's last modified timestamp. Returns error if unable to touch File.

func (*File) URI

func (f *File) URI() string

URI returns the File's URI as a string.

func (*File) Write

func (f *File) Write(p []byte) (n int, err error)

Write implements the io.Writer interface. It accepts a slice of bytes and returns the number of bytes written and an error, if any.

type FileSystem

FileSystem implements vfs.FileSystem for the OS file system.

type FileSystem struct {
    // contains filtered or unexported fields
}

func NewFileSystem

func NewFileSystem(opts ...options.NewFileSystemOption[FileSystem]) *FileSystem

NewFileSystem creates a new instance of the OS file system.

func (*FileSystem) Name

func (fs *FileSystem) Name() string

Name returns "os"

func (*FileSystem) NewFile

func (fs *FileSystem) NewFile(authorityStr, filePath string, opts ...options.NewFileOption) (vfs.File, error)

NewFile function returns the os implementation of vfs.File.

func (*FileSystem) NewLocation

func (fs *FileSystem) NewLocation(authorityStr, locPath string) (vfs.Location, error)

NewLocation function returns the os implementation of vfs.Location.

func (*FileSystem) Retry

func (fs *FileSystem) Retry() vfs.Retry

Retry will return a retriever provided via options, or a no-op if none is provided.

Deprecated: This method is deprecated and will be removed in a future release.

func (*FileSystem) Scheme

func (fs *FileSystem) Scheme() string

Scheme return "file" as the initial part of a file URI ie: file://

type Location

Location implements the vfs.Location interface specific to OS fs.

type Location struct {
    // contains filtered or unexported fields
}

func (*Location) Authority

func (l *Location) Authority() authority.Authority

Authority returns the location's authority as a string.

func (*Location) ChangeDir

func (l *Location) ChangeDir(relativePath string) error

ChangeDir takes a relative path, and modifies the underlying Location's path. The caller is modified by this so the only return is any error. For this implementation there are no errors.

Deprecated: Use NewLocation instead:

loc, err := loc.NewLocation("../../")

func (*Location) DeleteFile

func (l *Location) DeleteFile(fileName string, opts ...options.DeleteOption) error

DeleteFile deletes the file of the given name at the location. This is meant to be a short cut for instantiating a new file and calling delete on that with all the necessary error handling overhead.

func (*Location) Exists

func (l *Location) Exists() (bool, error)

Exists returns true if the location exists, and the calling user has the appropriate permissions. Will receive false without an error if the location simply doesn't exist. Otherwise could receive false and any errors passed back from the OS.

func (*Location) FileSystem

func (l *Location) FileSystem() vfs.FileSystem

FileSystem returns a vfs.FileSystem interface of the location's underlying file system.

func (*Location) List

func (l *Location) List() ([]string, error)

List returns a slice of all files in the top directory of the location.

func (*Location) ListByPrefix

func (l *Location) ListByPrefix(prefix string) ([]string, error)

ListByPrefix returns a slice of all files starting with "prefix" in the top directory of the location.

func (*Location) ListByRegex

func (l *Location) ListByRegex(regex *regexp.Regexp) ([]string, error)

ListByRegex returns a slice of all files matching the regex in the top directory of the location.

func (*Location) ListEntries

func (l *Location) ListEntries(ctx context.Context, opts ...options.ListOption) iter.Seq2[vfs.Entry, error]

ListEntries lists the location's contents as a stream of entries in byte order, implementing vfs.EntryLister. Use list.Entries to list a location with options and have every option applied.

Each directory is read when the listing reaches it, so memory use is one directory per level of depth. File entries carry the size, modification time and mode the operating system reported. A symbolic link is listed as a file entry whose Type is fs.ModeSymlink, and is not followed, so a link to a directory is not descended into. A directory that cannot be read is yielded with its entry and an error, and the listing continues.

func (*Location) NewFile

func (l *Location) NewFile(fileName string, opts ...options.NewFileOption) (vfs.File, error)

NewFile uses the properties of the calling location to generate a vfs.File (backed by an os.File). A string argument is expected to be a relative path to the location's current path.

func (*Location) NewLocation

func (l *Location) NewLocation(relativePath string) (vfs.Location, error)

NewLocation makes a copy of the underlying Location, then modifies its path by calling ChangeDir with the relativePath argument, returning the resulting location. The only possible errors come from the call to ChangeDir.

func (*Location) Path

func (l *Location) Path() string

Path returns the location path.

func (*Location) String

func (l *Location) String() string

String implement fmt.Stringer, returning the location's URI as the default string.

func (*Location) URI

func (l *Location) URI() string

URI returns the Location's URI as a string.

func (*Location) Volume

func (l *Location) Volume() string

Volume returns the volume, if any, of the location. Given "C:\foo\bar" it returns "C:" on Windows. On other platforms it returns "".

Deprecated: Use Authority instead.

authStr := loc.Authority().String()

type WithTempDir

WithTempDir specifies a custom directory for intermediate temporary files used during write operations. This is useful when the system temp directory is on a different device/volume than the target file, which would otherwise cause cross-device rename errors.

type WithTempDir struct {
    TempDir string
}

func (WithTempDir) Apply

func (o WithTempDir) Apply(fs *FileSystem)

Apply applies the temp dir option to the given FileSystem.

func (WithTempDir) NewFileSystemOptionName

func (o WithTempDir) NewFileSystemOptionName() string

NewFileSystemOptionName returns the option name.

Generated by gomarkdoc