Safe Haskell	None
Language	Haskell2010

Path

Contents

Description

Support for well-typed paths.

Synopsis

Types

data Path b t Source #

Path of some base and type.

The type variables are:

b — base, the base location of the path; absolute or relative.
t — type, whether file or directory.

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

File format: file.txt, foo/bar.txt, /foo/bar.txt
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) Source #	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) Source #	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) Source #	Same as 'show . Path.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 #
Hashable (Path b t) Source #
Methods hashWithSalt :: Int -> Path b t -> Int # hash :: Path b t -> Int #
ToJSON (Path b t) Source #
Methods toJSON :: Path b t -> Value # toEncoding :: Path b t -> Encoding # toJSONList :: [Path b t] -> Value # toEncodingList :: [Path b t] -> Encoding #
FromJSON (Path Rel Dir) #
Methods parseJSON :: Value -> Parser (Path Rel Dir) # parseJSONList :: Value -> Parser [Path Rel Dir] #
FromJSON (Path Rel File) #
Methods parseJSON :: Value -> Parser (Path Rel File) # parseJSONList :: Value -> Parser [Path Rel File] #
FromJSON (Path Abs Dir) #
Methods parseJSON :: Value -> Parser (Path Abs Dir) # parseJSONList :: Value -> Parser [Path Abs Dir] #
FromJSON (Path Abs File) #
Methods parseJSON :: Value -> Parser (Path Abs File) # parseJSONList :: Value -> Parser [Path Abs File] #
NFData (Path b t) Source #
Methods rnf :: Path b t -> () #

data Abs Source #

An absolute path.

Instances

FromJSON (Path Abs Dir) Source #
Methods parseJSON :: Value -> Parser (Path Abs Dir) # parseJSONList :: Value -> Parser [Path Abs Dir] #
FromJSON (Path Abs File) Source #
Methods parseJSON :: Value -> Parser (Path Abs File) # parseJSONList :: Value -> Parser [Path Abs File] #

data Rel Source #

A relative path; one without a root. Note that a . as well as any path starting with a .. is not a valid relative path. In other words, a relative path is always strictly under the directory tree to which it is relative.

Instances

FromJSON (Path Rel Dir) Source #
Methods parseJSON :: Value -> Parser (Path Rel Dir) # parseJSONList :: Value -> Parser [Path Rel Dir] #
FromJSON (Path Rel File) Source #
Methods parseJSON :: Value -> Parser (Path Rel File) # parseJSONList :: Value -> Parser [Path Rel File] #

data File Source #

A file path.

Instances

FromJSON (Path Rel File) Source #
Methods parseJSON :: Value -> Parser (Path Rel File) # parseJSONList :: Value -> Parser [Path Rel File] #
FromJSON (Path Abs File) Source #
Methods parseJSON :: Value -> Parser (Path Abs File) # parseJSONList :: Value -> Parser [Path Abs File] #

data Dir Source #

A directory path.

Instances

FromJSON (Path Rel Dir) Source #
Methods parseJSON :: Value -> Parser (Path Rel Dir) # parseJSONList :: Value -> Parser [Path Rel Dir] #
FromJSON (Path Abs Dir) Source #
Methods parseJSON :: Value -> Parser (Path Abs Dir) # parseJSONList :: Value -> Parser [Path Abs Dir] #

QuasiQuoters

Using the following requires the QuasiQuotes language extension.

For Windows users, the QuasiQuoters are especially beneficial because they prevent Haskell from treating \ as an escape character. This makes Windows paths easier to write.

[absfile|C:\chris\foo.txt|]

absdir :: QuasiQuoter Source #

Construct a Path Abs Dir using QuasiQuotes.

[absdir|/|] [absdir|/home/chris|]

Remember: due to the nature of absolute paths a path like [absdir|/home/chris|] may compile on your platform, but it may not compile on another platform (Windows).

Since: 0.5.13

reldir :: QuasiQuoter Source #

Construct a Path Rel Dir using QuasiQuotes.

[absdir|/home|]</>[reldir|chris|]

Since: 0.5.13

absfile :: QuasiQuoter Source #

Construct a Path Abs File using QuasiQuotes.

[absfile|/home/chris/foo.txt|]

Remember: due to the nature of absolute paths a path like [absdir|/home/chris/foo.txt|] may compile on your platform, but it may not compile on another platform (Windows).

Since: 0.5.13

relfile :: QuasiQuoter Source #

Construct a Path Rel File using QuasiQuotes.

[absdir|/home/chris|]</>[relfile|foo.txt|]

Since: 0.5.13

Operations

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

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) Source #

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 Source #

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

The following properties hold:

not (x `isParentOf` x)

x `isParentOf` (x </> y)

parent :: Path Abs t -> Path Abs Dir Source #

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 Source #

Extract the file part of a path.

The following properties hold:

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

dirname :: Path b Dir -> Path Rel Dir Source #

Extract the last directory name of a path.

The following properties hold:

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

fileExtension :: Path b File -> String Source #

Get extension from given file path.

Since: 0.5.11

setFileExtension Source #

Arguments

:: MonadThrow m
=> String	Extension to set
-> Path b File	Old file name
-> m (Path b File)	New file name with the desired extension

Replace/add extension to given file path. Throws if the resulting filename does not parse.

Since: 0.5.11

Parsing

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

Convert an absolute FilePath to a normalized absolute dir Path.

Throws: PathParseException when the supplied path:

is not an absolute path
contains a .. anywhere in the path
is not a valid path (See isValid)

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

Convert a relative FilePath to a normalized relative dir Path.

Throws: PathParseException when the supplied path:

is not a relative path
is any of "", . or ..
contains .. anywhere in the path
is not a valid path (See isValid)

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

Convert an absolute FilePath to a normalized absolute file Path.

Throws: PathParseException when the supplied path:

is not an absolute path
has a trailing path separator
contains .. anywhere in the path
ends in /.
is not a valid path (See isValid)

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

Convert a relative FilePath to a normalized relative file Path.

Throws: PathParseException when the supplied path:

is not a relative path
has a trailing path separator
is "", . or ..
contains .. anywhere in the path
is not a valid path (See isValid)

data PathParseException Source #

Exception when parsing a location.

Instances

Show PathParseException Source #
Methods showsPrec :: Int -> PathParseException -> ShowS # show :: PathParseException -> String # showList :: [PathParseException] -> ShowS #
Exception PathParseException Source #
Methods toException :: PathParseException -> SomeException # fromException :: SomeException -> Maybe PathParseException # displayException :: PathParseException -> String #

Conversion

toFilePath :: Path b t -> FilePath Source #

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 Source #

Convert absolute path to directory to FilePath type.

fromRelDir :: Path Rel Dir -> FilePath Source #

Convert relative path to directory to FilePath type.

fromAbsFile :: Path Abs File -> FilePath Source #

Convert absolute path to file to FilePath type.

fromRelFile :: Path Rel File -> FilePath Source #

Convert relative path to file to FilePath type.

TemplateHaskell constructors

These require the TemplateHaskell language extension.

mkAbsDir :: FilePath -> Q Exp Source #

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 Source #

Make a Path Rel Dir.

mkAbsFile :: FilePath -> Q Exp Source #

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 Source #

Make a Path Rel File.