Documentation
¶
Overview ¶
Package safepath implements some types and methods for dealing with POSIX file paths safely. When golang programmers use strings to express paths, it can sometimes be confusing whether a particular string represents either a file or a directory, and whether it is absolute or relative. This package provides a type for each of these, and safe methods to manipulate them all. The convention is that directories must end with a slash, and absolute paths must start with one. There are no generic "path" types for now, you must be more specific when using this library. If you can't discern exactly what you are, then use a string. It is your responsibility to build the type correctly and to call Validate on them to ensure you've done it correctly. If you don't, then you could cause a panic.
As a reminder, this library knows nothing about the special path characters like period (as in ./) and it only knows about two periods (..) in so far as it uses the stdlib Clean method when pulling in new paths.
The ParseInto* family of functions will sometimes add or remove a trailing slash to ensure you get a directory or file. It is recommended that you make sure to verify your desired type is what you expect before calling this.
Index ¶
- func HasPrefix(path Path, prefix Dir) bool
- func IsAbs(path string) bool
- func IsDir(path string) bool
- type Abs
- type AbsDir
- func (obj AbsDir) Cmp(absDir AbsDir) error
- func (obj AbsDir) HasDir(relDir RelDir) bool
- func (obj AbsDir) HasDirOne(relDir RelDir) bool
- func (obj AbsDir) IsAbs() bool
- func (obj AbsDir) IsDir() bool
- func (obj AbsDir) PanicValidate()
- func (obj AbsDir) Path() string
- func (obj AbsDir) String() string
- func (obj AbsDir) Validate() error
- type AbsFile
- func (obj AbsFile) Base() RelFile
- func (obj AbsFile) Cmp(absFile AbsFile) error
- func (obj AbsFile) HasDir(relDir RelDir) bool
- func (obj AbsFile) HasExt(ext string) bool
- func (obj AbsFile) HasExtInsensitive(ext string) bool
- func (obj AbsFile) IsAbs() bool
- func (obj AbsFile) IsDir() bool
- func (obj AbsFile) PanicValidate()
- func (obj AbsFile) Path() string
- func (obj AbsFile) String() string
- func (obj AbsFile) Validate() error
- type Dir
- type File
- type Path
- type Rel
- type RelDir
- func (obj RelDir) Cmp(relDir RelDir) error
- func (obj RelDir) HasDir(relDir RelDir) bool
- func (obj RelDir) HasDirOne(relDir RelDir) bool
- func (obj RelDir) IsAbs() bool
- func (obj RelDir) IsDir() bool
- func (obj RelDir) PanicValidate()
- func (obj RelDir) Path() string
- func (obj RelDir) String() string
- func (obj RelDir) Validate() error
- type RelFile
- func (obj RelFile) Cmp(relfile RelFile) error
- func (obj RelFile) HasDir(relDir RelDir) bool
- func (obj RelFile) HasExt(ext string) bool
- func (obj RelFile) HasExtInsensitive(ext string) bool
- func (obj RelFile) IsAbs() bool
- func (obj RelFile) IsDir() bool
- func (obj RelFile) PanicValidate()
- func (obj RelFile) Path() string
- func (obj RelFile) String() string
- func (obj RelFile) Validate() error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasPrefix ¶
HasPrefix determines if the given path has the specified dir prefix. The prefix and path can be absolute or relative. Keep in mind, that if the path is absolute, then only an absolute dir can successfully match. Similarly, if the path is relative, then only a relative dir can successfully match.
Types ¶
type Abs ¶
type Abs interface {
fmt.Stringer
Path() string
IsDir() bool
// contains filtered or unexported methods
}
Abs represents an absolute file or directory. Relative paths are not included.
type AbsDir ¶
type AbsDir struct {
// contains filtered or unexported fields
}
AbsDir represents an absolute dir path.
func JoinToAbsDir ¶
JoinToAbsDir joins an absolute dir with a relative dir to produce an absolute dir.
Example ¶
absDir := UnsafeParseIntoAbsDir("/foo/bar/")
relDir := UnsafeParseIntoRelDir("baz/")
fmt.Println(JoinToAbsDir(absDir, relDir).String())
Output: /foo/bar/baz/
func ParseIntoAbsDir ¶
ParseIntoAbsDir takes an input path and ensures it's an AbsDir, by adding a trailing slash if it's missing. It then runs Validate to ensure the path was valid overall. It also runs the stdlib path Clean function on it.
func UnsafeParseIntoAbsDir ¶
UnsafeParseIntoAbsDir performs exactly as ParseIntoAbsDir does, but it panics if the latter would have returned an error.
func (AbsDir) HasDirOne ¶
HasDirOne returns true if the input relative dir is present in the path. It only works with a single dir as relDir, so it won't work if relDir is `a/b/`.
func (AbsDir) PanicValidate ¶
func (obj AbsDir) PanicValidate()
PanicValidate panics if the path was not specified correctly.
func (AbsDir) Path ¶
Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.
type AbsFile ¶
type AbsFile struct {
// contains filtered or unexported fields
}
AbsFile represents an absolute file path.
func JoinToAbsFile ¶
JoinToAbsFile joins an absolute dir with a relative file to produce an absolute file.
Example ¶
absDir := UnsafeParseIntoAbsDir("/foo/bar/")
relFile := UnsafeParseIntoRelFile("baz")
fmt.Println(JoinToAbsFile(absDir, relFile).String())
Output: /foo/bar/baz
func ParseIntoAbsFile ¶
ParseIntoAbsFile takes an input path and ensures it's an AbsFile. It doesn't do anything particularly magical. It then runs Validate to ensure the path was valid overall. It also runs the stdlib path Clean function on it. Please note, that passing in the root slash / will cause this to fail.
func UnsafeParseIntoAbsFile ¶
UnsafeParseIntoAbsFile performs exactly as ParseIntoAbsFile does, but it panics if the latter would have returned an error.
func (AbsFile) Base ¶
Base returns the last component of the AbsFile, in this case, the filename. TODO: add tests
func (AbsFile) HasExt ¶
HasExt checks if the file ends with the given extension. It checks for an exact string match. You might prefer using HasExtInsensitive instead. As a special case, if you pass in an empty string as the extension to match, this will return false. TODO: add tests
func (AbsFile) HasExtInsensitive ¶
HasExtInsensitive checks if the file ends with the given extension. It checks with a fancy case-insensitive match. As a special case, if you pass in an empty string as the extension to match, this will return false.
func (AbsFile) PanicValidate ¶
func (obj AbsFile) PanicValidate()
PanicValidate panics if the path was not specified correctly.
func (AbsFile) Path ¶
Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.
type Dir ¶
type Dir interface {
fmt.Stringer
Path() string
//IsDir() bool // TODO: add this to allow a Dir to become a Path?
IsAbs() bool
// contains filtered or unexported methods
}
Dir represents either an absolute or relative directory. Files are not included.
func ParseIntoDir ¶
ParseIntoDir takes an input path and returns a type that fulfills the Dir interface. The returned underlying type will be one of AbsDir or RelDir.
func UnsafeParseIntoDir ¶
UnsafeParseIntoDir performs exactly as ParseIntoDir does, but it panics if the latter would have returned an error.
type File ¶
type File interface {
fmt.Stringer
Path() string
//IsDir() bool // TODO: add this to allow a File to become a Path?
IsAbs() bool
// contains filtered or unexported methods
}
File represents either an absolute or relative file. Directories are not included.
func ParseIntoFile ¶
ParseIntoFile takes an input path and returns a type that fulfills the File interface. The returned underlying type will be one of AbsFile or RelFile.
func UnsafeParseIntoFile ¶
UnsafeParseIntoFile performs exactly as ParseIntoFile does, but it panics if the latter would have returned an error.
type Path ¶
type Path interface {
fmt.Stringer
Path() string
IsDir() bool
IsAbs() bool
// contains filtered or unexported methods
}
Path represents any absolute or relative file or directory.
func ParseIntoPath ¶
ParseIntoPath takes an input path and a boolean that specifies if it is a dir and returns a type that fulfills the Path interface. The isDir boolean usually comes from the io/fs.FileMode IsDir() method. The returned underlying type will be one of AbsFile, AbsDir, RelFile, RelDir. It then runs Validate to ensure the path was valid overall.
func SmartParseIntoPath ¶
SmartParseIntoPath performs exactly as ParseIntoPath does, except it determines if something is a dir based on whetherthe string path has a trailing slash or not.
func StripPrefix ¶
StripPrefix removes a dir prefix from a path if it is possible to do so. The prefix and path can be both absolute or both relative. The returned result is either a relative dir or a relative file. Keep in mind, that if the path is absolute, then only an absolute dir can successfully match. Similarly, if the path is relative, then only a relative dir can successfully match. The input path will be returned unchanged if it is not possible to match (although it will return an error in parallel) and if there is a match, then either a relative dir or a relative file will be returned with the path interface. This is logical, because after removing some prefix, only relative paths can possibly remain. This relative returned path will be a file if the input path was a file, and a dir if the input path was a dir. XXX: add tests!
func UnsafeParseIntoPath ¶
UnsafeParseIntoPath performs exactly as ParseIntoPath does, but it panics if the latter would have returned an error.
func UnsafeSmartParseIntoPath ¶
UnsafeSmartParseIntoPath performs exactly as SmartParseIntoPath does, but it panics if the latter would have returned an error.
type Rel ¶
type Rel interface {
fmt.Stringer
Path() string
IsDir() bool
// contains filtered or unexported methods
}
Rel represents a relative file or directory. Absolute paths are not included.
type RelDir ¶
type RelDir struct {
// contains filtered or unexported fields
}
RelDir represents a relative dir path.
func JoinToRelDir ¶
JoinToRelDir joins any number of relative dir's to produce a relative dir.
Example ¶
relDir1 := UnsafeParseIntoRelDir("foo/")
relDir2 := UnsafeParseIntoRelDir("bar/")
relDir3 := UnsafeParseIntoRelDir("baz/")
fmt.Println(JoinToRelDir(relDir1, relDir2, relDir3).String())
Output: foo/bar/baz/
func ParseIntoRelDir ¶
ParseIntoRelDir takes an input path and ensures it's an RelDir, by adding a trailing slash if it's missing. It then runs Validate to ensure the path was valid overall. It also runs the stdlib path Clean function on it.
func UnsafeParseIntoRelDir ¶
UnsafeParseIntoRelDir performs exactly as ParseIntoRelDir does, but it panics if the latter would have returned an error.
func (RelDir) HasDirOne ¶
HasDirOne returns true if the input relative dir is present in the path. It only works with a single dir as relDir, so it won't work if relDir is `a/b/`.
func (RelDir) PanicValidate ¶
func (obj RelDir) PanicValidate()
PanicValidate panics if the path was not specified correctly.
func (RelDir) Path ¶
Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.
type RelFile ¶
type RelFile struct {
// contains filtered or unexported fields
}
RelFile represents a relative file path.
func JoinToRelFile ¶
JoinToRelFile joins a relative dir with a relative file to produce a relative file.
Example ¶
relDir := UnsafeParseIntoRelDir("foo/bar/")
relFile := UnsafeParseIntoRelFile("baz")
fmt.Println(JoinToRelFile(relDir, relFile).String())
Output: foo/bar/baz
func ParseIntoRelFile ¶
ParseIntoRelFile takes an input path and ensures it's an RelFile. It doesn't do anything particularly magical. It then runs Validate to ensure the path was valid overall. It also runs the stdlib path Clean function on it.
func UnsafeParseIntoRelFile ¶
UnsafeParseIntoRelFile performs exactly as ParseIntoRelFile does, but it panics if the latter would have returned an error.
func (RelFile) HasExt ¶
HasExt checks if the file ends with the given extension. It checks for an exact string match. You might prefer using HasExtInsensitive instead. As a special case, if you pass in an empty string as the extension to match, this will return false. TODO: add tests
func (RelFile) HasExtInsensitive ¶
HasExtInsensitive checks if the file ends with the given extension. It checks with a fancy case-insensitive match. As a special case, if you pass in an empty string as the extension to match, this will return false.
func (RelFile) PanicValidate ¶
func (obj RelFile) PanicValidate()
PanicValidate panics if the path was not specified correctly.
func (RelFile) Path ¶
Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.
Source Files