query
On this page

normalise

lib.path.subpath.normalise

Docs pulled from | This Revision | 10 minutes ago


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

subpath.normalise usage example

# 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

Implementation

The following is the current implementation of this function.

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