Safe Haskell | None |
---|---|
Language | Haskell2010 |
Path
Description
Support for well-typed paths.
- data Path b t
- data Abs
- data Rel
- data File
- data Dir
- absdir :: QuasiQuoter
- reldir :: QuasiQuoter
- absfile :: QuasiQuoter
- relfile :: QuasiQuoter
- (</>) :: Path b Dir -> Path Rel t -> Path b t
- stripDir :: MonadThrow m => Path b Dir -> Path b t -> m (Path Rel t)
- isParentOf :: Path b Dir -> Path b t -> Bool
- parent :: Path Abs t -> Path Abs Dir
- filename :: Path b File -> Path Rel File
- dirname :: Path b Dir -> Path Rel Dir
- fileExtension :: Path b File -> String
- setFileExtension :: MonadThrow m => String -> Path b File -> m (Path b File)
- parseAbsDir :: MonadThrow m => FilePath -> m (Path Abs Dir)
- parseRelDir :: MonadThrow m => FilePath -> m (Path Rel Dir)
- parseAbsFile :: MonadThrow m => FilePath -> m (Path Abs File)
- parseRelFile :: MonadThrow m => FilePath -> m (Path Rel File)
- data PathParseException
- toFilePath :: Path b t -> FilePath
- fromAbsDir :: Path Abs Dir -> FilePath
- fromRelDir :: Path Rel Dir -> FilePath
- fromAbsFile :: Path Abs File -> FilePath
- fromRelFile :: Path Rel File -> FilePath
- mkAbsDir :: FilePath -> Q Exp
- mkRelDir :: FilePath -> Q Exp
- mkAbsFile :: FilePath -> Q Exp
- mkRelFile :: FilePath -> Q Exp
Types
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) # | String equality. The following property holds: show x == show y ≡ x == y |
Ord (Path b t) # | String ordering. The following property holds: show x `compare` show y ≡ x `compare` y |
Show (Path b t) # | Same as 'show . Path.toFilePath'. The following property holds: x == y ≡ show x == show y |
Hashable (Path b t) # | |
FromJSON (Path Rel Dir) # | |
FromJSON (Path Rel File) # | |
FromJSON (Path Abs Dir) # | |
FromJSON (Path Abs File) # | |
ToJSON (Path b t) # | |
NFData (Path b t) # | |
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.
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 #
reldir :: QuasiQuoter #
absfile :: QuasiQuoter #
relfile :: QuasiQuoter #
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.
The following properties hold:
not (x `isParentOf` x)
x `isParentOf` (x </> y)
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
fileExtension :: Path b File -> String #
Get extension from given file path.
Since: 0.5.11
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) #
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) #
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) #
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) #
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
)
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.
TemplateHaskell constructors
These require the TemplateHaskell language extension.