System.Path

A more type-safe version of file paths

This module provides the basic Path abstraction. See also System.Path.IO which extends this module by thin wrappers wrappers around common IO operations.

Paths

data Path a

Paths

A Path is a wrapped FilePath with a type-level tag indicating where this path is rooted (relative to the current directory, absolute path, relative to a web domain, whatever). Most operations on Path are just lifted versions of the operations on the underlying FilePath. The tag however allows us to give a lot of operations a more meaningful type. For instance, it does not make sense to append two absolute paths together; instead, we can only append an unrooted path to another path. It also means we avoid bugs where we use one kind of path where we expect another.

Instances

Eq (Path a)

Methods

(==) :: Path a -> Path a -> Bool

(/=) :: Path a -> Path a -> Bool

Ord (Path a)

Methods

compare :: Path a -> Path a -> Ordering

(<) :: Path a -> Path a -> Bool

(<=) :: Path a -> Path a -> Bool

(>) :: Path a -> Path a -> Bool

(>=) :: Path a -> Path a -> Bool

max :: Path a -> Path a -> Path a

min :: Path a -> Path a -> Path a

Show (Path a)

Methods

showsPrec :: Int -> Path a -> ShowS

show :: Path a -> String

showList :: [Path a] -> ShowS

NFData (Path a)

Methods

rnf :: Path a -> ()

FilePath-like operations on paths with arbitrary roots

takeDirectory :: Path a -> Path a

Wrapped takeDirectory

takeFileName :: Path a -> Path Unrooted

Wrapped takeFileName

Operations aware of file-extensions

newtype FileExt

Type to represent filepath extensions.

File extensions are usually a high-level convention and in most cases the low-level filesystem layer is agnostic to them.

Since: 0.2.0.0

Constructors

FileExt String

Instances

Eq FileExt

Methods

(==) :: FileExt -> FileExt -> Bool

(/=) :: FileExt -> FileExt -> Bool

Ord FileExt

Methods

compare :: FileExt -> FileExt -> Ordering

(<) :: FileExt -> FileExt -> Bool

(<=) :: FileExt -> FileExt -> Bool

(>) :: FileExt -> FileExt -> Bool

(>=) :: FileExt -> FileExt -> Bool

max :: FileExt -> FileExt -> FileExt

min :: FileExt -> FileExt -> FileExt

Show FileExt

Methods

showsPrec :: Int -> FileExt -> ShowS

show :: FileExt -> String

showList :: [FileExt] -> ShowS

(<.>) :: Path a -> FileExt -> Path a infixr 7

Wrapped <.>

(-<.>) :: Path a -> FileExt -> Path a infixr 7

Wrapped -<.>

Since: 0.2.0.0

splitExtension :: Path a -> (Path a, Maybe FileExt)

Wrapped splitExtension

splitExtensions :: Path a -> (Path a, Maybe FileExt)

Wrapped splitExtensions

Since: 0.2.0.0

takeExtension :: Path a -> Maybe FileExt

Wrapped takeExtension

takeExtensions :: Path a -> Maybe FileExt

Wrapped takeExtensions

Since: 0.2.0.0

takeBaseName :: Path a -> Path Unrooted

Wrapped takeBaseName

Since: 0.2.0.0

stripExtension :: FileExt -> Path a -> Maybe (Path a)

Wrapped stripExtension

Since: 0.2.0.0

isExtensionOf :: FileExt -> Path a -> Bool

Wrapped isExtensionOf

Since: 0.2.0.0

Trailing slash functions

hasTrailingPathSeparator :: Path a -> Bool

Wrapped hasTrailingPathSeparator

Since: 0.2.0.0

addTrailingPathSeparator :: Path a -> Path a

Wrapped addTrailingPathSeparator

Since: 0.2.0.0

dropTrailingPathSeparator :: Path a -> Path a

Wrapped dropTrailingPathSeparator

Since: 0.2.0.0

Unrooted paths

data Unrooted

Type-level tag for unrooted paths

Unrooted paths need a root before they can be interpreted.

(</>) :: Path a -> Path Unrooted -> Path a infixr 5

Wrapped </>

The empty fragment fragment "" acts as the right-identity

root / fragment "" == root

This is the inverse to splitFileName.

unrootPath :: Path root -> Path Unrooted

Forget a path's root

NOTE: If the original Path is considered an absolute POSIX style FilePath, it's automatically converted to a relative FilePath.

toUnrootedFilePath :: Path Unrooted -> FilePath

Convert a relative/unrooted Path to a FilePath (using POSIX style directory separators).

See also toAbsoluteFilePath

fromUnrootedFilePath :: FilePath -> Path Unrooted

Convert from a relative/unrooted FilePath (using POSIX style directory separators).

NOTE: If the argument is considered an absolute POSIX style FilePath, it's automatically converted to a relative FilePath.

fragment :: String -> Path Unrooted

A path fragment (like a single directory or filename)

NOTE: If the argument would be considered an absolute POSIX style FilePath, it's automatically converted to a relative FilePath.

fragments :: [String] -> Path Unrooted

Version of fragment taking a list of fragments

NOTE: If any argument would be considered an absolute POSIX style FilePath, it's automatically converted to a relative FilePath.

Since: 0.2.0.0

joinFragments :: [Path Unrooted] -> Path Unrooted

Wrapped joinPath

Since: 0.2.0.0

splitFragments :: Path Unrooted -> [Path Unrooted]

Wrapped splitDirectories

Since: 0.2.0.0

normalise :: Path a -> Path a

Normalise Path according to POSIX rules.

See documentation of normalise for details.

Since: 0.2.0.0

File-system paths

class FsRoot root where

A file system root can be interpreted as an (absolute) FilePath

Minimal complete definition

toAbsoluteFilePath

Methods

toAbsoluteFilePath :: Path root -> IO FilePath

Convert a Path to an absolute native FilePath (using native style directory separators).

This operation needs to be in IO for resolving paths with dynamic roots, such as CWD or HomeDir.

See also makeAbsolute

Instances

FsRoot HomeDir

Methods

toAbsoluteFilePath :: Path HomeDir -> IO FilePath

FsRoot Absolute

Methods

toAbsoluteFilePath :: Path Absolute -> IO FilePath

FsRoot CWD

Methods

toAbsoluteFilePath :: Path CWD -> IO FilePath

data FsPath

Abstract over a file system root

FsPath can be constructed directly or via fromFilePath or fspath.

Constructors

FsRoot root => FsPath (Path root)

Instances

NFData FsPath

Methods

rnf :: FsPath -> ()

data CWD

Path tag for paths rooted at the current working directory

Since: 0.2.0.0

Instances

FsRoot CWD

Methods

toAbsoluteFilePath :: Path CWD -> IO FilePath

type Relative = CWD

Deprecated: Please use CWD instead

Compatibility type-synonym

data Absolute

Path tag for absolute paths

Instances

FsRoot Absolute

Methods

toAbsoluteFilePath :: Path Absolute -> IO FilePath

data HomeDir

Path tag for paths rooted at $HOME

Instances

FsRoot HomeDir

Methods

toAbsoluteFilePath :: Path HomeDir -> IO FilePath

Conversions

toFilePath :: Path Absolute -> FilePath

Export absolute path to a native FilePath.

This is the inverse to fromAbsoluteFilePath.

fromFilePath :: FilePath -> FsPath

Construct a FsPath from a native FilePath.

NOTE: Native FilePaths whose first path component is a ~ (and not preceded by anything else) are interpreted to be relative to $HOME (even on non-POSIX systems).

makeAbsolute :: FsPath -> IO (Path Absolute)

Export filesystem path to an absolute Path

See also toAbsoluteFilePath

fromAbsoluteFilePath :: FilePath -> Path Absolute

Construct Absolute path from a native FilePath.

This is the inverse to toFilePath.

NOTE: If the argument is not an absolute path this function will throw an error.