// Generated by Lisette bindgen
// Source: io/fs (Go stdlib)
// Go: 1.25.10
// Lisette: 0.3.0

import "go:time"

/// FileInfoToDirEntry returns a [DirEntry] that returns information from info.
/// If info is nil, FileInfoToDirEntry returns nil.
pub fn FileInfoToDirEntry(info: FileInfo) -> Option<DirEntry>

/// FormatDirEntry returns a formatted version of dir for human readability.
/// Implementations of [DirEntry] can call this from a String method.
/// The outputs for a directory named subdir and a file named hello.go are:
/// 
/// 	d subdir/
/// 	- hello.go
pub fn FormatDirEntry(dir: DirEntry) -> string

/// FormatFileInfo returns a formatted version of info for human readability.
/// Implementations of [FileInfo] can call this from a String method.
/// The output for a file named "hello.go", 100 bytes, mode 0o644, created
/// January 1, 1970 at noon is
/// 
/// 	-rw-r--r-- 100 1970-01-01 12:00:00 hello.go
pub fn FormatFileInfo(info: FileInfo) -> string

/// Glob returns the names of all files matching pattern or nil
/// if there is no matching file. The syntax of patterns 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.
/// 
/// If fs implements [GlobFS], Glob calls fs.Glob.
/// Otherwise, Glob uses [ReadDir] to traverse the directory tree
/// and look for matches for the pattern.
pub fn Glob(fsys: FS, pattern: string) -> Result<Slice<string>, error>

/// Lstat returns a [FileInfo] describing the named file.
/// If the file is a symbolic link, the returned [FileInfo] describes the symbolic link.
/// Lstat makes no attempt to follow the link.
/// 
/// If fsys does not implement [ReadLinkFS], then Lstat is identical to [Stat].
pub fn Lstat(fsys: FS, name: string) -> Result<FileInfo, error>

/// ReadDir reads the named directory
/// and returns a list of directory entries sorted by filename.
/// 
/// If fs implements [ReadDirFS], ReadDir calls fs.ReadDir.
/// Otherwise ReadDir calls fs.Open and uses ReadDir and Close
/// on the returned file.
pub fn ReadDir(fsys: FS, name: string) -> Result<Slice<DirEntry>, error>

/// ReadFile reads the named file from the file system fs and returns its contents.
/// A successful call returns a nil error, not [io.EOF].
/// (Because ReadFile reads the whole file, the expected EOF
/// from the final Read is not treated as an error to be reported.)
/// 
/// If fs implements [ReadFileFS], ReadFile calls fs.ReadFile.
/// Otherwise ReadFile calls fs.Open and uses Read and Close
/// on the returned [File].
pub fn ReadFile(fsys: FS, name: string) -> Result<Slice<byte>, error>

/// ReadLink returns the destination of the named symbolic link.
/// 
/// If fsys does not implement [ReadLinkFS], then ReadLink returns an error.
pub fn ReadLink(fsys: FS, name: string) -> Result<string, error>

/// Stat returns a [FileInfo] describing the named file from the file system.
/// 
/// If fs implements [StatFS], Stat calls fs.Stat.
/// Otherwise, Stat opens the [File] to stat it.
pub fn Stat(fsys: FS, name: string) -> Result<FileInfo, error>

/// Sub returns an [FS] corresponding to the subtree rooted at fsys's dir.
/// 
/// If dir is ".", Sub returns fsys unchanged.
/// Otherwise, if fs implements [SubFS], Sub returns fsys.Sub(dir).
/// Otherwise, Sub returns a new [FS] implementation sub that,
/// in effect, implements sub.Open(name) as fsys.Open(path.Join(dir, name)).
/// The implementation also translates calls to ReadDir, ReadFile,
/// ReadLink, Lstat, and Glob appropriately.
/// 
/// Note that Sub(os.DirFS("/"), "prefix") is equivalent to os.DirFS("/prefix")
/// and that neither of them guarantees to avoid operating system
/// accesses outside "/prefix", because the implementation of [os.DirFS]
/// does not check for symbolic links inside "/prefix" that point to
/// other directories. That is, [os.DirFS] is not a general substitute for a
/// chroot-style security mechanism, and Sub does not change that fact.
pub fn Sub(fsys: FS, dir: string) -> Result<FS, error>

/// ValidPath reports whether the given path name
/// is valid for use in a call to Open.
/// 
/// Path names passed to open are UTF-8-encoded,
/// unrooted, slash-separated sequences of path elements, like “x/y/z”.
/// Path names must not contain an element that is “.” or “..” or the empty string,
/// except for the special case that the name "." may be used for the root directory.
/// Paths must not start or end with a slash: “/x” and “x/” are invalid.
/// 
/// Note that paths are slash-separated on all systems, even Windows.
/// Paths containing other characters such as backslash and colon
/// are accepted as valid, but those characters must never be
/// interpreted by an [FS] implementation as path element separators.
pub fn ValidPath(name: string) -> bool

/// WalkDir walks the file tree rooted at root, calling fn for each file or
/// directory in the tree, including root.
/// 
/// All errors that arise visiting files and directories are filtered by fn:
/// see the [fs.WalkDirFunc] documentation for details.
/// 
/// The files are walked in lexical order, which makes the output deterministic
/// but requires WalkDir to read an entire directory into memory before proceeding
/// to walk that directory.
/// 
/// WalkDir does not follow symbolic links found in directories,
/// but if root itself is a symbolic link, its target will be walked.
pub fn WalkDir(fsys: FS, root: string, fn_: WalkDirFunc) -> Result<(), error>

/// A DirEntry is an entry read from a directory
/// (using the [ReadDir] function or a [ReadDirFile]'s ReadDir method).
pub interface DirEntry {
  fn Info() -> Result<FileInfo, error>
  fn IsDir() -> bool
  fn Name() -> string
  fn Type() -> FileMode
}

/// An FS provides access to a hierarchical file system.
/// 
/// The FS interface is the minimum implementation required of the file system.
/// A file system may implement additional interfaces,
/// such as [ReadFileFS], to provide additional or optimized functionality.
/// 
/// [testing/fstest.TestFS] may be used to test implementations of an FS for
/// correctness.
pub interface FS {
  fn Open(name: string) -> Result<File, error>
}

/// A File provides access to a single file.
/// The File interface is the minimum implementation required of the file.
/// Directory files should also implement [ReadDirFile].
/// A file may implement [io.ReaderAt] or [io.Seeker] as optimizations.
pub interface File {
  fn Close() -> Result<(), error>
  fn Read(mut b: Slice<byte>) -> Partial<int, error>
  fn Stat() -> Result<FileInfo, error>
}

/// A FileInfo describes a file and is returned by [Stat].
pub interface FileInfo {
  fn IsDir() -> bool
  fn ModTime() -> time.Time
  fn Mode() -> FileMode
  fn Name() -> string
  fn Size() -> int64
  fn Sys() -> Unknown
}

/// A FileMode represents a file's mode and permission bits.
/// The bits have the same definition on all systems, so that
/// information about files can be moved from one system
/// to another portably. Not all bits apply to all systems.
/// The only required bit is [ModeDir] for directories.
#[go(bit_flag_set)]
pub struct FileMode(uint32)

/// A GlobFS is a file system with a Glob method.
pub interface GlobFS {
  fn Glob(pattern: string) -> Result<Slice<string>, error>
  fn Open(name: string) -> Result<File, error>
}

/// PathError records an error and the operation and file path that caused it.
pub struct PathError {
  pub Op: string,
  pub Path: string,
  pub Err: error,
}

/// ReadDirFS is the interface implemented by a file system
/// that provides an optimized implementation of [ReadDir].
pub interface ReadDirFS {
  fn Open(name: string) -> Result<File, error>
  fn ReadDir(name: string) -> Result<Slice<DirEntry>, error>
}

/// A ReadDirFile is a directory file whose entries can be read with the ReadDir method.
/// Every directory file should implement this interface.
/// (It is permissible for any file to implement this interface,
/// but if so ReadDir should return an error for non-directories.)
pub interface ReadDirFile {
  fn Close() -> Result<(), error>
  fn Read(mut b: Slice<byte>) -> Partial<int, error>
  fn ReadDir(n: int) -> Result<Slice<DirEntry>, error>
  fn Stat() -> Result<FileInfo, error>
}

/// ReadFileFS is the interface implemented by a file system
/// that provides an optimized implementation of [ReadFile].
pub interface ReadFileFS {
  fn Open(name: string) -> Result<File, error>
  fn ReadFile(name: string) -> Result<Slice<byte>, error>
}

/// ReadLinkFS is the interface implemented by a file system
/// that supports reading symbolic links.
pub interface ReadLinkFS {
  fn Lstat(name: string) -> Result<FileInfo, error>
  fn Open(name: string) -> Result<File, error>
  fn ReadLink(name: string) -> Result<string, error>
}

/// A StatFS is a file system with a Stat method.
pub interface StatFS {
  fn Open(name: string) -> Result<File, error>
  fn Stat(name: string) -> Result<FileInfo, error>
}

/// A SubFS is a file system with a Sub method.
pub interface SubFS {
  fn Open(name: string) -> Result<File, error>
  fn Sub(dir: string) -> Result<FS, error>
}

/// WalkDirFunc is the type of the function called by [WalkDir] to visit
/// each file or directory.
/// 
/// The path argument contains the argument to [WalkDir] as a prefix.
/// That is, if WalkDir is called with root argument "dir" and finds a file
/// named "a" in that directory, the walk function will be called with
/// argument "dir/a".
/// 
/// The d argument is the [DirEntry] for the named path.
/// 
/// The error result returned by the function controls how [WalkDir]
/// continues. If the function returns the special value [SkipDir], WalkDir
/// skips the current directory (path if d.IsDir() is true, otherwise
/// path's parent directory). If the function returns the special value
/// [SkipAll], WalkDir skips all remaining files and directories. Otherwise,
/// if the function returns a non-nil error, WalkDir stops entirely and
/// returns that error.
/// 
/// The err argument reports an error related to path, signaling that
/// [WalkDir] will not walk into that directory. The function can decide how
/// to handle that error; as described earlier, returning the error will
/// cause WalkDir to stop walking the entire tree.
/// 
/// [WalkDir] calls the function with a non-nil err argument in two cases.
/// 
/// First, if the initial [Stat] on the root directory fails, WalkDir
/// calls the function with path set to root, d set to nil, and err set to
/// the error from [fs.Stat].
/// 
/// Second, if a directory's ReadDir method (see [ReadDirFile]) fails, WalkDir calls the
/// function with path set to the directory's path, d set to an
/// [DirEntry] describing the directory, and err set to the error from
/// ReadDir. In this second case, the function is called twice with the
/// path of the directory: the first call is before the directory read is
/// attempted and has err set to nil, giving the function a chance to
/// return [SkipDir] or [SkipAll] and avoid the ReadDir entirely. The second call
/// is after a failed ReadDir and reports the error from ReadDir.
/// (If ReadDir succeeds, there is no second call.)
/// 
/// The differences between WalkDirFunc compared to [path/filepath.WalkFunc] are:
/// 
///   - The second argument has type [DirEntry] instead of [FileInfo].
///   - The function is called before reading a directory, to allow [SkipDir]
///     or [SkipAll] to bypass the directory read entirely or skip all remaining
///     files and directories respectively.
///   - If a directory read fails, the function is called a second time
///     for that directory to report the error.
pub type WalkDirFunc = fn(string, DirEntry, error) -> Result<(), error>

pub const ModeAppend: FileMode = 1073741824

pub const ModeCharDevice: FileMode = 2097152

pub const ModeDevice: FileMode = 67108864

pub const ModeDir: FileMode = 2147483648

pub const ModeExclusive: FileMode = 536870912

pub const ModeIrregular: FileMode = 524288

pub const ModeNamedPipe: FileMode = 33554432

pub const ModePerm: FileMode = 0777

pub const ModeSetgid: FileMode = 4194304

pub const ModeSetuid: FileMode = 8388608

pub const ModeSocket: FileMode = 16777216

pub const ModeSticky: FileMode = 1048576

pub const ModeSymlink: FileMode = 134217728

pub const ModeTemporary: FileMode = 268435456

pub const ModeType: FileMode = 2401763328

/// Generic file system errors.
/// Errors returned by file systems can be tested against these errors
/// using [errors.Is].
pub var ErrClosed: error

/// Generic file system errors.
/// Errors returned by file systems can be tested against these errors
/// using [errors.Is].
pub var ErrExist: error

/// Generic file system errors.
/// Errors returned by file systems can be tested against these errors
/// using [errors.Is].
pub var ErrInvalid: error

/// Generic file system errors.
/// Errors returned by file systems can be tested against these errors
/// using [errors.Is].
pub var ErrNotExist: error

/// Generic file system errors.
/// Errors returned by file systems can be tested against these errors
/// using [errors.Is].
pub var ErrPermission: error

/// SkipAll is used as a return value from [WalkDirFunc] to indicate that
/// all remaining files and directories are to be skipped. It is not returned
/// as an error by any function.
pub var SkipAll: error

/// SkipDir is used as a return value from [WalkDirFunc] to indicate that
/// the directory named in the call is to be skipped. It is not returned
/// as an error by any function.
pub var SkipDir: error

impl FileMode {
  /// IsDir reports whether m describes a directory.
  /// That is, it tests for the [ModeDir] bit being set in m.
  fn IsDir(self) -> bool

  /// IsRegular reports whether m describes a regular file.
  /// That is, it tests that no mode type bits are set.
  fn IsRegular(self) -> bool

  /// Perm returns the Unix permission bits in m (m & [ModePerm]).
  fn Perm(self) -> FileMode

  fn String(self) -> string

  /// Type returns type bits in m (m & [ModeType]).
  fn Type(self) -> FileMode
}

impl PathError {
  fn Error(self: Ref<PathError>) -> string

  /// Timeout reports whether this error represents a timeout.
  fn Timeout(self: Ref<PathError>) -> bool

  fn Unwrap(self: Ref<PathError>) -> Option<error>
}
