github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/cmd/go/internal/fsys/fsys.go (about)

     1  // Copyright 2020 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package fsys is an abstraction for reading files that
     6  // allows for virtual overlays on top of the files on disk.
     7  package fsys
     8  
     9  import (
    10  	"github.com/shogo82148/std/io/fs"
    11  	"github.com/shogo82148/std/os"
    12  
    13  	"github.com/shogo82148/std/path/filepath"
    14  )
    15  
    16  // Trace emits a trace event for the operation and file path to the trace log,
    17  // but only when $GODEBUG contains gofsystrace=1.
    18  // The traces are appended to the file named by the $GODEBUG setting gofsystracelog, or else standard error.
    19  // For debugging, if the $GODEBUG setting gofsystracestack is non-empty, then trace events for paths
    20  // matching that glob pattern (using path.Match) will be followed by a full stack trace.
    21  func Trace(op, path string)
    22  
    23  // OverlayFile is the path to a text file in the OverlayJSON format.
    24  // It is the value of the -overlay flag.
    25  var OverlayFile string
    26  
    27  // OverlayJSON is the format overlay files are expected to be in.
    28  // The Replace map maps from overlaid paths to replacement paths:
    29  // the Go command will forward all reads trying to open
    30  // each overlaid path to its replacement path, or consider the overlaid
    31  // path not to exist if the replacement path is empty.
    32  type OverlayJSON struct {
    33  	Replace map[string]string
    34  }
    35  
    36  // Init initializes the overlay, if one is being used.
    37  func Init(wd string) error
    38  
    39  // IsDir returns true if path is a directory on disk or in the
    40  // overlay.
    41  func IsDir(path string) (bool, error)
    42  
    43  // ReadDir provides a slice of fs.FileInfo entries corresponding
    44  // to the overlaid files in the directory.
    45  func ReadDir(dir string) ([]fs.FileInfo, error)
    46  
    47  // OverlayPath returns the path to the overlaid contents of the
    48  // file, the empty string if the overlay deletes the file, or path
    49  // itself if the file is not in the overlay, the file is a directory
    50  // in the overlay, or there is no overlay.
    51  // It returns true if the path is overlaid with a regular file
    52  // or deleted, and false otherwise.
    53  func OverlayPath(path string) (string, bool)
    54  
    55  // Open opens the file at or overlaid on the given path.
    56  func Open(path string) (*os.File, error)
    57  
    58  // OpenFile opens the file at or overlaid on the given path with the flag and perm.
    59  func OpenFile(path string, flag int, perm os.FileMode) (*os.File, error)
    60  
    61  // IsDirWithGoFiles reports whether dir is a directory containing Go files
    62  // either on disk or in the overlay.
    63  func IsDirWithGoFiles(dir string) (bool, error)
    64  
    65  // Walk walks the file tree rooted at root, calling walkFn for each file or
    66  // directory in the tree, including root.
    67  func Walk(root string, walkFn filepath.WalkFunc) error
    68  
    69  // Lstat implements a version of os.Lstat that operates on the overlay filesystem.
    70  func Lstat(path string) (fs.FileInfo, error)
    71  
    72  // Stat implements a version of os.Stat that operates on the overlay filesystem.
    73  func Stat(path string) (fs.FileInfo, error)
    74  
    75  // Glob is like filepath.Glob but uses the overlay file system.
    76  func Glob(pattern string) (matches []string, err error)