Path

Support for well-typed paths.

Types

data Path b t

Path of some base and type.

Internally is a string. The string can be of two formats only:

1. File format: file.txt, foo/bar.txt, /foo/bar.txt
2. Directory format: foo/, /foo/bar/

All directories end in a trailing separator. There are no duplicate path separators //, no .., no ./, no ~/, etc.

Instances

Eq (Path b t)

String equality.

The following property holds:

show x == show y ≡ x == y

Methods

(==) :: Path b t -> Path b t -> Bool

(/=) :: Path b t -> Path b t -> Bool

Ord (Path b t)

String ordering.

The following property holds:

show x `compare` show y ≡ x `compare` y

Methods

compare :: Path b t -> Path b t -> Ordering

(<) :: Path b t -> Path b t -> Bool

(<=) :: Path b t -> Path b t -> Bool

(>) :: Path b t -> Path b t -> Bool

(>=) :: Path b t -> Path b t -> Bool

max :: Path b t -> Path b t -> Path b t

min :: Path b t -> Path b t -> Path b t

Show (Path b t)

Same as toFilePath.

The following property holds:

x == y ≡ show x == show y

Methods

showsPrec :: Int -> Path b t -> ShowS

show :: Path b t -> String

showList :: [Path b t] -> ShowS

ToJSON (Path b t)

Methods

toJSON :: Path b t -> Value

toEncoding :: Path b t -> Encoding

FromJSON (Path Rel Dir)

Methods

parseJSON :: Value -> Parser (Path Rel Dir)

FromJSON (Path Rel File)

Methods

parseJSON :: Value -> Parser (Path Rel File)

FromJSON (Path Abs Dir)

Methods

parseJSON :: Value -> Parser (Path Abs Dir)

FromJSON (Path Abs File)

Methods

parseJSON :: Value -> Parser (Path Abs File)

NFData (Path b t)

Methods

rnf :: Path b t -> ()

data Abs

An absolute path.

Instances

FromJSON (Path Abs Dir)

Methods

parseJSON :: Value -> Parser (Path Abs Dir)

FromJSON (Path Abs File)

Methods

parseJSON :: Value -> Parser (Path Abs File)

data Rel

A relative path; one without a root.

Instances

FromJSON (Path Rel Dir)

Methods

parseJSON :: Value -> Parser (Path Rel Dir)

FromJSON (Path Rel File)

Methods

parseJSON :: Value -> Parser (Path Rel File)

data File

A file path.

Instances

FromJSON (Path Rel File)

Methods

parseJSON :: Value -> Parser (Path Rel File)

FromJSON (Path Abs File)

Methods

parseJSON :: Value -> Parser (Path Abs File)

data Dir

A directory path.

Instances

FromJSON (Path Rel Dir)

Methods

parseJSON :: Value -> Parser (Path Rel Dir)

FromJSON (Path Abs Dir)

Methods

parseJSON :: Value -> Parser (Path Abs Dir)

Parsing

parseAbsDir :: MonadThrow m => FilePath -> m (Path Abs Dir)

Get a location for an absolute directory. Produces a normalized path which always ends in a path separator.

Throws: PathParseException

parseRelDir :: MonadThrow m => FilePath -> m (Path Rel Dir)

Get a location for a relative directory. Produces a normalized path which always ends in a path separator.

Note that filepath may contain any number of ./ but may not consist solely of ./. It also may not contain a single .. anywhere.

Throws: PathParseException

parseAbsFile :: MonadThrow m => FilePath -> m (Path Abs File)

Get a location for an absolute file.

Throws: PathParseException

parseRelFile :: MonadThrow m => FilePath -> m (Path Rel File)

Get a location for a relative file.

Note that filepath may contain any number of ./ but may not contain a single .. anywhere.

Throws: PathParseException

data PathParseException

Exception when parsing a location.

Instances

Show PathParseException

Methods

showsPrec :: Int -> PathParseException -> ShowS

show :: PathParseException -> String

showList :: [PathParseException] -> ShowS

Exception PathParseException

Methods

toException :: PathParseException -> SomeException

fromException :: SomeException -> Maybe PathParseException

displayException :: PathParseException -> String

Constructors

mkAbsDir :: FilePath -> Q Exp

Make a 'Path Abs Dir'.

Remember: due to the nature of absolute paths this (e.g. /home/foo) may compile on your platform, but it may not compile on another platform (Windows).

mkRelDir :: FilePath -> Q Exp

Make a 'Path Rel Dir'.

mkAbsFile :: FilePath -> Q Exp

Make a 'Path Abs File'.

Remember: due to the nature of absolute paths this (e.g. /home/foo) may compile on your platform, but it may not compile on another platform (Windows).

mkRelFile :: FilePath -> Q Exp

Make a 'Path Rel File'.

Operations

(</>) :: Path b Dir -> Path Rel t -> Path b t

Append two paths.

The following cases are valid and the equalities hold:

$(mkAbsDir x) </> $(mkRelDir y) = $(mkAbsDir (x ++ "/" ++ y))

$(mkAbsDir x) </> $(mkRelFile y) = $(mkAbsFile (x ++ "/" ++ y))

$(mkRelDir x) </> $(mkRelDir y) = $(mkRelDir (x ++ "/" ++ y))

$(mkRelDir x) </> $(mkRelFile y) = $(mkRelFile (x ++ "/" ++ y))

The following are proven not possible to express:

$(mkAbsFile …) </> x

$(mkRelFile …) </> x

x </> $(mkAbsFile …)

x </> $(mkAbsDir …)

stripDir :: MonadThrow m => Path b Dir -> Path b t -> m (Path Rel t)

Strip directory from path, making it relative to that directory. Throws Couldn'tStripPrefixDir if directory is not a parent of the path.

The following properties hold:

stripDir x (x </> y) = y

Cases which are proven not possible:

stripDir (a :: Path Abs …) (b :: Path Rel …)

stripDir (a :: Path Rel …) (b :: Path Abs …)

In other words the bases must match.

isParentOf :: Path b Dir -> Path b t -> Bool

Is p a parent of the given location? Implemented in terms of stripDir. The bases must match.

parent :: Path Abs t -> Path Abs Dir

Take the absolute parent directory from the absolute path.

The following properties hold:

parent (x </> y) == x

On the root, getting the parent is idempotent:

parent (parent "/") = "/"

filename :: Path b File -> Path Rel File

Extract the file part of a path.

The following properties hold:

filename (p </> a) == filename a

dirname :: Path b Dir -> Path Rel Dir

Extract the last directory name of a path.

The following properties hold:

dirname (p </> a) == dirname a

Conversion

toFilePath :: Path b t -> FilePath

Convert to a FilePath type.

All directories have a trailing slash, so if you want no trailing slash, you can use dropTrailingPathSeparator from the filepath package.

fromAbsDir :: Path Abs Dir -> FilePath

Convert absolute path to directory to FilePath type.

fromRelDir :: Path Rel Dir -> FilePath

Convert relative path to directory to FilePath type.

fromAbsFile :: Path Abs File -> FilePath

Convert absolute path to file to FilePath type.

fromRelFile :: Path Rel File -> FilePath

Convert relative path to file to FilePath type.