README
¶
path
This enhances the standard path API with some extra functions. This API is intended to be a drop-in replacement; it merely calls through to the standard API where there is duplication.
There is also a type Path, which is a kind of string. Path provides a similar set of methods to the helper functions.
Please see the GoDoc for more.
Installation
go get -u github.com/rickb777/path
Status
This library has been in reliable production use for some time. Versioning follows the well-known semantic version pattern.
Licence
Documentation
¶
Overview ¶
Package path implements utility routines for manipulating slash-separated paths. This deliberately resembles the standard path API closely. The similarity is intentional and credit is due to the Go authors for their work.
This package may serve as a drop-in replacement for the standard path package. In addition to the functions available in the standard path package, there are extra functions for dividing paths.
There is also a type Path. This allows path strings to be manipulated using methods instead of helper functions. These methods follow a similar design, and also allow iteration through path segments.
This package should only be used for paths separated by forward slashes, such as the paths in URLs.
Index ¶
- Variables
- func Base(path string) string
- func Clean(path string) string
- func Dir(path string) string
- func Divide(path string, nth int) (string, string)
- func Drop(path string, unwanted int) string
- func Ext(path string) string
- func IsAbs(path string) bool
- func Join(elem ...string) string
- func Match(pattern, name string) (matched bool, err error)
- func Split(path string) (dir, file string)
- func SplitExt(path string) (string, string)
- func Take(path string, wanted int) string
- type Path
- func (path Path) Append(elem ...string) Path
- func (path Path) Base() string
- func (path Path) Clean() Path
- func (path Path) Dir() Path
- func (path Path) Divide(nth int) (Path, Path)
- func (path Path) Drop(unwanted int) Path
- func (path Path) Ext() string
- func (path Path) ExtOnly() string
- func (path Path) HasPrefix(other Path) bool
- func (path Path) HasSuffix(other Path) bool
- func (path Path) IsAbs() bool
- func (path Path) IsEmpty() bool
- func (path Path) Join(p2 Path) Path
- func (path Path) Next() (string, Path)
- func (path Path) Prepend(elem ...string) Path
- func (path *Path) Scan(value interface{}) error
- func (path Path) Segments() []string
- func (path Path) Split() (dir Path, file string)
- func (path Path) SplitExt() (Path, string)
- func (path Path) String() string
- func (path Path) Take(wanted int) Path
- func (path Path) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
var ErrBadPattern = std.ErrBadPattern
ErrBadPattern indicates a globbing pattern was malformed.
Functions ¶
func Base ¶
Base returns the last element of path. Trailing slashes are removed before extracting the last element. If the path is empty, Base returns ".". If the path consists entirely of slashes, Base returns "/".
func Clean ¶
Clean returns the shortest path name equivalent to path by purely lexical processing. It applies the following rules iteratively until no further processing can be done:
- Replace multiple slashes with a single slash.
- Eliminate each . path name element (the current directory).
- Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
- Eliminate .. elements that begin a rooted path: that is, replace "/.." by "/" at the beginning of a path.
The returned path ends in a slash only if it is the root "/".
If the result of this process is an empty string, Clean returns the string ".".
See also Rob Pike, “Lexical File Names in Plan 9 or Getting Dot-Dot Right,” https://9p.io/sys/doc/lexnames.html
func Dir ¶
Dir returns all but the last element of path, typically the path's directory. After dropping the final element using Split, the path is Cleaned and trailing slashes are removed. If the path is empty, Dir returns ".". If the path consists entirely of slashes followed by non-slash bytes, Dir returns a single slash. In any other case, the returned path does not end in a slash.
func Divide ¶
Divide divides a path at the nth slash, not counting the leading slash if there is one.
The resulting pair (head, tail) always satisfy
head + tail = path
func Ext ¶
Ext returns the file name extension used by path. The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot.
func Join ¶
Join joins any number of path elements into a single path, adding a separating slash if necessary. The result is Cleaned; in particular, all empty strings are ignored.
func Match ¶
Match reports whether name matches the shell file name pattern. The pattern syntax is:
pattern:
{ term }
term:
'*' matches any sequence of non-/ characters
'?' matches any single non-/ character
'[' [ '^' ] { character-range } ']'
character class (must be non-empty)
c matches character c (c != '*', '?', '\\', '[')
'\\' c matches character c
character-range:
c matches character c (c != '\\', '-', ']')
'\\' c matches character c
lo '-' hi matches character c for lo <= c <= hi
Match requires pattern to match all of name, not just a substring. The only possible returned error is ErrBadPattern, when pattern is malformed.
func Split ¶
Split splits path immediately following the final slash, separating it into a directory and file name component. If there is no slash in path, Split returns an empty dir and file set to path. The returned values have the property that path = dir+file.
func SplitExt ¶ added in v1.1.0
SplitExt splits the file name from its extension. The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot. The dot is included in the extension.
Everything prior to the last dot is returned as the first result.
Types ¶
type Path ¶ added in v0.8.0
type Path string
Path is just a string with specialised methods.
func Of ¶ added in v0.12.0
Of joins any number of path elements to build a new path, adding a separating slashes as necessary. The result is Cleaned; in particular, all empty strings are ignored.
If the first non-blank elem has a leading slash, the path will also have a leading slash. It will not have a trailing slash.
func OfAny ¶ added in v0.14.0
func OfAny(elem ...interface{}) Path
OfAny joins any number of path elements to build a new path, adding a separating slashes as necessary. Each element is treated as either a string, or a Path, or some other type; in the latter case, it is formatted using fmt.Sprintf so the "%v" rules apply.
The result is Cleaned; in particular, all empty strings are ignored.
If the first non-blank elem has a leading slash, the path will also have a leading slash. It will not have a trailing slash.
func (Path) Append ¶ added in v0.8.0
Append joins some more segments to the end of the path. It adds separating slashes as necessary. The result is Cleaned; in particular, all empty strings are ignored.
func (Path) Base ¶ added in v0.8.0
Base returns the last element of path. Trailing slashes are removed before extracting the last element. If the path is empty, Base returns ".". If the path consists entirely of slashes, Base returns "/".
func (Path) Clean ¶ added in v0.8.0
Clean returns the shortest path name equivalent to path by purely lexical processing. It applies the following rules iteratively until no further processing can be done:
- Replace multiple slashes with a single slash.
- Eliminate each . path name element (the current directory).
- Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
- Eliminate .. elements that begin a rooted path: that is, replace "/.." by "/" at the beginning of a path.
The returned path ends in a slash only if it is the root "/".
If the result of this process is an empty string, Clean returns the string ".".
See also Rob Pike, “Lexical File Names in Plan 9 or Getting Dot-Dot Right,” https://9p.io/sys/doc/lexnames.html
func (Path) Dir ¶ added in v0.8.0
Dir returns all but the last element of path, typically the path's directory. After dropping the final element using Split, the path is Cleaned and trailing slashes are removed. If the path is empty, Dir returns ".". If the path consists entirely of slashes followed by non-slash bytes, Dir returns a single slash. In any other case, the returned path does not end in a slash.
func (Path) Divide ¶ added in v0.8.0
Divide divides a path at the nth slash, not counting the leading slash if there is one.
The resulting pair (head, tail) always satisfy
head + tail = path
func (Path) Ext ¶ added in v0.8.0
Ext returns the file name extension used by path. The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot.
Unlike ExtOnly, the dot is included in the result.
func (Path) ExtOnly ¶ added in v0.15.0
ExtOnly returns the file name extension used by path. The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot.
Unlike Ext, the dot is not included in the result.
func (Path) HasPrefix ¶ added in v0.13.0
HasPrefix reports whether the path starts with a particular prefix.
func (Path) HasSuffix ¶ added in v0.13.0
HasSuffix reports whether the path ends with a particular suffix.
func (Path) Join ¶ added in v1.3.0
Join joins a segment to the end of the path. It adds separating slashes as necessary. The result is Cleaned; in particular, all empty strings are ignored.
func (Path) Next ¶ added in v0.8.0
Next returns the first segment (without any leading '/') and the rest. It can be used for iterating through the path segments; the end has been reached when the tail is empty (see IsEmpty).
func (Path) Prepend ¶ added in v0.11.0
Prepend joins some more segments to the beginning of the path. It adds separating slashes as necessary. The result is Cleaned; in particular, all empty strings are ignored.
func (*Path) Scan ¶ added in v0.10.0
Scan parses some value. It implements sql.Scanner, https://golang.org/pkg/database/sql/#Scanner
func (Path) Segments ¶ added in v0.8.0
Segments returns the path split into the parts between slashes. Any leading or trailing slash on the path is removed before the path is split, so there is no leading or trailing blank string in the result.
The root path "/" will return nil. A blank path will also return nil; this ensures that the Segments of the zero value of Path is a zero value of []string.
func (Path) Split ¶ added in v0.8.0
Split splits path immediately following the final slash, separating it into a directory and file name component. If there is no slash in path, Split returns an empty dir and file set to path. The returned values have the property that path = dir+file.
func (Path) SplitExt ¶ added in v1.1.0
SplitExt splits the file name from its extension. The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot. The dot is included in the extension.
Everything prior to the last dot is returned as the first result.
Source Files