README
¶
path - utilities and convenience wrappers for all sorts of unix and URL path operations
The heading says it all. This package is likely a great candidate for a general refactoring into more targeted Go packages, however, it has proven quite convenient for Go-Enjin to have all these sorts of things in one place.
Installation
> go get github.com/go-corelibs/path@latest
Examples
There are too many things to demonstrate, see the godoc for the full details.
Go-CoreLibs
Go-CoreLibs is a repository of shared code between the Go-Curses and Go-Enjin projects.
License
Copyright 2023 The Go-CoreLibs Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use file except in compliance with the License.
You may obtain a copy of the license at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Documentation
¶
Index ¶
- Variables
- func Abs(path string) (absolute string, err error)
- func BackupAndOverwrite(path, content string, argv ...interface{}) (backup string, err error)
- func BackupName(name string, argv ...interface{}) (modified string)
- func Base(path string) (name string)
- func BasePath(path string) (basePath string)
- func ChmodAll(src string) error
- func Clean(path string) (cleaned string)
- func CleanWithSlash(path string) (clean string)
- func CleanWithSlashes(path string) (clean string)
- func CopyFile(src, dst string) (copied int64, err error)
- func Dir(path string) (name string)
- func DirSize(path string) (size uint64)
- func Exists(path string) bool
- func Ext(path string) (extn string)
- func ExtExt(path string) (primary, secondary string)
- func FileSize(path string) (size int64)
- func FindFileRelativeToPath(name, path string) (file string)
- func FindFileRelativeToPwd(name string) (file string)
- func HasAnyExt(path string, extensions ...string) (present bool)
- func HasExt(path, extension string) (present bool)
- func HasPermission(path string, expected os.FileMode) (present bool)
- func IncrementFileBackup(name, extension string) (modified string)
- func IncrementFileName(name string) (modified string)
- func IncrementFilePath(name string) (modified string)
- func IncrementLabel(label, leader, prefix, suffix string, increment int) (modified string, integer int)
- func IsBackup(path string) bool
- func IsDir(path string) bool
- func IsFile(path string) bool
- func IsHidden(path string) bool
- func IsHiddenPath(path string) (hidden bool)
- func IsPermission(path string, expected os.FileMode) (present bool)
- func IsPlainText(path string) (isPlain bool)
- func IsRegularFile(path string) bool
- func Join(parts ...string) (joined string)
- func JoinWithSlash(paths ...string) (joined string)
- func JoinWithSlashes(paths ...string) (joined string)
- func List(path string, includeHidden bool) (paths []string, err error)
- func ListAllDirs(path string, includeHidden bool) (paths []string, err error)
- func ListAllFiles(path string, includeHidden bool) (paths []string, err error)
- func ListDirs(path string, includeHidden bool) (paths []string, err error)
- func ListFiles(path string, includeHidden bool) (paths []string, err error)
- func MatchCut(path, prefix string) (suffix string, matched bool)
- func MatchExact(path, prefix string) (match bool)
- func MkdirAll(path string) (err error)
- func MoveFile(src, dst string) (err error)
- func Overwrite(path, content string) (err error)
- func OverwriteWithPerms(path, content string, perms fs.FileMode) (err error)
- func ParseParentPaths(path string) (parents []string)
- func Permissions(path string) (perms fs.FileMode, err error)
- func PruneEmptyDirs(path string) (err error)
- func Pwd() (pwd string)
- func ReadDir(path string) (paths []fs.DirEntry, err error)
- func ReadFile(path string) (content []byte, err error)
- func SafeConcatRelPath(root string, paths ...string) (out string)
- func SafeConcatUrlPath(root string, paths ...string) (out string)
- func Stat(path string) (spec times.Timespec, err error)
- func TopDirectory(path string) (name string)
- func TrimDotSlash(path string) (out string)
- func TrimExt(path string) (out string)
- func TrimPrefix(path, prefix string) (modified string)
- func TrimRelativeToRoot(path, root string) (rel string)
- func TrimSlash(path string) (clean string)
- func TrimSlashes(path string) (clean string)
- func Walk(root string, fn filepath.WalkFunc) (err error)
- func Which(name string) (path string)
- type CListPath
- func (l *CListPath) AddHiddenDir(paths ...string)
- func (l *CListPath) AddHiddenFile(paths ...string)
- func (l *CListPath) AddListPath(parent string, other *CListPath)
- func (l *CListPath) AddNormalDir(paths ...string)
- func (l *CListPath) AddNormalFile(paths ...string)
- func (l *CListPath) List() (sorted []string)
- func (l *CListPath) Sort()
- type ListPaths
Constants ¶
This section is empty.
Variables ¶
var ( RxIncrementNameSuffix = regexp.MustCompile(`\((\d+)\)\s*$`) RxIncrementPathSuffix = regexp.MustCompile(`.(\d+)\s*$`) )
var ( // DefaultPathPerms are the default permissions used when creating // new directories DefaultPathPerms = os.FileMode(0770) // DefaultFilePerms are the default permissions used when creating // new files DefaultFilePerms = os.FileMode(0660) )
var (
ErrExistingFile = errors.New("path is an existing file")
)
Functions ¶
func BackupAndOverwrite ¶
BackupAndOverwrite uses BackupName (passing argv along) to derive a non-existing file name, uses CopyFile to back up the current file contents and then uses Overwrite to update the original file contents.
func BackupName ¶
BackupName is a more flexible version of IncrementFileBackup, with a variable length list of values configuring the backup file naming process. The following is a breakdown of the `argv` patterns based on the number of arguments in the `argv`:
defaults: ext="~", leader=".", prefix="", suffix="", inc=1 0: all defaults used 1: ext=argv[0].(string) 2: 1 + leader=argv[1].(string) 3: 2 + inc=argv[2].(int) 4: 2 + prefix=argv[2].(string) + suffix=argv[3].(string) 5: 4 + inc=argv[4].(int)
Examples:
- zero argv BackupName("file.txt") == "file.txt~" BackupName("file.txt~") == "file.txt.1~"
- one argv BackupName("file.txt", ".bak") == "file.txt.bak" BackupName("file.txt.bak", ".bak") == "file.txt.1.bak"
- two argv BackupName("file.txt", ".bak", "~") == "file.txt~1.bak" BackupName("file.txt~1.bak", ".bak", "~") == "file.txt~2.bak"
- three argv BackupName("file.txt", ".bak", "~", 2) == "file.txt~1.bak" BackupName("file.txt~1.bak", ".bak", "~", 2) == "file.txt~3.bak"
- four argv BackupName("file.txt", ".bak", "~", "[", "]") == "file.txt.bak" BackupName("file.txt.bak", ".bak", "~", "[", "]") == "file.txt~[1].bak"
- five argv BackupName("file.txt", ".bak", "~", "[", "]", 2) == "file.txt.bak" BackupName("file.txt~[1].bak", ".bak", "~", "[", "]", 2) == "file.txt~[3].bak"
func BasePath ¶
BasePath returns the path without any primary or secondary file extensions, tertiary and other extensions present will remain as-is
Example:
BasePath("one/file.txt.tmpl.bak") == "one/file.txt"
func ChmodAll ¶ added in v1.2.0
ChmodAll uses Walk to traverse the filesystem and change all regular file permissions to the DefaultFilePerms (0660) and all directory permissions to the DefaultPathPerms (0770).
Stops on the first error
func CleanWithSlash ¶
CleanWithSlash trims all leading and trailing space from the `path` given, uses filepath.Clean on the trimmed results. The cleaned results are prefixed with a leading slash producing the `clean` value of `path`.
CleanWithSlash supports the Go-Enjin convention of a special type of path that is prefixed with a `!` instead of a slash and will correctly return the `clean` value with that prefix if it was present and if not uses that normal path separator slash.
CleanWithSlash produces absolute paths but do not mistake these for actual filesystem paths. CleanWithSlash is intended for use in working with URL paths.
func CleanWithSlashes ¶
CleanWithSlashes is a wrapper around CleanWithSlash which ensures the `clean` path begins and ends with a slash
func DirSize ¶ added in v1.4.0
DirSize uses filepath.WalkDir to traverse the given directory recursively and add up the size of each file present (includes hidden and any non-directory entries)
func Exists ¶
Exists returns true if the path is present on the local filesystem (could be a directory or any type of file)
func ExtExt ¶
ExtExt returns the extension of the file (without the dot) and any secondary extension found in the path
Example:
ExtExt("page.html.tmpl") => "tmpl", "html"
func FindFileRelativeToPath ¶
FindFileRelativeToPath looks for the named file within the directory path given and if not found, walks up the parent directories, checking each of them and returning the first named file found (as an absolute path)
The intent is something similar to how the `git` command knows it's in a repository even though the command may be run from within a subdirectory of the repository
func FindFileRelativeToPwd ¶
FindFileRelativeToPwd is a convenience wrapper for FindFileRelativeToPath, specifying the given name and a path of "."
func HasExt ¶
HasExt returns true if either the primary or secondary file extension matches the one given
func HasPermission ¶ added in v1.2.0
func IncrementFileBackup ¶
IncrementFileBackup removes the given extension if present, uses IncrementFilePath to modify the name with the extension appended. If the extension is empty, a "~" is used.
Examples:
IncrementFileBackup("test.txt", ".bak") == "test.txt.bak"
IncrementFileBackup("test.txt.bak", ".bak") == "test.txt.1.bak"
IncrementFileBackup("test.txt.1.bak", ".bak") == "test.txt.2.bak"
func IncrementFileName ¶
IncrementFileName is a wrapper around IncrementLabel, equivalent to: `IncrementLabel(name, " ", "(", ")", 1)`
func IncrementFilePath ¶
IncrementFilePath is a wrapper around IncrementLabel, equivalent to: `IncrementLabel(name, ".", "", "", 1)`
func IncrementLabel ¶
func IncrementLabel(label, leader, prefix, suffix string, increment int) (modified string, integer int)
IncrementLabel examines the given label for the specific sequence of leader, prefix, one or more digits and suffix characters. If the sequence is found, the digits are parsed into an integer and incremented by the given increment value and reassembled into the modified label output. If the sequence is not found, the sequence is appended to the whole label given with a number of 1.
If the increment given is zero, an increment of 1 is assumed as an increment of zero would not actually increment anything. Negative increments are valid, resulting in a decrement rather than actual increment.
Examples:
IncrementLabel("Title", " ", "(", ")", 1) == "Title (1)"
IncrementLabel("Title (10)", " ", "(", ")", 1) == "Title (11)"
IncrementLabel("filename", ".", "", "", 1) == "filename.1"
IncrementLabel("filename.10", ".", "", "", 1) == "filename.11"
IncrementLabel("filename.10", ".", "", "", -1) == "filename.9"
func IsFile ¶
IsFile returns true if the path is an existing file (could be a char device, pipe or other unix goodness, but not a directory)
func IsHiddenPath ¶
IsHiddenPath returns true if any of the path segments starts with a period and will panic if filepath.Abs fails to resolve an absolute path, which is not something that just happens randomly. Likely culprits of a panic are situations where the current working directory doesn't exist anymore or some other calamity of that nature
func IsPermission ¶ added in v1.2.0
func IsPlainText ¶
IsPlainText returns true if the path is a file and the file's mimetype is of `text/plain` type
func IsRegularFile ¶
IsRegularFile returns true if the path is an existing regular file
func JoinWithSlash ¶
JoinWithSlash joins the given URL path parts and uses CleanWithSlash on the results
func JoinWithSlashes ¶
JoinWithSlashes joins the given URL path parts and uses CleanWithSlashes on the results
func List ¶
List returns a list of directories and files, sorted in natural order with hidden things first and directories grouped before files
func ListAllDirs ¶
ListAllDirs is similar to ListDirs except returning all directories found recursively
func ListAllFiles ¶
ListAllFiles is similar to ListAllDirs except returning only files
func MatchCut ¶
MatchCut returns the suffix of path if path is prefixed with the given prefix path. If the path and prefix match exactly, suffix will be empty and matched will be true
Examples:
MatchCut("/one/two/", "one/two") == "", true
MatchCut("/one/two/many", "one/two") == "many", true
MatchCut("/one/two/many", "one") == "two/many", true
func MatchExact ¶
MatchExact compares cleaned versions of path and prefix
func MkdirAll ¶ added in v1.2.0
MkdirAll is a wrapper around os.MkdirAll with DefaultPathPerms (0770)
func MoveFile ¶
MoveFile tries to rename `src` to `dst` and if that works, nothing else is done. If renaming did not work, MoveFile copies `src` to `dst` and if successful, removes the original file. MoveFile can only move regular files and not pipes, char devices, etc.
func OverwriteWithPerms ¶
OverwriteWithPerms overwrites the given file and ensures the permissions are specifically the perms given. Normal unix umask may prevent correct permissions, use: `old := syscall.Umask(0); defer syscall.Umask(old)` to guarantee the specified perms
func ParseParentPaths ¶
ParseParentPaths is expecting a directory path and returns a list that walks up the total path with each item in the list
Example:
ParseParentPaths("one/two/many") == []string{
"one",
"one/two",
"one/two/many",
}
func Permissions ¶
Permissions is a wrapper around os.Stat, returning just the stat.Mode().Perm() value and any error from the stat call
func PruneEmptyDirs ¶
PruneEmptyDirs finds all directories starting at the given path, checks if
func SafeConcatRelPath ¶
SafeConcatRelPath prunes all empty and current dir paths from the list given, using TrimSlashes, then joins all the paths together, ensuring the output is prefixed with the given root, and has no leading or trailing slash and has is filepath.Clean
func SafeConcatUrlPath ¶
SafeConcatUrlPath wraps SafeConcatRelPath with a prefixing slash making an absolute URL path
func TopDirectory ¶
TopDirectory returns the top directory in the path given or an empty string if there are no parent directories present
func TrimDotSlash ¶
TrimDotSlash trims any leading `./` from the given path
func TrimPrefix ¶
TrimPrefix is like strings.TrimPrefix but for URL paths so that the prefix looked for is a prefixing URL path regardless of any slashes present in the prefix or path argument values.
TrimPrefix is primarily used in Go-Enjin filesystem driver implementations to coalesce given path into an underlying filesystem's actual path.
Example:
TrimPrefix("/one", "one") == ""
TrimPrefix("/one/two/many", "one") == "two/many"
TrimPrefix("/one/two/many", "two/many") == "one/two/many"
func TrimRelativeToRoot ¶
TrimRelativeToRoot truncates the root from path and removes any leading or trailing slashes. If the root is not present in the path, rel is empty
func TrimSlashes ¶
TrimSlashes returns the filepath cleaned and without any leading or trailing slashes
Types ¶
type CListPath ¶
type CListPath struct {
Path string
Hidden struct {
Dirs []string
Files []string
}
Normal struct {
Dirs []string
Files []string
}
Others map[string]ListPaths
}
func ListMatching ¶
func ListMatching(path string, includeHidden, recurse bool, matcher func(dir bool, path string) (matched bool)) (list *CListPath, err error)
ListMatching is a general purpose filesystem listing function, used by all other List functions in this package. It accepts a custom matcher func used to determine whether to include the specific path or not and it returns a new *CListPath instance which contains all the results of the list process. ListMatching will return at the first error
Source Files