Filesystem.CanonicalPath

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!

Abstract Type

data CanonicalPath

Instances

Show CanonicalPath

type UnsafePath = FilePath

Synonym of FilePath from Filesystem.Path module.

Since 0.1.0.0

Constructors

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

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

Version of canonicalPath that takes Text instead of UnsafePath.

Since 0.2.1.0

canonicalPathM :: MonadIO m => UnsafePath -> 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 UnsafePath.

Since 0.2.1.0

canonicalPathE :: MonadIO m => UnsafePath -> 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 UnsafePath.

Since 0.2.1.0

unsafePath :: CanonicalPath -> UnsafePath

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 -> UnsafePath -> 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

pathToText :: UnsafePath -> Text

pathToText path converts UnsafePath path to Text. In case of eny problems it will throw error.

See toText function for details.

Since 0.1.2.0

textToPath :: Text -> UnsafePath

textToPath txt converts Text to UnsafePath.

Since 0.1.2.0

cpathToText :: CanonicalPath -> Text

cpathToText path converts CanonicalPath to Text.

Since 0.2.3.0