paths

Documentation

Index

• Constants
• func ExpandHome(path *string) (err error)
• func GetFirst(paths []string) (content []byte, isDir, ok bool)
• func GetFirstWithRef(paths []string) (content []byte, isDir, ok bool, idx int)
• func MakeDirIfNotExist(path string) (err error)
• func RealPath(path *string) (err error)
• func RealPathExists(path *string) (exists bool, err error)
• func RealPathExistsStat(path *string) (exists bool, stat os.FileInfo, err error)
• func SearchFsPaths(root string, targetType fs.FileMode, noFiles bool, ...) (foundPaths []string, err error)

Constants

const (
	// TimeAccessed == atime
	TimeAccessed pathTimeType = 1 << iota
	// TimeCreated == "birth" time (*NOT* ctime! See TimeChanged)
	TimeCreated
	// TimeChanged == ctime
	TimeChanged
	// TimeModified == mtime
	TimeModified
)

const TimeAny pathTimeType = 0

Times

Functions

func ExpandHome

func ExpandHome(path *string) (err error)

ExpandHome will take a tilde(~)-prefixed path and resolve it to the actual path in-place. "Nested" user paths (~someuser/somechroot/~someotheruser) are not supported as home directories are expected to be absolute paths.

func GetFirst

func GetFirst(paths []string) (content []byte, isDir, ok bool)

GetFirst is the file equivalent of envs.GetFirst.

It iterates through paths, normalizing them along the way (so abstracted paths such as ~/foo/bar.txt and relative paths such as bar/baz.txt will still work), and returns the content of the first found existing file. If the first found path is a directory, content will be nil but isDir will be true (as will ok).

If no path exists, ok will be false.

As always, results are not guaranteed due to permissions, etc. potentially returning an inaccurate result.

This is a thin wrapper around GetFirstWithRef.

func GetFirstWithRef

func GetFirstWithRef(paths []string) (content []byte, isDir, ok bool, idx int)

GetFirstWithRef is the file equivalent of envs.GetFirstWithRef.

It behaves exactly like GetFirst, but with an additional returned value, idx, which specifies the index in paths in which a path was found.

As always, results are not guaranteed due to permissions, etc. potentially returning an inaccurate result.

func MakeDirIfNotExist

func MakeDirIfNotExist(path string) (err error)

MakeDirIfNotExist will create a directory at a given path if it doesn't exist.

See also the documentation for RealPath.

This is a bit more sane option than os.MkdirAll as it will normalize paths a little better.

func RealPath

func RealPath(path *string) (err error)

RealPath will transform a given path into the very best guess for an absolute path in-place.

It is recommended to check err (if not nil) for an invalid path error. If this is true, the path syntax/string itself is not supported on the runtime OS. This can be done via:

if errors.Is(err, fs.ErrInvalid) {...}

func RealPathExists

func RealPathExists(path *string) (exists bool, err error)

RealPathExists is like RealPath, but will also return a boolean as to whether the path actually exists or not.

Note that err *may* be os.ErrPermission/fs.ErrPermission, in which case the exists value cannot be trusted as a permission error occurred when trying to stat the path - if the calling user/process does not have read permission on e.g. a parent directory, then exists may be false but the path may actually exist. This condition can be checked via via:

if errors.Is(err, fs.ErrPermission) {...}

See also the documentation for RealPath.

In those cases, it may be preferable to use RealPathExistsStat and checking stat for nil.

func RealPathExistsStat

func RealPathExistsStat(path *string) (exists bool, stat os.FileInfo, err error)

RealPathExistsStat is like RealPathExists except it will also return the os.FileInfo for the path (assuming it exists).

If stat is nil, it is highly recommended to check err via the methods suggested in the documentation for RealPath and RealPathExists.

func SearchFsPaths

func SearchFsPaths(
	root string,
	targetType fs.FileMode, noFiles bool,
	basePtrn, pathPtrn *regexp.Regexp,
	age *time.Duration, ageType pathTimeType, olderThan bool,
) (foundPaths []string, err error)

SearchPaths gets a file/directory path list based on the provided criteria.

targetType defines what should be included in the path list. It can consist of one or more (io/)fs.FileMode types OR'd together (ensure they are part of (io/)fs.ModeType). (You can use 0 to match regular files explicitly, and/or noFiles = true to exclude them.)

noFiles, if true, will explicitly filter out regular files from the path results. (Normally they are *always* included regardless of targetType.)

basePtrn may be nil; if it isn't, it will be applied to *base names* (that is, quux.txt rather than /foo/bar/baz/quux.txt).

pathPtrn is like basePtrn except it applies to the *entire* path, not just the basename, if not nil (e.g. /foo/bar/baz/quux.txt, not just quux.txt).

If age is not nil, it will be applied to the path object. It will match older files/directories/etc. if olderThan is true, otherwise it will match newer files/directories/etc. (olderThan is not used otherwise.)

ageType is one or more Time* constants OR'd together to describe which timestamp type to check. (Note that TimeCreated may not match if specified as it is only available on certain OSes, kernel versions, and filesystems. This may lead to files being excluded that may have otherwise been included.) (You can use TimeAny to specify any supported time.) *Any* matching timestamp of all specified (and supported) timestamp types matches, so be judicious with your selection. They are processed in order of:

• btime (birth/creation time) (if supported)
• mtime (modification time -- contents have changed)
• ctime (OS-specific behavior; generally disk metadata has changed) (if supported)
• atime (access time)

olderThan (as mentioned above) will find paths *older* than age if true, otherwise *newer*.