lib.path.subpath.normalise

Normalise a subpath. Throw an error if the subpath isn't valid.

• Limit repeating / to a single one.

• Remove redundant . components.

• Remove trailing / and /..

• Add leading ./.

Laws:

• Idempotency - normalising multiple times gives the same result:

  subpath.normalise (subpath.normalise p) == subpath.normalise p
  

• Uniqueness - there's only a single normalisation for the paths that lead to the same file system node:

  subpath.normalise p != subpath.normalise q -> $(realpath ${p}) != $(realpath ${q})
  

• Don't change the result when appended to a Nix path value:

  append base p == append base (subpath.normalise p)
  

• Don't change the path according to realpath:

  $(realpath ${p}) == $(realpath ${subpath.normalise p})
  

• Only error on invalid subpaths:

  builtins.tryEval (subpath.normalise p)).success == subpath.isValid p
  

Inputs

subpath

The subpath string to normalise

Type

subpath.normalise :: String -> String

Examples

# limit repeating `/` to a single one
subpath.normalise "foo//bar"
=> "./foo/bar"

# remove redundant `.` components
subpath.normalise "foo/./bar"
=> "./foo/bar"

# add leading `./`
subpath.normalise "foo/bar"
=> "./foo/bar"

# remove trailing `/`
subpath.normalise "foo/bar/"
=> "./foo/bar"

# remove trailing `/.`
subpath.normalise "foo/bar/."
=> "./foo/bar"

# Return the current directory as `./.`
subpath.normalise "."
=> "./."

# error on `..` path components
subpath.normalise "foo/../bar"
=> <error>

# error on empty string
subpath.normalise ""
=> <error>

# error on absolute path
subpath.normalise "/foo"
=> <error>

Noogle detected

subpath.normalise =
    # The subpath string to normalise
    subpath:
    assert assertMsg (isValid subpath) ''
      lib.path.subpath.normalise: Argument is not a valid subpath string:
          ${subpathInvalidReason subpath}'';
    joinRelPath (splitRelPath subpath);