Module

Pathy.Path

#Path

data Path :: RelOrAbs -> DirOrFile -> Typedata Path a b

A type that describes a Path. All flavors of paths are described by this type, whether they are absolute or relative paths and whether they refer to files or directories.

  • The type parameter a describes whether the path is Rel or Abs.
  • The type parameter b describes whether the path is File or Dir.

To ensure type safety, there is no way for users to create a value of this type directly. Instead, helpers should be used, such as rootDir, currentDir, file, dir, (</>), and parsePath.

This ADT allows invalid paths (e.g. paths inside files), but there is no possible way for such paths to be constructed by user-land code.

Instances

#AnyPath

type AnyPath :: RelOrAbs -> Typetype AnyPath a = Either (Path a Dir) (Path a File)

A type describing a file or directory path.

#RelPath

type RelPath = AnyPath Rel

A type describing a relative file or directory path.

#AbsPath

type AbsPath = AnyPath Abs

A type describing an absolute file or directory path.

#RelDir

type RelDir = Path Rel Dir

A type describing a directory whose location is given relative to some other, unspecified directory (referred to as the "current directory").

#AbsDir

type AbsDir = Path Abs Dir

A type describing a directory whose location is absolutely specified.

#AnyDir

type AnyDir = Either AbsDir RelDir

A type describing a absolute or relative directory path.

#RelFile

type RelFile = Path Rel File

A type describing a file whose location is given relative to some other, unspecified directory (referred to as the "current directory").

#AbsFile

type AbsFile = Path Abs File

A type describing a file whose location is absolutely specified.

#AnyFile

type AnyFile = Either AbsFile RelFile

A type describing a absolute or relative file path.

#rootDir

rootDir :: Path Abs Dir

The root directory, which can be used to define absolutely-located resources.

#currentDir

currentDir :: Path Rel Dir

The "current directory", which can be used to define relatively-located resources.

#dir

dir :: forall s proxy. IsName s => proxy s -> Path Rel Dir

Creates a path which points to a relative directory of the specified name.

Instead of accepting a runtime value, this function accepts a type-level string via a proxy, to ensure the constructed name is not empty.

#dir'

dir' :: Name Dir -> Path Rel Dir

Creates a path which points to a relative directory of the specified name.

#file

file :: forall s proxy. IsName s => proxy s -> Path Rel File

Creates a path which points to a relative file of the specified name.

Instead of accepting a runtime value, this function accepts a type-level string via a proxy, to ensure the constructed name is not empty.

#file'

file' :: Name File -> Path Rel File

Creates a path which points to a relative file of the specified name.

#in'

in' :: forall a. Name a -> Path Rel a

Creates a path which points to a relative directory or file of the specified name. In most cases dir' or file' should be used instead, but it's still there in case the segment type is going to be determined based on some type variable.

p == maybe p (\(Tuple r n) -> r </> in' n) (peel p)

#parentOf

parentOf :: forall a. IsRelOrAbs a => Path a Dir -> Path a Dir

Creates a path that points to the parent directory of the specified path.

Calling parentOf on rootDir will return rootDir.

#extendPath

extendPath :: forall a b. Path a Dir -> Name b -> Path a b

Extends a path with a file or directory under the current path.

#appendPath

appendPath :: forall a b. IsRelOrAbs a => Path a Dir -> Path Rel b -> Path a b

Given a directory path, appends a relative path to extend the original path.

#(</>)

Operator alias for Pathy.Path.appendPath (left-associative / precedence 6)

#parentAppend

parentAppend :: forall a b. IsRelOrAbs a => Path a Dir -> Path Rel b -> Path a b

Ascends into the parent of the specified directory, then descends into the specified path.

rootDir </> dir "foo" <..> dir "bar" = rootDir </> dir "bar"

#(<..>)

Operator alias for Pathy.Path.parentAppend (left-associative / precedence 6)

#foldPath

foldPath :: forall a b r. r -> (Path Rel Dir -> r) -> (Path a Dir -> Name b -> r) -> Path a b -> r

A fold over Paths. Since Path has private constructors, this allows for functions to be written over its constructors, similar to a total pattern match.

  • The first argument is the value to return for the currentDir/rootDir at the base of the path.
  • The second argument is a function for handling a step into the parent directory of the path it receives (eliminates parentOf).
  • The third argument is a function representing a file or directory within the directory of the path it receives (eliminates extendPath).

#peel

peel :: forall a b. Path a b -> Maybe (Tuple (Path a Dir) (Name b))

Peels off the last directory and the terminal file or directory name from the path. Returns Nothing if the path is rootDir / currentDir or a relative path that is ascending (../)

#peelFile

peelFile :: forall a. Path a File -> Tuple (Path a Dir) (Name File)

Peels off the last director and terminal file from a path. Unlike the general peel function this is guaranteed to return a result, as File paths are known to have a name.

#name

name :: forall a b. IsRelOrAbs a => IsDirOrFile b => Path a b -> Maybe (Name b)

Retrieves the name of the terminal segment in a path. Returns Nothing if the path is rootDir / currentDir or some parentOf p.

#fileName

fileName :: forall a. Path a File -> Name File

Retrieves the name of a file path. Unlike the general name function, this is guaranteed to return a result, as File paths are known to have a name.

#rename

rename :: forall a b. (Name b -> Name b) -> Path a b -> Path a b

Attempts to rename the terminal segment of a path. If the path is rootDir / currentDir or a relative path that is ascending (../) this will have no effect.

#renameTraverse

renameTraverse :: forall f a b. Applicative f => (Name b -> f (Name b)) -> Path a b -> f (Path a b)

Attempts to rename the terminal segment of a path using a function that returns the result in some Applicative. If the path is rootDir / currentDir or a relative path that is ascending (../) this will have no effect.

#setExtension

setExtension :: forall a b. Path a b -> String -> Path a b

Sets the extension on the terminal segment of a path. If the path is rootDir / currentDir or a relative path that is ascending (../) this will have no effect.

file "image" <.> "png"

See splitName and alterExtension fore more examples.

#(<.>)

Operator alias for Pathy.Path.setExtension (left-associative / precedence 6)

#relativeTo

relativeTo :: forall b. Path Abs b -> Path Abs Dir -> Path Rel b

Makes a path relative to a reference path. This function is best explaned using this property:

a == r </> a `relativeTo` r

#refine

refine :: forall a b. IsDirOrFile b => (Name File -> Name File) -> (Name Dir -> Name Dir) -> Path a b -> Path a b

Refines path segments but does not change anything else.

Modules