Copyright	(c) Boris Buliga, 2014
License	MIT
Maintainer	d12frosted@icloud.com
Stability	stable
Portability	portable
Safe Haskell	None
Language	Haskell2010

Filesystem.CanonicalPath

Contents

Abstract Type
Constructors
Some IO functions
Conversion functions

Description

Prelude.FilePath is just synonym for String, so actually it can be anything - your mothers name or path to file you want to edit. Just look at type signature of function readFile :: FilePath -> IO String which can be converted to readFile :: String -> IO String. You can't be sure that it wont break your program in runtime.

OK, you can use FilePath data type from Filesystem.Path module instead of Prelude.FilePath. I really like this data type but it has the same problem as Prelude.FilePath - you can't be sure, that it holds actual path to some file or directory on your system.

So here comes abstract type CanonicalPath. It solves main problem - CanonicalPath points to existing file or directory. Well, to be honest, 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) - hopefully you can always check if CanonicalPath is not broken (using composition of any constructor and unsafePath). But in most cases CanonicalPath will help you avoid many problems and will make your routine less routine.

Oh, and last but not least, CanonicalPath constructor extracts all environment variables. Also it treats ~ as home directory.

Happy Haskell Hacking!

Synopsis

Abstract Type

data CanonicalPath Source

Instances

Show CanonicalPath

type UnsafePath = FilePath Source

Synonym of FilePath from Filesystem.Path module.

Since 0.1.0.0

Constructors

canonicalPath :: MonadIO m => UnsafePath -> m CanonicalPath Source

Unsafe constructor of CanonicalPath. In case of any problem 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 Source

Version of canonicalPath that takes Text instead of UnsafePath.

Since 0.2.1.0

canonicalPathM :: MonadIO m => UnsafePath -> m (Maybe CanonicalPath) Source

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

Version of canonicalPathM that takes Text instead of UnsafePath.

Since 0.2.1.0

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

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

Version of canonicalPathE that takes Text instead of UnsafePath.

Since 0.2.1.0

unsafePath :: CanonicalPath -> UnsafePath Source

Convert CanonicalPath to Filesystem.FilePath.

Since 0.1.0.0

Some IO functions

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

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

writeFile file txt writes txt to the file.

Since 0.1.1.0

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

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

appendFile file txt appends txt to the file.

Since 0.1.1.0