Documentation ¶
Overview ¶
Package gopath implements an alternative API to Go's path processing libraries. It implements the recommondations from the article https://blog.golang.org/errors-are-values. For even more information, also have a look at the article http://blog.golang.org/error-handling-and-go.
Idea ¶
What's special to gopath is its ability to write code that processes paths in a fluent way, while doing the error handling later. This is possible by using the immutable object gopath.GoPath, which either represents a path, or an error.
var p1 = gopath.FromPath("/existing/file").Stat() assert.Nil(p1.Err()) var p2 = gopath.FromPath("/doesnt/exist").Stat() assert.NotNil(p2.Err())
All operations on an errorneous GoPath are no-ops, therefore the first error ever occured in a chain of operations will remain visible. This way, you can work with GoPaths like you would with any other object.
var p = gopath.FromPath("/my/path/to/somewhere").Abs().EvalSymlinks().Rel(otherPath) if p.HasErr() { // handle error } // go on
Index ¶
- type GoPath
- func (g GoPath) Abs() GoPath
- func (g GoPath) Append(s string) GoPath
- func (g GoPath) AssertExists() GoPath
- func (g GoPath) Base() string
- func (g GoPath) Clean() GoPath
- func (g GoPath) ClearErr() GoPath
- func (g GoPath) Components() []string
- func (g GoPath) Dir() GoPath
- func (g GoPath) Do(transformer Transformer) GoPath
- func (g GoPath) Err() error
- func (g GoPath) EvalSymlinks() GoPath
- func (g GoPath) Ext() string
- func (g GoPath) FileInfo() os.FileInfo
- func (g GoPath) FileMode() os.FileMode
- func (g GoPath) Glob() (matches []string, err error)
- func (g GoPath) GlobAny() GoPath
- func (g GoPath) HasErr() bool
- func (g GoPath) HasFileMode(mode os.FileMode) bool
- func (g GoPath) IsDirectory() bool
- func (g GoPath) IsEmpty() bool
- func (g GoPath) IsExists() bool
- func (g GoPath) IsRegular() bool
- func (g GoPath) IsSymlink() bool
- func (g GoPath) IsTemporary() bool
- func (g GoPath) Join(other GoPath) GoPath
- func (g GoPath) JoinPath(p string) GoPath
- func (g GoPath) Path() string
- func (g GoPath) PrependErr(prefix string) GoPath
- func (g GoPath) Rel(targpath GoPath) GoPath
- func (g GoPath) RelTo(base GoPath) GoPath
- func (g GoPath) Stat() GoPath
- func (g GoPath) String() string
- func (g GoPath) ToSlash() GoPath
- type Transformer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GoPath ¶
type GoPath struct {
// contains filtered or unexported fields
}
GoPath is an immutable object, representing a computational stage in path processing. It might either represent a path after zero or more successfully executed operations, or it might represent an errorneous state after an operation that returned an error.
func (GoPath) Abs ¶
Abs calls filepath.Abs() on the path.
If the path is already absolute, it returns the path itself. Otherwise, it returns an absolute representation of the path using the current working directory.
If an error occurs, it returns an errorneous GoPath.
func (GoPath) Append ¶
Append appends the given string to this GoPath. It doesn't use any separator, especially no slash.
If this GoPath is errorneous, it returns simply this GoPath.
func (GoPath) AssertExists ¶
AssertExists returns an errorneous path, iff a Stat() call fails, and sets the error value. Otherwise, it returns the GoPath itself.
Note that it seems wrong to only return an errorneous path when Stat() fails with an error that yields os.IsNotExist(err) == true, because a different error does not necessarily mean that the file does exist.
func (GoPath) Clean ¶
Clean calls filepath.Clean(). It returns the shortest path equivalent to the given path. It might not return an errorneous GoPath, unless the given GoPath is already errorneous.
func (GoPath) ClearErr ¶
ClearErr returns a GoPath instance with the same fields as this instance, except for the err field being nil.
func (GoPath) Components ¶
Components returns all path components in this gopath. That is, the path is split at each os.PathSeparator.
If this gopath is errorneous, it returns the empty array.
func (GoPath) Dir ¶
Dir calls path.Dir() and returns all but the last element of this GoPath, typically the directory containing the file or directory this path points to.
If this GoPath is errorneous, it returns simply this GoPath.
func (GoPath) Do ¶
func (g GoPath) Do(transformer Transformer) GoPath
Do executes the transformer on this GoPath. It therefore is an extension point. For example, you could define a transformer like the following:
func normalizePath(p gopath.GoPath) gopath.GoPath { return p.Abs().Clean() }
Now, you can invoke it using Do:
var p = gopath.FromPath("some/path").Do(normalizePath)
func (GoPath) Err ¶
Err returns the error represented by the GoPath. When the GoPath is not errorneous, it returns nil.
func (GoPath) EvalSymlinks ¶
EvalSymlinks calls filepath.EvalSymlinks(). It evaluates any symlinks in the path.
If the path is relative, the result might be relative, too. If an error occurs, it returns an errorneous GoPath.
func (GoPath) FileInfo ¶
FileInfo calls Stat() on GoPath and returns the resulting FileInfo. When Stat() results in an error, or GoPath is already errorneous, the result is a zero interface. When the Stat() result is already cached inside the GoPath, Stat() is not called again.
func (GoPath) Glob ¶
Glob calls filepath.Glob(string) and returns the matches and any possible error.
See also GlobAny(), if you just want one GoPath value. Especially it returns g.Err(), if this GoPath is errorneous.
func (GoPath) GlobAny ¶
GlobAny runs Glob() and selects the first match.
If any error occurs, it returns an errorneous GoPath. Note, that -- according to https://godoc.org/path/filepath#Glob -- this may only occur when the glob expression is not formatted correctly.
If there is no match, an empty GoPath is returned.
func (GoPath) HasErr ¶
HasErr returns true iff the GoPath is errorneous. It returns false otherwise, including the empty GoPath.
func (GoPath) IsDirectory ¶
IsDirectory returns true iff we have no error and the path points to a directory.
func (GoPath) IsEmpty ¶
IsEmpty returns true exactly iff this GoPath contains the empty path:
assert.True(gopath.FromPath("").IsEmpty()) assert.False(gopath.FromPath("/some/empty/file").IsEmpty())
Note, that this does not check the file size, contents or anything like this.
func (GoPath) IsTemporary ¶
func (GoPath) Join ¶
Join appends the other GoPath to this GoPath, separated by the operating systems path separator.
If this GoPath is errorneous, it returns simply this GoPath.
func (GoPath) JoinPath ¶
Join appends the given path to this GoPath, separated by the operating systmes path separator.
If this GoPath is errorneous, it returns simply this GoPath.
func (GoPath) Path ¶
Path returns the path represented by the given GoPath object. If that GoPath is errorneous, a zero value is returned.
func (GoPath) PrependErr ¶
PrependErr modifies this GoPath by prefixing its error text with the given string, followed by a colon and a space. When this GoPath doesn't have an err set, it is returned unchanged.
func (GoPath) Rel ¶
Rel returns the other (targpath) GoPath, expressed as path relative to this GoPath.
var base = gopath.FromPath("/a") var target = gopath.FromPath("/b/c") var rel = base.Rel(target) assert.Equal(rel.Path(), "../b/c")
Note that this func follows the argument order of the filepath.Rel func, while the RelTo() func implements the reverse argument order.
func (GoPath) RelTo ¶
RelTo returns this GoPath, expressed as path relative to the other (base) GoPath.
var base = gopath.FromPath("/a") var target = gopath.FromPath("/b/c") var rel = target.RelTo(base) assert.Equal(rel.Path(), "../b/c")
Note that this func uses the inverse argument order of the filepath.Rel func, while the Rel() func implements the exact argument order.
func (GoPath) Stat ¶
Stat calls os.Stat and caches the FileInfo result inside the returned GoPath. When the Stat call fails, an errorneous GoPath is returned. Stat always calls os.Stat, even if the GoPath already contains a FileInfo.
Be warned: Stat() might cause an errorneous path to be returned, even in normal operation (e.g. file does not exist). An errorneous GoPath will have all operations being no-ops, so take care when using this function.
Note, that Stat() is only useful for caching purposes. FileInfo() delivers the Stat() results even if Stat() was not called explicitly.
type Transformer ¶
Transformer is a func that transforms one GoPath instance into another.