paths

README

paths: a golang library to simplify handling of paths

This library aims to simplify handling of the most common operations with paths.

For example code that looked like this:

buildPath := getPathFromSomewhere() // returns string
if buildPath != "" {
	cachePath, err := filepath.Abs(filepath.Join(buildPath, "cache"))
	...
}

can be transformed to:

buildPath := getPathFromSomewhere() // returns *paths.Path
if buildPath != nil {
	cachePath, err := buildPath.Join("cache").Abs()
	...
}

most operations that usually requires a bit of convoluted system calls are now simplified, for example to check if a path is a directory:

buildPath := "/path/to/somewhere"
srcPath := filepath.Join(buildPath, "src")
if info, err := os.Stat(srcPath); err == nil && !info.IsDir() {
    os.MkdirAll(srcPath)
}

using this library can be done this way:

buildPath := paths.New("/path/to/somewhere")
srcPath := buildPath.Join("src")
if !srcPath.IsDir() {
    scrPath.MkdirAll()
}

Documentation

Index

• func MkTempFile(dir *Path, prefix string) (*os.File, error)
• type Path
  • func Getwd() (*Path, error)
  • func MkTempDir(dir, prefix string) (*Path, error)
  • func New(path ...string) *Path
  • func NewFromFile(file *os.File) *Path
  • func NullPath() *Path
  • func TempDir() *Path
  • func WriteToTempFile(data []byte, dir *Path, prefix string) (res *Path, err error)
  • func (p *Path) Abs() (*Path, error)
  • func (p *Path) Append() (*os.File, error)
  • func (p *Path) Base() string
  • func (p *Path) Canonical() *Path
  • func (p *Path) Chtimes(atime, mtime time.Time) error
  • func (p *Path) Clean() *Path
  • func (p *Path) Clone() *Path
  • func (p *Path) CopyDirTo(dst *Path) error
  • func (p *Path) CopyTo(dst *Path) error
  • func (p *Path) Create() (*os.File, error)
  • func (p *Path) EqualsTo(other *Path) bool
  • func (p *Path) EquivalentTo(other *Path) bool
  • func (p *Path) Exist() bool
  • func (p *Path) ExistCheck() (bool, error)
  • func (p *Path) Ext() string
  • func (p *Path) FollowSymLink() error
  • func (p *Path) HasPrefix(prefixes ...string) bool
  • func (p *Path) HasSuffix(suffixies ...string) bool
  • func (p *Path) IsAbs() bool
  • func (p *Path) IsDir() bool
  • func (p *Path) IsDirCheck() (bool, error)
  • func (p *Path) IsInsideDir(dir *Path) (bool, error)
  • func (p *Path) IsNotDir() bool
  • func (p *Path) Join(paths ...string) *Path
  • func (p *Path) JoinPath(paths ...*Path) *Path
  • func (p *Path) MarshalJSON() ([]byte, error)
  • func (p *Path) MkTempDir(prefix string) (*Path, error)
  • func (p *Path) Mkdir() error
  • func (p *Path) MkdirAll() error
  • func (p *Path) NotExist() bool
  • func (p *Path) Open() (*os.File, error)
  • func (p *Path) Parent() *Path
  • func (p *Path) Parents() []*Path
  • func (p *Path) ReadDir() (PathList, error)
  • func (p *Path) ReadDirRecursive() (PathList, error)
  • func (p *Path) ReadFile() ([]byte, error)
  • func (p *Path) ReadFileAsLines() ([]string, error)
  • func (p *Path) RelFrom(r *Path) (*Path, error)
  • func (p *Path) RelTo(r *Path) (*Path, error)
  • func (p *Path) Remove() error
  • func (p *Path) RemoveAll() error
  • func (p *Path) Rename(newpath *Path) error
  • func (p *Path) Stat() (os.FileInfo, error)
  • func (p *Path) String() string
  • func (p *Path) ToAbs() error
  • func (p *Path) Truncate() error
  • func (p *Path) UnmarshalJSON(b []byte) error
  • func (p *Path) WriteFile(data []byte) error
• type PathList
  • func NewPathList(paths ...string) PathList
  • func (p *PathList) Add(path *Path)
  • func (p *PathList) AddAll(paths PathList)
  • func (p *PathList) AddAllMissing(pathsToAdd PathList)
  • func (p *PathList) AddIfMissing(path *Path)
  • func (p *PathList) AsStrings() []string
  • func (p *PathList) Clone() PathList
  • func (p *PathList) Contains(pathToSearch *Path) bool
  • func (p *PathList) ContainsEquivalentTo(pathToSearch *Path) bool
  • func (p *PathList) FilterDirs()
  • func (p *PathList) FilterOutDirs()
  • func (p *PathList) FilterOutHiddenFiles()
  • func (p *PathList) FilterOutPrefix(prefixes ...string)
  • func (p *PathList) FilterOutSuffix(suffixies ...string)
  • func (p *PathList) FilterPrefix(prefixes ...string)
  • func (p *PathList) FilterSuffix(suffixies ...string)
  • func (p *PathList) Len() int
  • func (p *PathList) Less(i, j int) bool
  • func (p *PathList) Sort()
  • func (p *PathList) Swap(i, j int)
  • func (p *PathList) ToAbs() error

Functions

func MkTempFile

func MkTempFile(dir *Path, prefix string) (*os.File, error)

MkTempFile creates a new temporary file in the directory dir with a name beginning with prefix, opens the file for reading and writing, and returns the resulting *os.File. If dir is nil, MkTempFile uses the default directory for temporary files (see paths.TempDir). Multiple programs calling TempFile simultaneously will not choose the same file. The caller can use f.Name() to find the pathname of the file. It is the caller's responsibility to remove the file when no longer needed.

Types

type Path

type Path struct {
	// contains filtered or unexported fields
}

Path represents a path

func Getwd

func Getwd() (*Path, error)

Getwd returns a rooted path name corresponding to the current directory.

func MkTempDir

func MkTempDir(dir, prefix string) (*Path, error)

MkTempDir creates a new temporary directory in the directory dir with a name beginning with prefix and returns the path of the new directory. If dir is the empty string, TempDir uses the default directory for temporary files

func New

func New(path ...string) *Path

New creates a new Path object. If path is the empty string then nil is returned.

func NewFromFile

func NewFromFile(file *os.File) *Path

NewFromFile creates a new Path object using the path name obtained from the File object (see os.File.Name function).

func NullPath

func NullPath() *Path

NullPath return the path to the /dev/null equivalent for the current OS

func TempDir

func TempDir() *Path

TempDir returns the default path to use for temporary files

func WriteToTempFile

func WriteToTempFile(data []byte, dir *Path, prefix string) (res *Path, err error)

WriteToTempFile writes data to a newly generated temporary file. dir and prefix have the same meaning for MkTempFile. In case of success the Path to the temp file is returned.

func (*Path) Abs

func (p *Path) Abs() (*Path, error)

Abs returns the absolute path of the current Path

func (*Path) Append

func (p *Path) Append() (*os.File, error)

Append opens a file for append or creates it if the file doesn't exist.

func (*Path) Base

func (p *Path) Base() string

Base returns the last element of path

func (*Path) Canonical

func (p *Path) Canonical() *Path

Canonical return a "canonical" Path for the given filename. The meaning of "canonical" is OS-dependent but the goal of this method is to always return the same path for a given file (factoring out all the possibile ambiguities including, for example, relative paths traversal, symlinks, drive volume letter case, etc).

func (*Path) Chtimes

func (p *Path) Chtimes(atime, mtime time.Time) error

Chtimes changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.

func (*Path) Clean

func (p *Path) Clean() *Path

Clean Clean returns the shortest path name equivalent to path by purely lexical processing

func (*Path) Clone

func (p *Path) Clone() *Path

Clone create a copy of the Path object

func (*Path) CopyDirTo

func (p *Path) CopyDirTo(dst *Path) error

CopyDirTo recursively copies the directory denoted by the current path to the destination path. The source directory must exist and the destination directory must NOT exist (no implicit destination name allowed). Symlinks are not copied, they will be supported in future versions.

func (*Path) CopyTo

func (p *Path) CopyTo(dst *Path) error

CopyTo copies the contents of the file named src to the file named by dst. The file will be created if it does not already exist. If the destination file exists, all it's contents will be replaced by the contents of the source file. The file mode will be copied from the source and the copied data is synced/flushed to stable storage.

func (*Path) Create

func (p *Path) Create() (*os.File, error)

Create creates or truncates a file. It calls os.Create on the underlying path.

func (*Path) EqualsTo

func (p *Path) EqualsTo(other *Path) bool

EqualsTo return true if both paths are equal

func (*Path) EquivalentTo

func (p *Path) EquivalentTo(other *Path) bool

EquivalentTo return true if both paths are equivalent (they points to the same file even if they are lexicographically different) based on the current working directory.

func (*Path) Exist

func (p *Path) Exist() bool

Exist return true if the file denoted by this path exists, false in any other case (also in case of error).

func (*Path) ExistCheck

func (p *Path) ExistCheck() (bool, error)

ExistCheck return true if the path exists or false if the path doesn't exists. In case the check fails false is returned together with the corresponding error.

func (*Path) Ext

func (p *Path) Ext() string

Ext returns the file name extension used by path

func (*Path) FollowSymLink

func (p *Path) FollowSymLink() error

FollowSymLink transforms the current path to the path pointed by the symlink if path is a symlink, otherwise it does nothing

func (*Path) HasPrefix

func (p *Path) HasPrefix(prefixes ...string) bool

HasPrefix returns true if the file name has one of the given prefixes (the Base() method is used to obtain the file name used for the comparison)

func (*Path) HasSuffix

func (p *Path) HasSuffix(suffixies ...string) bool

HasSuffix returns true if the file name has one of the given suffixies

func (*Path) IsAbs

func (p *Path) IsAbs() bool

IsAbs returns true if the Path is absolute

func (*Path) IsDir

func (p *Path) IsDir() bool

IsDir returns true if the path exists and is a directory. In all the other cases (and also in case of any error) false is returned.

func (*Path) IsDirCheck

func (p *Path) IsDirCheck() (bool, error)

IsDirCheck return true if the path exists and is a directory or false if the path exists and is not a directory. In all the other case false and the corresponding error is returned.

func (*Path) IsInsideDir

func (p *Path) IsInsideDir(dir *Path) (bool, error)

IsInsideDir returns true if the current path is inside the provided dir

func (*Path) IsNotDir

func (p *Path) IsNotDir() bool

IsNotDir returns true if the path exists and is NOT a directory. In all the other cases (and also in case of any error) false is returned.

func (*Path) Join

func (p *Path) Join(paths ...string) *Path

Join create a new Path by joining the provided paths

func (*Path) JoinPath

func (p *Path) JoinPath(paths ...*Path) *Path

JoinPath create a new Path by joining the provided paths

func (*Path) MarshalJSON

func (p *Path) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface

func (*Path) MkTempDir

func (p *Path) MkTempDir(prefix string) (*Path, error)

MkTempDir creates a new temporary directory inside the path pointed by the Path object with a name beginning with prefix and returns the path of the new directory.

func (*Path) Mkdir

func (p *Path) Mkdir() error

Mkdir create a directory denoted by the current path

func (*Path) MkdirAll

func (p *Path) MkdirAll() error

MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error

func (*Path) NotExist

func (p *Path) NotExist() bool

NotExist return true if the file denoted by this path DO NOT exists, false in any other case (also in case of error).

func (*Path) Open

func (p *Path) Open() (*os.File, error)

Open opens a file for reading. It calls os.Open on the underlying path.

func (*Path) Parent

func (p *Path) Parent() *Path

Parent returns all but the last element of path, typically the path's directory or the parent directory if the path is already a directory

func (*Path) Parents

func (p *Path) Parents() []*Path

Parents returns all the parents directories of the current path. If the path is absolute it starts from the current path to the root, if the path is relative is starts from the current path to the current directory. The path should be clean for this method to work properly (no .. or . or other shortcuts). This function does not performs any check on the returned paths.

func (*Path) ReadDir

func (p *Path) ReadDir() (PathList, error)

ReadDir returns a PathList containing the content of the directory pointed by the current Path

func (*Path) ReadDirRecursive

func (p *Path) ReadDirRecursive() (PathList, error)

ReadDirRecursive returns a PathList containing the content of the directory and its subdirectories pointed by the current Path

func (*Path) ReadFile

func (p *Path) ReadFile() ([]byte, error)

ReadFile reads the file named by filename and returns the contents

func (*Path) ReadFileAsLines

func (p *Path) ReadFileAsLines() ([]string, error)

ReadFileAsLines reads the file named by filename and returns it as an array of lines. This function takes care of the newline encoding differences between different OS

func (*Path) RelFrom

func (p *Path) RelFrom(r *Path) (*Path, error)

RelFrom returns a relative Path that when joined with r is lexically equivalent to the current path.

For example paths.New("/my/path/ab/cd").RelFrom(paths.New("/my/path")) returns "ab/cd".

func (*Path) RelTo

func (p *Path) RelTo(r *Path) (*Path, error)

RelTo returns a relative Path that is lexically equivalent to r when joined to the current Path.

For example paths.New("/my/path/ab/cd").RelTo(paths.New("/my/path")) returns "../..".

func (*Path) Remove

func (p *Path) Remove() error

Remove removes the named file or directory

func (*Path) RemoveAll

func (p *Path) RemoveAll() error

RemoveAll removes path and any children it contains. It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error).

func (*Path) Rename

func (p *Path) Rename(newpath *Path) error

Rename renames (moves) the path to newpath. If newpath already exists and is not a directory, Rename replaces it. OS-specific restrictions may apply when oldpath and newpath are in different directories. If there is an error, it will be of type *os.LinkError.

func (*Path) Stat

func (p *Path) Stat() (os.FileInfo, error)

Stat returns a FileInfo describing the named file. The result is cached internally for next queries. To ensure that the cached FileInfo entry is updated just call Stat again.

func (*Path) String

func (p *Path) String() string

func (*Path) ToAbs

func (p *Path) ToAbs() error

ToAbs transofrm the current Path to the corresponding absolute path

func (*Path) Truncate

func (p *Path) Truncate() error

Truncate create an empty file named by path or if the file already exist it truncates it (delete all contents)

func (*Path) UnmarshalJSON

func (p *Path) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaler interface

func (*Path) WriteFile

func (p *Path) WriteFile(data []byte) error

WriteFile writes data to a file named by filename. If the file does not exist, WriteFile creates it otherwise WriteFile truncates it before writing.

type PathList

type PathList []*Path

PathList is a list of Path

func NewPathList

func NewPathList(paths ...string) PathList

NewPathList creates a new PathList with the given paths

func (*PathList) Add

func (p *PathList) Add(path *Path)

Add adds a Path to the PathList

func (*PathList) AddAll

func (p *PathList) AddAll(paths PathList)

AddAll adds all Paths in the list passed as argument

func (*PathList) AddAllMissing

func (p *PathList) AddAllMissing(pathsToAdd PathList)

AddAllMissing adds all paths to the PathList excluding the paths already in the list

func (*PathList) AddIfMissing

func (p *PathList) AddIfMissing(path *Path)

AddIfMissing adds a Path to the PathList if the path is not already in the list

func (*PathList) AsStrings

func (p *PathList) AsStrings() []string

AsStrings return this path list as a string array

func (*PathList) Clone

func (p *PathList) Clone() PathList

Clone returns a copy of the current PathList

func (*PathList) Contains

func (p *PathList) Contains(pathToSearch *Path) bool

Contains check if the list contains a path that match exactly (EqualsTo) to the specified path

func (*PathList) ContainsEquivalentTo

func (p *PathList) ContainsEquivalentTo(pathToSearch *Path) bool

ContainsEquivalentTo check if the list contains a path that is equivalent (EquivalentTo) to the specified path

func (*PathList) FilterDirs

func (p *PathList) FilterDirs()

FilterDirs remove all entries except directories

func (*PathList) FilterOutDirs

func (p *PathList) FilterOutDirs()

FilterOutDirs remove all directories entries

func (*PathList) FilterOutHiddenFiles

func (p *PathList) FilterOutHiddenFiles()

FilterOutHiddenFiles remove all hidden files (files with the name starting with ".")

func (*PathList) FilterOutPrefix

func (p *PathList) FilterOutPrefix(prefixes ...string)

FilterOutPrefix remove all entries having the specified prefixes

func (*PathList) FilterOutSuffix

func (p *PathList) FilterOutSuffix(suffixies ...string)

FilterOutSuffix remove all entries having the specified suffix

func (*PathList) FilterPrefix

func (p *PathList) FilterPrefix(prefixes ...string)

FilterPrefix remove all entries not having one of the specified prefixes

func (*PathList) FilterSuffix

func (p *PathList) FilterSuffix(suffixies ...string)

FilterSuffix remove all entries not having the specified prefix

func (*PathList) Len

func (p *PathList) Len() int

func (*PathList) Less

func (p *PathList) Less(i, j int) bool

func (*PathList) Sort

func (p *PathList) Sort()

Sort sorts this pathlist

func (*PathList) Swap

func (p *PathList) Swap(i, j int)

func (*PathList) ToAbs

func (p *PathList) ToAbs() error

ToAbs calls Path.ToAbs() method on each path of the list. It stops at the first error and returns it. If all ToAbs calls are successful nil is returned.