safepath

package
v0.0.0-...-2561dba Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 15, 2024 License: GPL-3.0 Imports: 3 Imported by: 6

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func HasPrefix 

func HasPrefix(path Path, prefix Dir) bool

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.

func IsAbs 

func IsAbs(path string) bool

IsAbs is a helper that returns true if a string path is considered as such by the presence of a leading slash.

func IsDir 

func IsDir(path string) bool

IsDir is a helper that returns true if a string path is considered as such by the presence of a trailing slash.

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 

func JoinToAbsDir(absDir AbsDir, relDir RelDir) AbsDir

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 

func ParseIntoAbsDir(path string) (AbsDir, error)

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 

func UnsafeParseIntoAbsDir(path string) AbsDir

UnsafeParseIntoAbsDir performs exactly as ParseIntoAbsDir does, but it panics if the latter would have returned an error.

func (AbsDir) Cmp 

func (obj AbsDir) Cmp(absDir AbsDir) error

Cmp compares two AbsDir's and returns nil if they have the same path.

func (AbsDir) HasDir 

func (obj AbsDir) HasDir(relDir RelDir) bool

HasDir returns true if the input relative dir is present in the path.

func (AbsDir) HasDirOne 

func (obj AbsDir) HasDirOne(relDir RelDir) bool

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) IsAbs 

func (obj AbsDir) IsAbs() bool

IsAbs returns true for this struct.

func (AbsDir) IsDir 

func (obj AbsDir) IsDir() bool

IsDir returns true for this struct.

func (AbsDir) PanicValidate 

func (obj AbsDir) PanicValidate()

PanicValidate panics if the path was not specified correctly.

func (AbsDir) Path 

func (obj AbsDir) Path() string

Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.

func (AbsDir) String 

func (obj AbsDir) String() string

String returns the canonical "friendly" representation of this path. If it is a directory, then it will end with a slash.

func (AbsDir) Validate 

func (obj AbsDir) Validate() error

Validate returns an error if the path was not specified correctly.

type AbsFile 

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

AbsFile represents an absolute file path.

func JoinToAbsFile 

func JoinToAbsFile(absDir AbsDir, relFile RelFile) AbsFile

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 

func ParseIntoAbsFile(path string) (AbsFile, error)

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 

func UnsafeParseIntoAbsFile(path string) AbsFile

UnsafeParseIntoAbsFile performs exactly as ParseIntoAbsFile does, but it panics if the latter would have returned an error.

func (AbsFile) Base 

func (obj AbsFile) Base() RelFile

Base returns the last component of the AbsFile, in this case, the filename.

func (AbsFile) Cmp 

func (obj AbsFile) Cmp(absFile AbsFile) error

Cmp compares two AbsFile's and returns nil if they have the same path.

func (AbsFile) Dir 

func (obj AbsFile) Dir() AbsDir

Dir returns the head component of the AbsFile, in this case, the directory.

func (AbsFile) HasDir 

func (obj AbsFile) HasDir(relDir RelDir) bool

HasDir returns true if the input relative dir is present in the path.

func (AbsFile) HasExt 

func (obj AbsFile) HasExt(ext string) bool

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 

func (obj AbsFile) HasExtInsensitive(ext string) bool

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) IsAbs 

func (obj AbsFile) IsAbs() bool

IsAbs returns true for this struct.

func (AbsFile) IsDir 

func (obj AbsFile) IsDir() bool

IsDir returns false for this struct.

func (AbsFile) PanicValidate 

func (obj AbsFile) PanicValidate()

PanicValidate panics if the path was not specified correctly.

func (AbsFile) Path 

func (obj AbsFile) Path() string

Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.

func (AbsFile) String 

func (obj AbsFile) String() string

String returns the canonical "friendly" representation of this path. If it is a directory, then it will end with a slash.

func (AbsFile) Validate 

func (obj AbsFile) Validate() error

Validate returns an error if the path was not specified correctly.

type AbsPath 

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

AbsPath represents an absolute file or dir path.

func ParseIntoAbsPath 

func ParseIntoAbsPath(path string) (AbsPath, error)

ParseIntoAbsPath takes an input path and ensures it's an AbsPath. 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 UnsafeParseIntoAbsPath 

func UnsafeParseIntoAbsPath(path string) AbsPath

UnsafeParseIntoAbsPath performs exactly as ParseIntoAbsPath does, but it panics if the latter would have returned an error.

func (AbsPath) Cmp 

func (obj AbsPath) Cmp(absPath AbsPath) error

Cmp compares two AbsPath's and returns nil if they have the same path.

func (AbsPath) Dir 

func (obj AbsPath) Dir() AbsDir

Dir returns the head component of the AbsPath, in this case, the directory.

func (AbsPath) HasDir 

func (obj AbsPath) HasDir(relDir RelDir) bool

HasDir returns true if the input relative dir is present in the path. TODO: write tests for this and ensure it doesn't have a bug

func (AbsPath) IsAbs 

func (obj AbsPath) IsAbs() bool

IsAbs returns true for this struct.

func (AbsPath) IsDir 

func (obj AbsPath) IsDir() bool

IsDir returns true if this is a dir, and false if it's not based on the path stored within and the parsing criteria in the IsDir helper function.

func (AbsPath) PanicValidate 

func (obj AbsPath) PanicValidate()

PanicValidate panics if the path was not specified correctly.

func (AbsPath) Path 

func (obj AbsPath) Path() string

Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.

func (AbsPath) String 

func (obj AbsPath) String() string

String returns the canonical "friendly" representation of this path. If it is a directory, then it will end with a slash.

func (AbsPath) Validate 

func (obj AbsPath) Validate() error

Validate returns an error if the path was not specified correctly.

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 

func ParseIntoDir(path string) (Dir, error)

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 

func UnsafeParseIntoDir(path string) Dir

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 

func ParseIntoFile(path string) (File, error)

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 

func UnsafeParseIntoFile(path string) File

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 

func ParseIntoPath(path string, isDir bool) (Path, error)

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 

func SmartParseIntoPath(path string) (Path, error)

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 

func StripPrefix(path Path, prefix Dir) (Path, error)

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 

func UnsafeParseIntoPath(path string, isDir bool) Path

UnsafeParseIntoPath performs exactly as ParseIntoPath does, but it panics if the latter would have returned an error.

func UnsafeSmartParseIntoPath 

func UnsafeSmartParseIntoPath(path string) Path

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 

func JoinToRelDir(relDir ...RelDir) RelDir

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 

func ParseIntoRelDir(path string) (RelDir, error)

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 

func UnsafeParseIntoRelDir(path string) RelDir

UnsafeParseIntoRelDir performs exactly as ParseIntoRelDir does, but it panics if the latter would have returned an error.

func (RelDir) Cmp 

func (obj RelDir) Cmp(relDir RelDir) error

Cmp compares two RelDir's and returns nil if they have the same path.

func (RelDir) HasDir 

func (obj RelDir) HasDir(relDir RelDir) bool

HasDir returns true if the input relative dir is present in the path.

func (RelDir) HasDirOne 

func (obj RelDir) HasDirOne(relDir RelDir) bool

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) IsAbs 

func (obj RelDir) IsAbs() bool

IsAbs returns false for this struct.

func (RelDir) IsDir 

func (obj RelDir) IsDir() bool

IsDir returns true for this struct.

func (RelDir) PanicValidate 

func (obj RelDir) PanicValidate()

PanicValidate panics if the path was not specified correctly.

func (RelDir) Path 

func (obj RelDir) Path() string

Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.

func (RelDir) String 

func (obj RelDir) String() string

String returns the canonical "friendly" representation of this path. If it is a directory, then it will end with a slash.

func (RelDir) Validate 

func (obj RelDir) Validate() error

Validate returns an error if the path was not specified correctly.

type RelFile 

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

RelFile represents a relative file path.

func JoinToRelFile 

func JoinToRelFile(relDir RelDir, relFile RelFile) RelFile

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 

func ParseIntoRelFile(path string) (RelFile, error)

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 

func UnsafeParseIntoRelFile(path string) RelFile

UnsafeParseIntoRelFile performs exactly as ParseIntoRelFile does, but it panics if the latter would have returned an error.

func (RelFile) Cmp 

func (obj RelFile) Cmp(relfile RelFile) error

Cmp compares two RelFile's and returns nil if they have the same path.

func (RelFile) HasDir 

func (obj RelFile) HasDir(relDir RelDir) bool

HasDir returns true if the input relative dir is present in the path.

func (RelFile) HasExt 

func (obj RelFile) HasExt(ext string) bool

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 

func (obj RelFile) HasExtInsensitive(ext string) bool

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) IsAbs 

func (obj RelFile) IsAbs() bool

IsAbs returns false for this struct.

func (RelFile) IsDir 

func (obj RelFile) IsDir() bool

IsDir returns false for this struct.

func (RelFile) PanicValidate 

func (obj RelFile) PanicValidate()

PanicValidate panics if the path was not specified correctly.

func (RelFile) Path 

func (obj RelFile) Path() string

Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.

func (RelFile) String 

func (obj RelFile) String() string

String returns the canonical "friendly" representation of this path. If it is a directory, then it will end with a slash.

func (RelFile) Validate 

func (obj RelFile) Validate() error

Validate returns an error if the path was not specified correctly.

type RelPath 

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

RelPath represents a relative file or dir path.

func ParseIntoRelPath 

func ParseIntoRelPath(path string) (RelPath, error)

ParseIntoRelPath takes an input path and ensures it's an RelPath. 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 UnsafeParseIntoRelPath 

func UnsafeParseIntoRelPath(path string) RelPath

UnsafeParseIntoRelPath performs exactly as ParseIntoRelPath does, but it panics if the latter would have returned an error.

func (RelPath) Cmp 

func (obj RelPath) Cmp(relpath RelPath) error

Cmp compares two RelPath's and returns nil if they have the same path.

func (RelPath) HasDir 

func (obj RelPath) HasDir(relDir RelDir) bool

HasDir returns true if the input relative dir is present in the path. TODO: write tests for this and ensure it doesn't have a bug

func (RelPath) IsAbs 

func (obj RelPath) IsAbs() bool

IsAbs returns false for this struct.

func (RelPath) IsDir 

func (obj RelPath) IsDir() bool

IsDir returns true if this is a dir, and false if it's not based on the path stored within and the parsing criteria in the IsDir helper function.

func (RelPath) PanicValidate 

func (obj RelPath) PanicValidate()

PanicValidate panics if the path was not specified correctly.

func (RelPath) Path 

func (obj RelPath) Path() string

Path returns the cleaned version of this path. It is what you expect after running the golang path cleaner on the internal representation.

func (RelPath) String 

func (obj RelPath) String() string

String returns the canonical "friendly" representation of this path. If it is a directory, then it will end with a slash.

func (RelPath) Validate 

func (obj RelPath) Validate() error

Validate returns an error if the path was not specified correctly.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.