Filesystem.CanonicalPath

FilePath is very deceptive, because it's just a synonym for String, so actually it can be anything - your mothers name or path to file you want to edit. Just look at the type signature of function readFile:

readFile :: FilePath -> IO String

You can translate it as follows:

readFile :: String -> IO String

Well, it is known that IO actions are dangerous by themselves. And here comes another problem - you need to be sure that the path you pass to function is at least well constructed. For this purpose you can use well known FilePath data type. It solves a lot of problems and comes beefed with multiple cool utilities. And also it is build around Text instead of String. Awesome!

So why do we need yet another path library? The answer is simple - we want to use paths like $HOME/.app.cfg, ~/.zshrc or /full/path/to/existing/file/or/dir in our code without any additional overhead. CanonicalPath is named so because it tries to canonicalize given path (FilePath or Text) using canonicalizePath function. It also will extract any variables it finds in path (like $VARNAME, %VARNAME% and special ~/). But these steps both may fail. Thats why this library provides functions that return Maybe CanonicalPath or Either Text CanonicalPath.

CanonicalPath also comes with additional useful property. When it is created, it points to real file or directory. Honestly, it can't guarantee that this path will refer to existing file or directory always (someone can remove or move it to another path - and it's almost impossible to be aware of such cruelty), but you can always reconstruct CanonicalPath.

One more thing about path canonicalization. As I mentioned before, under the hood it uses canonicalizePath function. So here are two warnings. Firstly, it behaves differently on different platforms. Sometime too damn differently. So you better watch your steps. Secodly, it's impossible to guarantee that the implication same file/dir <=> same canonicalizedPath holds in either direction: this function can make only a best-effort attempt.

Happy Haskell Hacking!

Abstract Type

data CanonicalPath

Instances

Eq CanonicalPath

Show CanonicalPath

Constructors

canonicalPath :: MonadIO m => FilePath -> m CanonicalPath

Unsafe constructor of CanonicalPath. In case of any problems it will error.

Example:

>>> canonicalPath "$HOME"
CanonicalPath "/Users/your-user-name"

>>> canonicalPath "unknown"
*** Exception: Path does not exist (no such file or directory): unknown

Since 0.1.0.0

canonicalPath' :: MonadIO m => Text -> m CanonicalPath

Version of canonicalPath that takes Text instead of FilePath.

Since 0.2.1.0

canonicalPathM :: MonadIO m => FilePath -> m (Maybe CanonicalPath)

Constructs Maybe CanonicalPath.

>>> canonicalPathM "~"
Just CanonicalPath "Users/your-user-name"

>>> canonicalPathM "unknown"
Nothing

Since 0.1.0.0

canonicalPathM' :: MonadIO m => Text -> m (Maybe CanonicalPath)

Version of canonicalPathM that takes Text instead of FilePath.

Since 0.2.1.0

canonicalPathE :: MonadIO m => FilePath -> m (Either Text CanonicalPath)

Constructs Either Text CanonicalPath.

>>> canonicalPathE "~/"
Right CanonicalPath "/Users/your-user-name"

>>> canonicalPathE "$HOME/this-folder-does-not-exist"
Left "Path does not exist (no such file or directory): /Users/your-user-name/this-folder-does-not-exist"

Since 0.1.0.0

canonicalPathE' :: MonadIO m => Text -> m (Either Text CanonicalPath)

Version of canonicalPathE that takes Text instead of FilePath.

Since 0.2.1.0

unsafePath :: CanonicalPath -> FilePath

Convert CanonicalPath to Filesystem.FilePath.

Since 0.1.0.0

Some IO functions

readFile :: MonadIO m => CanonicalPath -> m Text

readFile file function reads a file and returns the contents of the file as a Text. The file is read lazily, on demand, as with getContents.

Since 0.1.1.0

writeFile :: MonadIO m => CanonicalPath -> Text -> m ()

writeFile file txt writes txt to the file.

Since 0.1.1.0

writeFile' :: MonadIO m => CanonicalPath -> FilePath -> Text -> m ()

writeFile' dir file txt writes txt to the dir/file. Useful, when the file isn't created yet or you don't sure if it exists.

Since 0.1.2.0

appendFile :: MonadIO m => CanonicalPath -> Text -> m ()

appendFile file txt appends txt to the file.

Since 0.1.1.0

Conversion functions

fromText :: Text -> FilePath

Convert human‐readable text into a FilePath.

This function ignores the user’s locale, and assumes all file paths are encoded in UTF8. If you need to create file paths with an unusual or obscure encoding, encode them manually and then use decode.

Since: 0.2

toText :: FilePath -> Either Text Text

Attempt to convert a FilePath to human‐readable text.

If the path is decoded successfully, the result is a Right containing the decoded text. Successfully decoded text can be converted back to the original path using fromText.

If the path cannot be decoded, the result is a Left containing an approximation of the original path. If displayed to the user, this value should be accompanied by some warning that the path has an invalid encoding. Approximated text cannot be converted back to the original path.

This function ignores the user’s locale, and assumes all file paths are encoded in UTF8. If you need to display file paths with an unusual or obscure encoding, use encode and then decode them manually.

Since: 0.2

toText' :: CanonicalPath -> Text

toText' path converts CanonicalPath to Text.

Since 0.3.0.0

fromPrelude :: FilePath -> FilePath

fromPrelude fp converts FilePath to toText.

Since 0.1.0.0

toPrelude :: FilePath -> FilePath

toPrelude up converts FilePath to FilePath.

Since 0.1.0.0