impath

Documentation

Overview

Package impath (immutable path) provides immutable and distinguishable types for absolute and relative paths. This allows for strong guarantees at compile time, improves legibility and reduces maintenance burden.

Index

• Variables
• type Absolute
  • func Abs(elements ...string) (Absolute, error)
  • func MustAbs(elements ...string) Absolute
  • func (p Absolute) Append(elements ...Relative) Absolute
  • func (p Absolute) Base() Relative
  • func (p Absolute) Dir() Absolute
  • func (p Absolute) String() string
• type Relative
  • func Descendant(base Absolute, target Absolute) (Relative, error)
  • func MustRel(elements ...string) Relative
  • func Rel(elements ...string) (Relative, error)
  • func (p Relative) Append(elements ...Relative) Relative
  • func (p Relative) Base() Relative
  • func (p Relative) Dir() Relative
  • func (p Relative) String() string

Variables

var (
	// ErrNotAbsolute indicates that the path is not absolute.
	ErrNotAbsolute = errors.New("path is not absolute")

	// ErrNotRelative indicates that the path is not relative.
	ErrNotRelative = errors.New("path is not relative")

	// ErrNotDescendant indicates that the target is a descendant of base.
	ErrNotDescendant = errors.New("target is not a descendant of base")

	// Root is / on unix-like systems and c:\ on Windows.
	Root = os.Getenv("SYSTEMDRIVE") + string(os.PathSeparator)
)

Types

type Absolute

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

Absolute represents an immutable absolute path. The zero value is Root.

func Abs

func Abs(elements ...string) (Absolute, error)

Abs creates a new absolute and clean path from the specified elements.

If the specified elements do not join to a valid absolute path, ErrNotAbsolute is returned. If the joined path does not contain consecutive separators or dot elements, filepath.Clean is not called.

func MustAbs

func MustAbs(elements ...string) Absolute

MustAbs is a convenient wrapper of Abs that is useful for constant paths.

If the specified elements do not join to a valid absolute path, this function panics.

func (Absolute) Append

func (p Absolute) Append(elements ...Relative) Absolute

Append is a convenient method to join additional elements to this path.

func (Absolute) Base

func (p Absolute) Base() Relative

Base is a convenient method that returns the last path element.

func (Absolute) Dir

func (p Absolute) Dir() Absolute

Dir is a convenient method that returns all path elements except the last.

func (Absolute) String

func (p Absolute) String() string

String implements the Stringer interface and returns the path as a string.

type Relative

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

Relative represents an immutable relative path. The zero value is the empty path, which is an alias to the current directory `.`.

func Descendant

func Descendant(base Absolute, target Absolute) (Relative, error)

Descendant returns a relative path to the base such that when joined together with base using filepath.Join(base, path), the result is lexically equivalent to target.

The returned error is nil or ErrNotDescendant.

func MustRel

func MustRel(elements ...string) Relative

MustRel is a convenient wrapper of Rel that is useful for constant paths.

If the specified elements do not join to a valid relative path, this function panics.

func Rel

func Rel(elements ...string) (Relative, error)

Rel creates a new relative and clean path from the specified elements.

If the specified elements do not join to a valid relative path, ErrNotRelative is returned.

func (Relative) Append

func (p Relative) Append(elements ...Relative) Relative

Append is a convenient method to join additional elements to this path.

func (Relative) Base

func (p Relative) Base() Relative

Base is a convenient method that returns the last path element.

func (Relative) Dir

func (p Relative) Dir() Relative

Dir is a convenient method that returns all path elements except the last.

func (Relative) String

func (p Relative) String() string

String implements the Stringer interface and returns the path as a string.