Documentation
¶
Overview ¶
file provide simple utilities for working with the file system
Index ¶
- Constants
- Variables
- func AbsPaths(paths []string, checkExists bool) ([]string, error)
- func CalculateDirSizeShallow(path string) (int64, []os.FileInfo, error)
- func CopyFile(ctx context.Context, source string, destination string) (int64, error)
- func CopyFileN(ctx context.Context, source string, destination string, count int64) (int64, error)
- func DirExists(path string) (bool, error)
- func ExpandPath(path string) (string, error)
- func FileExists(path string) (bool, error)
- func FileSize(path string) (int64, error)
- func GlobExt(dir string, ext string) ([]string, error)
- func Hash(ctx context.Context, path string, hasher hash.Hash, w io.Writer) ([]byte, uint64, error)
- func HashFromReader(ctx context.Context, rd io.Reader, hasher hash.Hash, w io.Writer) ([]byte, uint64, error)
- func HashMD5(ctx context.Context, path string, w io.Writer) ([]byte, uint64, error)
- func HashSHA1(ctx context.Context, path string, w io.Writer) ([]byte, uint64, error)
- func HashSHA256(ctx context.Context, path string, w io.Writer) ([]byte, uint64, error)
- func HashSHA512(ctx context.Context, path string, w io.Writer) ([]byte, uint64, error)
- func IsDirEntryEqual(a os.DirEntry, b os.DirEntry) bool
- func IsDirEntryWithInfoEqual(a os.DirEntry, b os.DirEntry) (bool, error)
- func MatchAlways(path string, d fs.DirEntry) (bool, error)
- func MatchNever(path string, d fs.DirEntry) (bool, error)
- func PathExists(path string) (bool, error)
- func ReadDirUnsorted(name string) ([]os.DirEntry, error)
- func RemoveIfExists(path string) error
- func ReplaceExt(path string, newExt string) string
- func SortDirEntries(dirs []os.DirEntry)
- type CalculateSizeResult
- type Lockfile
- type MatchPathFn
- type MatchPathMiddleware
- type PathHash
- type Walker
Constants ¶
const (
PathHashSize = sha1.Size
)
Variables ¶
var ( ErrLockfileAcquired = errors.New("failed to acquire the lock file") ErrLockfileNotOwned = errors.New("the current process does not own the lock file") )
Functions ¶
func AbsPaths ¶
Convert the slice of paths to the absolute paths and optionally verify the paths exists.
func CalculateDirSizeShallow ¶
List a directory and calculate the size of all files in the directory. NOTE: This does not calculate recursively into subdirectories.
func CopyFile ¶
Copy the source file to the destination and return the number of bytes that were copied.
func CopyFileN ¶
Copy N bytes from the source file to the destination and return the number of bytes that were copied.
func DirExists ¶
Check if the path exists and is a directory. If the path does not exists then (false, nil) will be returned. If the path exists but is not a directory then (false, nil) will be returned. An error is only returned if an error occurred while checking if the path exists.
func ExpandPath ¶
Expand the path to include the user's home directory if the path starts with the suffix ~.
func FileExists ¶
Check if the path exists and is a regular file. If the path does not exists then (false, nil) will be returned. If the path exists but is not a regular file then (false, nil) will be returned. An error is only returned if an error occurred while checking if the path exists.
func GlobExt ¶
Recursively find all files in dir that matches the specified extension. NOTE: ext must include the dot (period) e.g. .txt.
func Hash ¶
Hash the specified file and optionally copy the read bytes to the io.Writer. Return the calculated hash and the total number of bytes copied.
func HashFromReader ¶
func HashFromReader(ctx context.Context, rd io.Reader, hasher hash.Hash, w io.Writer) ([]byte, uint64, error)
Do buffered reads from rd and write to the hasher and optional io.Writer. Return the calculated hash and the total number of bytes copied.
func HashSHA256 ¶
func HashSHA512 ¶
func IsDirEntryEqual ¶
Return true if two os.DirEntry are the same without comparing .Info() (which involves fetching more data).
func IsDirEntryWithInfoEqual ¶
Return true if two os.DirEntry are the same. This will also make a call to .Info() which involves fetching more data and potentially result in an error.
func MatchAlways ¶
MatchAlways is a MatchPathFn that will always return true.
func MatchNever ¶
MatchNever is a MatchPathFn that will always return false.
func PathExists ¶
Check if the path exists. If the path exists then (true, nil) is returned. If the path does not exist then (false, nil) is returned. If an error occurred while trying to check if the path exists then (false, err) is returned.
func ReadDirUnsorted ¶
Unsorted version of os.ReadDir for small optimisation. It requires less allocs if you are not concerned about sorted order.
func RemoveIfExists ¶
Delete the path if it exists and only return an error if something went wrong other than the fact that the path didn't exist.
func ReplaceExt ¶
Replace the path's file extension with a new one.
func SortDirEntries ¶
Sort a slice of os.DirEntry. This performs the same sort found in os.ReadDir.
Types ¶
type CalculateSizeResult ¶
type CalculateSizeResult struct {
Dirs int // The number of directories
Files int // The number of regular files
TotalSize uint64 // The total size in bytes of all the regular files
}
Results from CalculateSize.
func CalculateSize ¶
func CalculateSize(path string) (CalculateSizeResult, error)
Walk the path recusively and count the number of directories, files and the total file size.
type Lockfile ¶
type Lockfile struct {
// contains filtered or unexported fields
}
Lockfile is used to acquire a lock on a process for various tasks to be performed and thus other processes should not be allowed to run while the lock has been acquired. NOTE: This is not a lock on a single file, this is a lock on a service or process to ensure no other process (that adheres to the lock) will run. The lock file that is created contains the PID of the process that acquired the lock.
func AcquireLockfile ¶
Attempt to acquire the lock file specified by the path. If the lock file does not exist, then it will be created and the current PID will be written to the file. If the lock file does exist, then the Lockfile info along with the error ErrLockfileAcquired will be returned.
func AcquireLockfileReEntrant ¶
Attempt to acquire the lock file specified by the path. This is the same as AcquireLockfile but allows for the same process to acquire the same lock file multiple times (re-entrant) If the lock file does exist and is not owned by the same process then the Lockfile info along with the error ErrLockfileAcquired will be returned. NOTE: You can not call Release multiple times (e.g. 1 Acquire = 1 Release) as the first call to Release will release the lock.
type MatchPathFn ¶
MatchPathFn determines if the path matches a criteria and if so returns true.
func MatchAppleDSStore ¶
func MatchAppleDSStore(next MatchPathFn) MatchPathFn
MatchAppleDSStore middleware will match Apple .DS_Store files.
func MatchRegex ¶
func MatchRegex(expressions []string, next MatchPathFn) (MatchPathFn, error)
MatchRegex middleware takes a slice of regular expression patterns and will check a path if any of the expressions matched.
type MatchPathMiddleware ¶
type MatchPathMiddleware func(next MatchPathFn) MatchPathFn
MatchPathMiddleware specifies the function signature for a wrapping MatchPathFn into a call chain. Similarly to how http middleware works in popular frameworks.
type PathHash ¶
type PathHash [PathHashSize]byte
func CalculatePathHash ¶
Calculate the unique hash for a path.
func CalculatePathsHash ¶
Calculate the unique hash for a given slice of file paths.
type Walker ¶
type Walker struct {
DirIncluder MatchPathFn // Determine which directories should be walked
FileIncluder MatchPathFn // Determine which files should be walked
DirExcluder MatchPathFn // Determine which directories should not be walked
FileExcluder MatchPathFn // Determine which files should not be walked
}
Walker is used to walk a file hierarchy.
func NewWalker ¶
func NewWalker() *Walker
Create a new Walker.
By default all files and directories found will be walked and not be excluded.
func (*Walker) Walk ¶
func (w *Walker) Walk(root string, fn fs.WalkDirFunc) error
Walk walks the file tree rooted at root, calling fn for each file or directory in the tree, including root that was not filtered.
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 Walk to read an entire directory into memory before proceeding to walk that directory.
Walk does not follow symbolic links.
Walk calls fn with paths that use the separator character appropriate for the operating system.
Walk uses fs.WalkDir for implementation.
For each directory that is found, the DirIncluder will be called to determine if the path should be walked. If this filter returns false then the DirExcluder will not be checked. The DirExcluder will be called to determine if the path should not be walked. The root path will never be filtered.
For each file that is found, the FileIncluder will be called to determine if the path should be walked. If this filter returns false then the FileExcluder will not be checked. The FileExcluder will be called to determine if the path should not be walked.
The root path will be expanded using file.ExpandPath if needed.
Source Files
Directories