}
// FormatDirEntry returns a formatted version of dir for human readability.
-// Implementations of DirEntry can call this from a String method.
+// 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/
// 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.
+// interpreted by an [FS] implementation as path element separators.
func ValidPath(name string) bool {
if !utf8.ValidString(name) {
return false
// 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.
+// Directory files should also implement [ReadDirFile].
+// A file may implement [io.ReaderAt] or [io.Seeker] as optimizations.
type File interface {
Stat() (FileInfo, error)
Read([]byte) (int, error)
}
// A DirEntry is an entry read from a directory
-// (using the ReadDir function or a ReadDirFile's ReadDir method).
+// (using the ReadDir function or a [ReadDirFile]'s ReadDir method).
type DirEntry interface {
// Name returns the name of the file (or subdirectory) described by the entry.
// This name is only the final element of the path (the base name), not the entire path.
// Generic file system errors.
// Errors returned by file systems can be tested against these errors
-// using errors.Is.
+// using [errors.Is].
var (
ErrInvalid = errInvalid() // "invalid argument"
ErrPermission = errPermission() // "permission denied"
// 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.
+// The only required bit is [ModeDir] for directories.
type FileMode uint32
-// The defined file mode bits are the most significant bits of the FileMode.
+// The defined file mode bits are the most significant bits of the [FileMode].
// The nine least-significant bits are the standard Unix rwxrwxrwx permissions.
// The values of these bits should be considered part of the public API and
// may be used in wire protocols or disk representations: they must not be
// 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
+// 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 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
+// If fs implements [GlobFS], Glob calls fs.Glob.
+// Otherwise, Glob uses [ReadDir] to traverse the directory tree
// and look for matches for the pattern.
func Glob(fsys FS, pattern string) (matches []string, err error) {
return globWithLimit(fsys, pattern, 0)
)
// ReadDirFS is the interface implemented by a file system
-// that provides an optimized implementation of ReadDir.
+// that provides an optimized implementation of [ReadDir].
type ReadDirFS interface {
FS
// ReadDir reads the named directory
// and returns a list of directory entries sorted by filename.
//
-// If fs implements ReadDirFS, ReadDir calls fs.ReadDir.
+// If fs implements [ReadDirFS], ReadDir calls fs.ReadDir.
// Otherwise ReadDir calls fs.Open and uses ReadDir and Close
// on the returned file.
func ReadDir(fsys FS, name string) ([]DirEntry, error) {
return FormatDirEntry(di)
}
-// FileInfoToDirEntry returns a DirEntry that returns information from info.
+// FileInfoToDirEntry returns a [DirEntry] that returns information from info.
// If info is nil, FileInfoToDirEntry returns nil.
func FileInfoToDirEntry(info FileInfo) DirEntry {
if info == nil {
import "io"
// ReadFileFS is the interface implemented by a file system
-// that provides an optimized implementation of ReadFile.
+// that provides an optimized implementation of [ReadFile].
type ReadFileFS interface {
FS
}
// ReadFile reads the named file from the file system fs and returns its contents.
-// A successful call returns a nil error, not io.EOF.
+// 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.
+// If fs implements [ReadFileFS], ReadFile calls fs.ReadFile.
// Otherwise ReadFile calls fs.Open and uses Read and Close
-// on the returned file.
+// on the returned [File].
func ReadFile(fsys FS, name string) ([]byte, error) {
if fsys, ok := fsys.(ReadFileFS); ok {
return fsys.ReadFile(name)
Stat(name string) (FileInfo, error)
}
-// Stat returns a FileInfo describing the named file from the file system.
+// 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.
+// If fs implements [StatFS], Stat calls fs.Stat.
+// Otherwise, Stat opens the [File] to stat it.
func Stat(fsys FS, name string) (FileInfo, error) {
if fsys, ok := fsys.(StatFS); ok {
return fsys.Stat(name)
Sub(dir string) (FS, error)
}
-// Sub returns an FS corresponding to the subtree rooted at fsys's dir.
+// 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,
+// 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, 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
+// 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
+// other directories. That is, [os.DirFS] is not a general substitute for a
// chroot-style security mechanism, and Sub does not change that fact.
func Sub(fsys FS, dir string) (FS, error) {
if !ValidPath(dir) {
// as an error by any function.
var SkipAll = errors.New("skip everything and stop the walk")
-// WalkDirFunc is the type of the function called by WalkDir to visit
+// 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.
+// 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 fs.DirEntry for the named path.
+// 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
+// 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,
+// [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
+// [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.
+// [WalkDir] calls the function with a non-nil err argument in two cases.
//
-// First, if the initial fs.Stat on the root directory fails, WalkDir
+// 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 fails, WalkDir calls the
+// 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
-// fs.DirEntry describing the directory, and err set to the error from
+// [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
+// 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 filepath.WalkFunc are:
+// The differences between WalkDirFunc compared to [path/filepath.WalkFunc] are:
//
-// - The second argument has type fs.DirEntry instead of fs.FileInfo.
-// - The function is called before reading a directory, to allow SkipDir
-// or SkipAll to bypass the directory read entirely or skip all remaining
+// - 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.