sh_fs.go

// Code generated by go generate; DO NOT EDIT.
// This file is generated from lesiw.io/fs package helper functions.

package command

import (
	"context"
	"io"
	"iter"
	"time"

	"lesiw.io/fs"
)

// The methods below are convenience wrappers that delegate to lesiw.io/fs
// package-level helper functions. These are kept in sync with lesiw.io/fs
// via code generation to ensure Sh provides ergonomic access to all
//
// filesystem operations with dynamic fallback to underlying helpers.

// Abs returns an absolute representation of path within the filesystem.
//
// If the path is already absolute, Abs returns it cleaned.
// If the path is relative, Abs attempts to resolve it to an absolute path.
//
// The returned path format depends on the filesystem implementation.
// Local filesystems return OS-specific absolute paths (e.g., /home/user/file
// or C:\Users\file). Remote filesystems may return URLs (e.g.,
// s3://bucket/key or https://server/path).
//
// # Files
//
// Returns an absolute representation of the file path.
//
// Requires: [lesiw.io/fs.AbsFS] || (absolute [lesiw.io/fs.WorkDir] in ctx)
//
// # Directories
//
// Returns an absolute representation of the directory path.
//
// Requires: [lesiw.io/fs.AbsFS] || (absolute [lesiw.io/fs.WorkDir] in ctx)
//
// Similar capabilities: [path/filepath.Abs], realpath, pwd.
//
// This is a convenience method that calls [lesiw.io/fs.Abs].
func (sh *Sh) Abs(
	ctx context.Context, name string,
) (string, error) {
	return fs.Abs(ctx, sh.FS(), name)
}

// Append opens a file for appending or adds files to a directory. Analogous
// to: [os.OpenFile] with O_APPEND, echo >>, tar (append mode), 9P Topen with
// OAPPEND.
//
// If the parent directory does not exist and the filesystem implements
// [lesiw.io/fs.MkdirFS], Append automatically creates the parent directories with mode
// 0755 (or the mode specified via [lesiw.io/fs.WithDirMode]).
//
// The returned [lesiw.io/fs.WritePathCloser] must be closed when done. The Path() method
// returns the native filesystem path, or the input path if localization is not
// supported.
//
// # Files
//
// Writes are added to the end of the file. If the file does not exist, it is
// created with mode 0644 (or the mode specified via [lesiw.io/fs.WithFileMode]).
//
// Requires: [lesiw.io/fs.AppendFS] || ([lesiw.io/fs.FS] && [lesiw.io/fs.CreateFS])
//
// # Directories
//
// A trailing slash returns a tar stream writer that extracts files into the
// directory. The directory is created if it doesn't exist. Existing files with
// the same names are overwritten, but other files in the directory are
// preserved.
//
// Requires: [lesiw.io/fs.AppendDirFS] || [lesiw.io/fs.CreateFS]
//
// This is a convenience method that calls [lesiw.io/fs.Append].
func (sh *Sh) Append(
	ctx context.Context, name string,
) (fs.WritePathCloser, error) {
	return fs.Append(ctx, sh.FS(), name)
}

// AppendBuffer returns a lazy-executing writer for appending to the file at
// name. The file is opened for appending on first Write(), not when
// AppendBuffer is called.
//
// Example:
//
//	io.Copy(fs.AppendBuffer(ctx, fsys, "log.txt"), src)
//
// This is a convenience method that calls [lesiw.io/fs.AppendBuffer].
func (sh *Sh) AppendBuffer(
	ctx context.Context, name string,
) io.WriteCloser {
	return fs.AppendBuffer(ctx, sh.FS(), name)
}

// Chmod changes the mode of the named file to mode.
// Analogous to: [os.Chmod], chmod, 9P Twstat.
//
// Requires: [lesiw.io/fs.ChmodFS]
//
// This is a convenience method that calls [lesiw.io/fs.Chmod].
func (sh *Sh) Chmod(
	ctx context.Context, name string, mode fs.Mode,
) error {
	return fs.Chmod(ctx, sh.FS(), name, mode)
}

// Chown changes the numeric uid and gid of the named file.
// Analogous to: [os.Chown], [os.Lchown], chown, 9P Twstat.
// This is typically a Unix-specific operation.
//
// Requires: [lesiw.io/fs.ChownFS]
//
// This is a convenience method that calls [lesiw.io/fs.Chown].
func (sh *Sh) Chown(
	ctx context.Context, name string, uid int, gid int,
) error {
	return fs.Chown(ctx, sh.FS(), name, uid, gid)
}

// Chtimes changes the access and modification times of the named file.
// A zero time.Time value will leave the corresponding file time unchanged.
// Analogous to: [os.Chtimes], touch -t, 9P Twstat.
//
// Requires: [lesiw.io/fs.ChtimesFS]
//
// This is a convenience method that calls [lesiw.io/fs.Chtimes].
func (sh *Sh) Chtimes(
	ctx context.Context, name string, atime time.Time, mtime time.Time,
) error {
	return fs.Chtimes(ctx, sh.FS(), name, atime, mtime)
}

// Close closes a filesystem if it implements io.Closer.
//
// This is a convenience method that calls [lesiw.io/fs.Close].
func (sh *Sh) Close() error {
	return fs.Close(sh.FS())
}

// Create creates or truncates the named file for writing.
// Analogous to: [os.Create], touch, echo >, tar, 9P Tcreate, S3 PutObject.
//
// If the parent directory does not exist and the filesystem implements
// [lesiw.io/fs.MkdirFS], Create automatically creates the parent directories with
// mode 0755 (or the mode specified via [lesiw.io/fs.WithDirMode]).
//
// The returned [lesiw.io/fs.WritePathCloser] must be closed when done. The Path() method
// returns the native filesystem path, or the input path if localization is
// not supported.
//
// # Files
//
// If the file already exists, it is truncated. If the file does not exist,
// it is created with mode 0644 (or the mode specified via [lesiw.io/fs.WithFileMode]).
//
// Requires: [lesiw.io/fs.CreateFS]
//
// # Directories
//
// A trailing slash empties the directory (or creates it if it doesn't exist)
// and returns a tar stream writer for extracting files into it. This is
// equivalent to Truncate(name, 0) followed by Append(name).
//
// Requires: See [lesiw.io/fs.Truncate] and [lesiw.io/fs.Append] requirements
//
// This is a convenience method that calls [lesiw.io/fs.Create].
func (sh *Sh) Create(
	ctx context.Context, name string,
) (fs.WritePathCloser, error) {
	return fs.Create(ctx, sh.FS(), name)
}

// CreateBuffer returns a lazy-executing writer for the file at name.
// The file is created on first Write(), not when CreateBuffer is called.
//
// Example:
//
//	io.Copy(fs.CreateBuffer(ctx, fsys, "output.txt"), src)
//
// This is a convenience method that calls [lesiw.io/fs.CreateBuffer].
func (sh *Sh) CreateBuffer(
	ctx context.Context, name string,
) io.WriteCloser {
	return fs.CreateBuffer(ctx, sh.FS(), name)
}

// Glob returns the names of all files matching pattern.
// Analogous to: [io/fs.Glob], [path.Match], glob, find, 9P walk.
//
// The pattern syntax is the same as in [path.Match]. The pattern may
// describe hierarchical names such as usr/*/bin/ed.
//
// Glob ignores file system errors such as I/O errors reading directories.
// The only possible returned error is [path.ErrBadPattern], reporting that
// the pattern is malformed.
//
// Requires: [lesiw.io/fs.GlobFS] ||
// ([lesiw.io/fs.StatFS] && ([lesiw.io/fs.ReadDirFS] || [lesiw.io/fs.WalkFS]))
//
// This is a convenience method that calls [lesiw.io/fs.Glob].
func (sh *Sh) Glob(
	ctx context.Context, pattern string,
) ([]string, error) {
	return fs.Glob(ctx, sh.FS(), pattern)
}

// Localize converts a path from Unix-style to native.
//
// This is typically a lexical operation.
// For canonical path representation, use [lesiw.io/fs.Abs].
//
// Localize may be called with an already-localized path and should return the
// same path unchanged (idempotent behavior).
//
// Requires: [lesiw.io/fs.LocalizeFS]
//
// This is a convenience method that calls [lesiw.io/fs.Localize].
func (sh *Sh) Localize(
	ctx context.Context, path string,
) (string, error) {
	return fs.Localize(ctx, sh.FS(), path)
}

// Lstat returns FileInfo describing the named file.
// Analogous to: [os.Lstat], stat (without -L).
// If the file is a symbolic link, the returned FileInfo describes the
// symbolic link. Lstat makes no attempt to follow the link.
//
// Requires: [lesiw.io/fs.ReadLinkFS] || [lesiw.io/fs.StatFS]
//
// This is a convenience method that calls [lesiw.io/fs.Lstat].
func (sh *Sh) Lstat(
	ctx context.Context, name string,
) (fs.FileInfo, error) {
	return fs.Lstat(ctx, sh.FS(), name)
}

// Mkdir creates a new directory.
// Analogous to: [os.Mkdir], mkdir.
//
// The directory mode is obtained from [lesiw.io/fs.DirMode](ctx). If not set in the
// context, the default mode 0755 is used:
//
//	ctx = fs.WithDirMode(ctx, 0700)
//	fs.Mkdir(ctx, fsys, "private")  // Creates with mode 0700
//
// Mkdir returns an error if the directory already exists or if the parent
// directory does not exist. Use [lesiw.io/fs.MkdirAll] to create parent directories
// automatically.
//
// Requires: [lesiw.io/fs.MkdirFS]
//
// This is a convenience method that calls [lesiw.io/fs.Mkdir].
func (sh *Sh) Mkdir(
	ctx context.Context, name string,
) error {
	return fs.Mkdir(ctx, sh.FS(), name)
}

// MkdirAll creates a directory named name, along with any necessary parents.
// Analogous to: [os.MkdirAll], mkdir -p.
//
// The directory mode is obtained from [lesiw.io/fs.DirMode](ctx). If not set in the
// context, the default mode 0755 is used:
//
//	ctx = fs.WithDirMode(ctx, 0700)
//	fs.MkdirAll(ctx, fsys, "a/b/c")  // All created with mode 0700
//
// If name is already a directory, MkdirAll does nothing and returns nil.
//
// Requires: [lesiw.io/fs.MkdirAllFS] || ([lesiw.io/fs.MkdirFS] && [lesiw.io/fs.StatFS])
//
// This is a convenience method that calls [lesiw.io/fs.MkdirAll].
func (sh *Sh) MkdirAll(
	ctx context.Context, name string,
) error {
	return fs.MkdirAll(ctx, sh.FS(), name)
}

// Open opens the named file or directory for reading.
// Analogous to: [io/fs.Open], [os.Open], cat, tar, 9P Topen, S3 GetObject.
//
// All paths use forward slashes (/) regardless of the operating system,
// following [io/fs] conventions. Use the [lesiw.io/fs.path] package (not [path/filepath])
// for path manipulation. Implementations handle OS-specific conversion
// internally.
//
// The returned [lesiw.io/fs.ReadPathCloser] must be closed when done. The Path() method
// returns the native filesystem path, or the input path if localization is
// not supported.
//
// # Files
//
// Returns a [lesiw.io/fs.ReadPathCloser] for reading the file contents.
//
// Requires: [lesiw.io/fs.FS]
//
// # Directories
//
// A trailing slash returns a tar archive stream of the directory contents.
// A path identified as a directory via [lesiw.io/fs.StatFS] also returns a tar archive.
//
// Requires: [lesiw.io/fs.DirFS] || ([lesiw.io/fs.FS] && ([lesiw.io/fs.ReadDirFS] || [lesiw.io/fs.WalkFS]))
//
// This is a convenience method that calls [lesiw.io/fs.Open].
func (sh *Sh) Open(
	ctx context.Context, name string,
) (fs.ReadPathCloser, error) {
	return fs.Open(ctx, sh.FS(), name)
}

// OpenBuffer returns a lazy-executing reader for the file at name.
// The file is opened on first Read(), not when OpenBuffer is called.
//
// Example:
//
//	io.Copy(dst, fs.OpenBuffer(ctx, fsys, "input.txt"))
//
// This is a convenience method that calls [lesiw.io/fs.OpenBuffer].
func (sh *Sh) OpenBuffer(
	ctx context.Context, name string,
) io.ReadCloser {
	return fs.OpenBuffer(ctx, sh.FS(), name)
}

// ReadDir reads the named directory and returns an iterator over its
// entries. Analogous to: [os.ReadDir], [io/fs.ReadDir], ls, 9P Tread on
// directory.
//
// Requires: [lesiw.io/fs.ReadDirFS] || [lesiw.io/fs.WalkFS]
//
// This is a convenience method that calls [lesiw.io/fs.ReadDir].
func (sh *Sh) ReadDir(
	ctx context.Context, name string,
) iter.Seq2[fs.DirEntry, error] {
	return fs.ReadDir(ctx, sh.FS(), name)
}

// ReadFile reads the named file and returns its contents.
// Analogous to: [io/fs.ReadFile], [os.ReadFile], cat.
//
// Requires: [lesiw.io/fs.FS]
//
// This is a convenience method that calls [lesiw.io/fs.ReadFile].
func (sh *Sh) ReadFile(
	ctx context.Context, name string,
) ([]byte, error) {
	return fs.ReadFile(ctx, sh.FS(), name)
}

// ReadLink returns the destination of the named symbolic link.
// Analogous to: [os.Readlink], readlink, 9P2000.u Treadlink.
// If the link destination is relative, ReadLink returns the relative path
// without resolving it to an absolute one.
//
// Requires: [lesiw.io/fs.ReadLinkFS]
//
// This is a convenience method that calls [lesiw.io/fs.ReadLink].
func (sh *Sh) ReadLink(
	ctx context.Context, name string,
) (string, error) {
	return fs.ReadLink(ctx, sh.FS(), name)
}

// Remove removes the named file or empty directory.
// Analogous to: [os.Remove], rm, 9P Tremove, S3 DeleteObject.
// Returns an error if the file does not exist or if a directory is not
// empty.
//
// Requires: [lesiw.io/fs.RemoveFS]
//
// This is a convenience method that calls [lesiw.io/fs.Remove].
func (sh *Sh) Remove(
	ctx context.Context, name string,
) error {
	return fs.Remove(ctx, sh.FS(), name)
}

// RemoveAll removes name and any children it contains.
// Analogous to: [os.RemoveAll], rm -rf.
//
// Requires: [lesiw.io/fs.RemoveAllFS] ||
// ([lesiw.io/fs.RemoveFS] && [lesiw.io/fs.StatFS] && ([lesiw.io/fs.ReadDirFS] || [lesiw.io/fs.WalkFS]))
//
// This is a convenience method that calls [lesiw.io/fs.RemoveAll].
func (sh *Sh) RemoveAll(
	ctx context.Context, name string,
) error {
	return fs.RemoveAll(ctx, sh.FS(), name)
}

// Rename renames (moves) oldname to newname.
// Analogous to: [os.Rename], mv, 9P2000.u Trename.
// If newname already exists and is not a directory, Rename replaces it.
//
// Requires: [lesiw.io/fs.RenameFS] || ([lesiw.io/fs.FS] && [lesiw.io/fs.CreateFS] && [lesiw.io/fs.RemoveFS])
//
// This is a convenience method that calls [lesiw.io/fs.Rename].
func (sh *Sh) Rename(
	ctx context.Context, oldname string, newname string,
) error {
	return fs.Rename(ctx, sh.FS(), oldname, newname)
}

// Stat returns file metadata for the named file.
// Analogous to: [io/fs.Stat], [os.Stat], stat, ls -l, 9P Tstat,
// S3 HeadObject.
//
// Requires: [lesiw.io/fs.StatFS]
//
// This is a convenience method that calls [lesiw.io/fs.Stat].
func (sh *Sh) Stat(
	ctx context.Context, name string,
) (fs.FileInfo, error) {
	return fs.Stat(ctx, sh.FS(), name)
}

// Symlink creates newname as a symbolic link to oldname.
// Analogous to: [os.Symlink], ln -s, 9P2000.u Tsymlink.
//
// Requires: [lesiw.io/fs.SymlinkFS]
//
// This is a convenience method that calls [lesiw.io/fs.Symlink].
func (sh *Sh) Symlink(
	ctx context.Context, oldname string, newname string,
) error {
	return fs.Symlink(ctx, sh.FS(), oldname, newname)
}

// Temp creates a temporary file or directory.
// Analogous to: [os.CreateTemp], [os.MkdirTemp], mktemp.
//
// The returned [lesiw.io/fs.WritePathCloser] must be closed when done. Path() returns
// the full path to the created resource. The caller is responsible for
// removing the temporary resource when done (typically with [lesiw.io/fs.RemoveAll]).
//
// # Files
//
// Without a trailing separator, creates a temporary file.
// The name parameter serves as a prefix or pattern (implementation-specific).
// The file name will typically have the pattern: name-randomhex
//
// Requires: [lesiw.io/fs.TempFS] || [lesiw.io/fs.TempDirFS] || [lesiw.io/fs.CreateFS]
//
// # Directories
//
// With a trailing separator, creates a temporary directory and returns a tar
// stream writer for extracting files into it. The directory name will
// typically have the pattern: name-randomhex
//
// Requires: [lesiw.io/fs.TempDirFS] || [lesiw.io/fs.MkdirFS]
//
// This is a convenience method that calls [lesiw.io/fs.Temp].
func (sh *Sh) Temp(
	ctx context.Context, name string,
) (fs.WritePathCloser, error) {
	return fs.Temp(ctx, sh.FS(), name)
}

// Truncate changes the size of the named file or empties a directory.
// Analogous to: [os.Truncate], truncate, 9P Twstat.
//
// Like [os.Truncate], Truncate returns an error if the path doesn't exist.
// If [lesiw.io/fs.StatFS] is available, the existence check happens before attempting the
// operation. Otherwise, the error comes from the truncate operation itself.
//
// # Files
//
// If the file is larger than size, it is truncated. If it is smaller, it is
// extended with zeros.
//
// Requires: [lesiw.io/fs.TruncateFS] || ([lesiw.io/fs.FS] && [lesiw.io/fs.RemoveFS] && [lesiw.io/fs.CreateFS])
//
// # Directories
//
// A trailing slash indicates a directory. Removes all contents, leaving an
// empty directory.
//
// Requires: [lesiw.io/fs.TruncateDirFS] || ([lesiw.io/fs.RemoveAllFS] && [lesiw.io/fs.MkdirFS])
//
// This is a convenience method that calls [lesiw.io/fs.Truncate].
func (sh *Sh) Truncate(
	ctx context.Context, name string, size int64,
) error {
	return fs.Truncate(ctx, sh.FS(), name, size)
}

// Walk traverses the filesystem rooted at root.
// Analogous to: [io/fs.WalkDir], find, tree.
//
// The depth parameter controls how deep to traverse (like find -maxdepth):
//   - depth <= 0: unlimited depth (like find without -maxdepth)
//   - depth >= 1: root directory plus n-1 levels of subdirectories
//     (like find -maxdepth n)
//
// Walk does not guarantee any particular order (lexicographic or
// breadth-first). Implementations may choose whatever order is most
// efficient.
//
// Walk does not follow symbolic links. Entries are yielded for symbolic
// links themselves, but they are not traversed.
//
// Entries returned by Walk have Path() populated with the full path.
//
// If an error occurs reading a directory, the iteration yields a zero
// DirEntry and the error. The caller can choose to continue iterating
// (skip that directory) or break to stop the walk.
//
// Requires: [lesiw.io/fs.WalkFS] || [lesiw.io/fs.ReadDirFS]
//
// This is a convenience method that calls [lesiw.io/fs.Walk].
func (sh *Sh) Walk(
	ctx context.Context, root string, depth int,
) iter.Seq2[fs.DirEntry, error] {
	return fs.Walk(ctx, sh.FS(), root, depth)
}

// WriteFile writes data to the named file in the filesystem.
// It creates the file or truncates it if it already exists.
// The file is created with mode 0644 (or the mode specified via
// WithFileMode).
//
// Like os.WriteFile, this always truncates existing files to zero length
// before writing.
//
// If the parent directory does not exist and the filesystem implements
// MkdirFS, WriteFile automatically creates the parent directories with
// mode 0755 (or the mode specified via WithDirMode).
//
// This is analogous to os.WriteFile and io/fs.ReadFile.
//
// Requires: [lesiw.io/fs.CreateFS]
//
// This is a convenience method that calls [lesiw.io/fs.WriteFile].
func (sh *Sh) WriteFile(
	ctx context.Context, name string, data []byte,
) error {
	return fs.WriteFile(ctx, sh.FS(), name, data)
}