os.go

package pathtype

import (
	"io/fs"
	"os"
	"time"
)

// Executable returns the path name for the executable that started
// the current process. There is no guarantee that the path is still
// pointing to the correct executable. If a symlink was used to start
// the process, depending on the operating system, the result might
// be the symlink or the path it pointed to. If a stable result is
// needed, path/filepath.EvalSymlinks might help.
//
// Executable returns an absolute path unless an error occurred.
//
// The main use case is finding resources located relative to an
// executable.
func Executable() (Path, error) {
	res, err := os.Executable()
	return Path(res), err
}

// Getwd returns a rooted path name corresponding to the
// current directory. If the current directory can be
// reached via multiple paths (due to symbolic links),
// Getwd may return any one of them.
func Getwd() (dir Path, err error) {
	res, err := os.Getwd()
	return Path(res), err
}

// TempDir returns the default directory to use for temporary files.
func TempDir() Path {
	return Path(os.TempDir())
}

// UserCacheDir returns the default root directory to use for user-specific
// cached data. Users should create their own application-specific subdirectory
// within this one and use that.
func UserCacheDir() (Path, error) {
	res, err := os.UserCacheDir()
	return Path(res), err
}

// UserConfigDir returns the default root directory to use for user-specific
// configuration data. Users should create their own application-specific
// subdirectory within this one and use that.
func UserConfigDir() (Path, error) {
	res, err := os.UserConfigDir()
	return Path(res), err
}

// UserHomeDir returns the current user's home directory.
func UserHomeDir() (Path, error) {
	res, err := os.UserHomeDir()
	return Path(res), err
}

// Chdir changes the current working directory to the directory at path.
// If there is an error, it will be of type *os.PathError.
func (path Path) Chdir() error { return os.Chdir(string(path)) }

// Chmod changes the mode of the file at path to mode.
// If there is an error, it will be of type *os.PathError.
func (path Path) Chmod(mode os.FileMode) error { return os.Chmod(string(path), mode) }

// Chown changes the numeric uid and gid of the file at path.
// If there is an error, it will be of type *os.PathError.
// On Windows, it always returns the syscall.EWINDOWS error, wrapped
// in *os.PathError.
func (path Path) Chown(uid, gid int) error { return os.Chown(string(path), uid, gid) }

// Chtimes changes the access and modification times of the file at path.
// If there is an error, it will be of type *os.PathError.
func (path Path) Chtimes(atime time.Time, mtime time.Time) error {
	return os.Chtimes(string(path), atime, mtime)
}

// Create creates or truncates the file at path. 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 os.O_RDWR.
// If there is an error, it will be of type *os.PathError.
func (path Path) Create() (*os.File, error) {
	return os.Create(string(path))
}

// CreateTemp creates a new temporary file in the directory at path,
// opens the file for reading and writing, and returns the resulting 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 the path is empty, CreateTemp uses the default directory for temporary files, as returned by TempDir.
// Multiple programs or goroutines calling CreateTemp simultaneously will not choose the same file.
// The caller can use the file's Name method to find the pathname of the file.
// It is the caller's responsibility to remove the file when it is no longer needed.
func (path Path) CreateTemp(pattern string) (*os.File, error) {
	return os.CreateTemp(string(path), pattern)
}

// DirFS returns a file system (an fs.FS) for the tree of files rooted at the directory at path.
func (path Path) DirFS() fs.FS {
	return os.DirFS(string(path))
}

// Lchown changes the numeric uid and gid of the file at path.
// If the file is a symbolic link, it changes the uid and gid of the link itself.
// If there is an error, it will be of type *PathError.
//
// On Windows, it always returns the syscall.EWINDOWS error, wrapped
// in *os.PathError.
func (path Path) Lchown(uid, gid int) error {
	return os.Lchown(string(path), uid, gid)
}

// Link creates newname as a hard link to path.
// If there is an error, it will be of type *os.LinkError.
func (path Path) Link(newname Path) error {
	return os.Link(string(path), string(newname))
}

// Lstat returns a FileInfo describing the file at path.
// 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 will be of type *os.PathError.
func (path Path) Lstat() (os.FileInfo, error) {
	return os.Lstat(string(path))
}

// Mkdir creates a new directory at path with the specified permission
// bits (before umask).
// If there is an error, it will be of type *os.PathError.
func (path Path) Mkdir(perm os.FileMode) error {
	return os.Mkdir(string(path), perm)
}

// MkdirAll creates a directory at path,
// along with any necessary parents, and returns nil,
// or else returns an error.
// The permission bits perm (before umask) are used for all
// directories that MkdirAll creates.
// If path is already a directory, MkdirAll does nothing
// and returns nil.
func (path Path) MkdirAll(perm os.FileMode) error {
	return os.MkdirAll(string(path), perm)
}

// MkdirTemp creates a new temporary directory at path
// and returns the pathname of the new directory.
// The new directory's name is generated by adding a random string to the end of pattern.
// If pattern includes a "*", the random string replaces the last "*" instead.
// If path is empty, MkdirTemp uses the default directory for temporary files, as returned by TempDir.
// Multiple programs or goroutines calling MkdirTemp simultaneously will not choose the same directory.
// It is the caller's responsibility to remove the directory when it is no longer needed.
func (path Path) MkdirTemp(pattern string) (Path, error) {
	res, err := os.MkdirTemp(string(path), pattern)
	return Path(res), err
}

// Open opens the file at path for reading. If successful, methods on
// the returned file can be used for reading; the associated file
// descriptor has mode os.O_RDONLY.
// If there is an error, it will be of type *os.PathError.
func (path Path) Open() (*os.File, error) {
	return os.Open(string(path))
}

// OpenFile is the generalized open call; most users will use Open
// or Create instead. It opens the file at path with specified flag
// (O_RDONLY etc.). If the file does not exist, and the O_CREATE flag
// is passed, it is created with mode perm (before umask). If successful,
// methods on the returned File can be used for I/O.
// If there is an error, it will be of type *os.PathError.
func (path Path) OpenFile(flag int, perm os.FileMode) (*os.File, error) {
	return os.OpenFile(string(path), flag, perm)
}

// Readlink returns the destination of the symbolic link at path.
// If there is an error, it will be of type *os.PathError.
func (path Path) Readlink() (Path, error) {
	res, err := os.Readlink(string(path))
	return Path(res), err
}

// Remove removes path.
// If there is an error, it will be of type *os.PathError.
func (path Path) Remove() error {
	return os.Remove(string(path))
}

// RemoveAll removes path and any children it contains.
// It removes everything it can but returns the first error
// it encounters. If the path does not exist, RemoveAll
// returns nil (no error).
// If there is an error, it will be of type *os.PathError.
func (path Path) RemoveAll() error {
	return os.RemoveAll(string(path))
}

// Rename renames (moves) path to newpath.
// If newpath already exists and is not a directory, Rename replaces it.
// OS-specific restrictions may apply when path and newpath are in different directories.
// If there is an error, it will be of type *os.LinkError.
func (path Path) Rename(newpath Path) error {
	return os.Rename(string(path), string(newpath))
}

// Stat returns a FileInfo describing the file at path.
// If there is an error, it will be of type *os.PathError.
func (path Path) Stat() (os.FileInfo, error) {
	return os.Stat(string(path))
}

// Symlink creates newname as a symbolic link to the path.
// If there is an error, it will be of type *os.LinkError..
func (path Path) Symlink(newname Path) error {
	return os.Symlink(string(path), string(newname))
}

// Truncate changes the size of the path.
// If the file is a symbolic link, it changes the size of the link's target.
// If there is an error, it will be of type *os.PathError.
func (path Path) Truncate(size int64) error {
	return os.Truncate(string(path), size)
}

// WriteFile writes data to the file at path, creating it if necessary.
// If the file does not exist, WriteFile creates it with permissions perm (before umask);
// otherwise WriteFile truncates it before writing, without changing permissions.
func (path Path) WriteFile(data []byte, perm os.FileMode) error {
	return os.WriteFile(string(path), data, perm)
}