| Copyright | © 2015–2016 FP Complete |
|---|---|
| License | BSD 3 clause |
| Maintainer | Chris Done <chrisdone@fpcomplete.com> |
| Stability | experimental |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell98 |
Path
Description
Support for well-typed paths.
- data Path b t
- data Abs
- data Rel
- data File
- data Dir
- 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
- mkAbsDir :: FilePath -> Q Exp
- mkRelDir :: FilePath -> Q Exp
- mkAbsFile :: FilePath -> Q Exp
- mkRelFile :: FilePath -> Q Exp
- (</>) :: 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)
- 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
Types
Path of some base and type.
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 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.
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)
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).
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).
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
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.