Release 0.7.1

This also matches the documentation order from the
filepath package more.

CHANGELOG

@@ -1,3 +1,14 @@
+0.7.1:
+	* various cleanups and documentation improvements
+	* added the following functions to System.Posix.FilePath: splitSearchPath, getSearchPath, stripExtension, makeRelative, makeValid
+0.7.0:
+	* use 'sendfile' from 'simple-sendfile' in _copyFile and do read/write as a fallback only
+	* add isFileName, hasParentDir, hiddenFile to System.Posix.FilePath
+	* add our own openFd version for more control
+	* small documentation improvements
+	* add a getDirectoryContents' version that works on Fd
+	* lift version constraints in benchmark
+	* remove fpToString and userStringToFP, use Data.ByteString.UTF8 directly instead
 0.6.0:
 	* fixes 'throwDestinationInSource' to be more reliable.
 	* removes some unused HPathIOException constructors

README.md

@@ -1,6 +1,6 @@
 # HPath
 
-[![Build Status](https://api.travis-ci.org/hasufell/hpath.png?branch=master)](http://travis-ci.org/hasufell/hpath)
+[![Gitter chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/hasufell/hpath?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Hackage version](https://img.shields.io/hackage/v/hpath.svg?label=Hackage)](https://hackage.haskell.org/package/hpath) [![Build Status](https://api.travis-ci.org/hasufell/hpath.png?branch=master)](http://travis-ci.org/hasufell/hpath)
 
 Support for well-typed paths in Haskell. Also provides ByteString based filepath
 manipulation.
@@ -43,9 +43,20 @@ so it is forked as well and merged into this library.
 
 ## Differences to 'posix-paths'
 
-* `hasTrailingPathSeparator` behaves in the same way as `System.FilePath`
-* `dropTrailingPathSeparator` behaves in the same way as `System.FilePath`
-* added various functions like `isValid`, `normalise` and `equalFilePath`
 * uses the `word8` package for save word8 literals instead of `OverloadedStrings`
-* has custom versions of `openFd` and `getDirectoryContents`
+* `hasTrailingPathSeparator` and `dropTrailingPathSeparator` behave in the same way as their `System.FilePath` counterpart
+* added various functions:
+    * `equalFilePath`
+    * `getSearchPath`
+    * `hasParentDir`
+    * `hiddenFile`
+    * `isFileName`
+    * `isValid`
+    * `makeRelative`
+    * `makeValid`
+    * `normalise`
+    * `splitSearchPath`
+    * `stripExtension`
+* has a custom versions of `openFd` which allows more control over the flags than its unix package counterpart
+* adds a `getDirectoryContents'` version that works on Fd
 

hpath.cabal

@@ -1,5 +1,5 @@
 name:                hpath
-version:             0.6.0
+version:             0.7.1
 synopsis:            Support for well-typed paths
 description:         Support for well-typed paths, utilizing ByteString under the hood.
 license:             GPL-2
@@ -29,12 +29,14 @@ library
                      HPath.Internal,
                      System.Posix.Directory.Foreign,
                      System.Posix.Directory.Traversals,
+                     System.Posix.FD,
                      System.Posix.FilePath
   build-depends:     base >= 4.2 && <5
                    , bytestring >= 0.9.2.0
                    , deepseq
                    , exceptions
                    , hspec
+                   , simple-sendfile >= 0.2.24
                    , unix >= 2.5
                    , unix-bytestring
                    , utf8-string
@@ -110,9 +112,9 @@ benchmark bench.hs
       bytestring,
       unix,
       directory  >= 1.1 && < 1.3,
-      filepath   >= 1.2 && < 1.4,
+      filepath   >= 1.2 && < 1.5,
       process    >= 1.0 && < 1.3,
-      criterion  >= 0.6 && < 0.9
+      criterion  >= 0.6 && < 1.2
   ghc-options: -O2
 
 source-repository head

src/HPath.hs

@@ -45,9 +45,6 @@ module HPath
   ,withAbsPath
   ,withRelPath
   ,withFnPath
-  -- * ByteString operations
-  ,fpToString
-  ,userStringToFP
   )
   where
 
@@ -57,10 +54,10 @@ import           Control.Monad.Catch (MonadThrow(..))
 import           Data.ByteString(ByteString, stripPrefix)
 #else
 import           Data.ByteString(ByteString)
+import qualified Data.List as L
 #endif
 import qualified Data.ByteString as BS
 import           Data.Data
-import qualified Data.List as L
 import           Data.Maybe
 import           Data.Word8
 import           HPath.Internal
@@ -109,19 +106,19 @@ pattern Path x <- (MkPath x)
 --
 -- Throws: 'PathParseException'
 --
--- >>> parseAbs "/abc" :: Maybe (Path Abs)
+-- >>> parseAbs "/abc"          :: Maybe (Path Abs)
 -- Just "/abc"
--- >>> parseAbs "/" :: Maybe (Path Abs)
+-- >>> parseAbs "/"             :: Maybe (Path Abs)
 -- Just "/"
--- >>> parseAbs "/abc/def" :: Maybe (Path Abs)
+-- >>> parseAbs "/abc/def"      :: Maybe (Path Abs)
 -- Just "/abc/def"
 -- >>> parseAbs "/abc/def/.///" :: Maybe (Path Abs)
 -- Just "/abc/def/"
--- >>> parseAbs "abc" :: Maybe (Path Abs)
+-- >>> parseAbs "abc"           :: Maybe (Path Abs)
 -- Nothing
--- >>> parseAbs "" :: Maybe (Path Abs)
+-- >>> parseAbs ""              :: Maybe (Path Abs)
 -- Nothing
--- >>> parseAbs "/abc/../foo" :: Maybe (Path Abs)
+-- >>> parseAbs "/abc/../foo"   :: Maybe (Path Abs)
 -- Nothing
 parseAbs :: MonadThrow m
          => ByteString -> m (Path Abs)
@@ -141,23 +138,23 @@ parseAbs filepath =
 --
 -- Throws: 'PathParseException'
 --
--- >>> parseRel "abc" :: Maybe (Path Rel)
+-- >>> parseRel "abc"        :: Maybe (Path Rel)
 -- Just "abc"
--- >>> parseRel "def/" :: Maybe (Path Rel)
+-- >>> parseRel "def/"       :: Maybe (Path Rel)
 -- Just "def/"
--- >>> parseRel "abc/def" :: Maybe (Path Rel)
+-- >>> parseRel "abc/def"    :: Maybe (Path Rel)
 -- Just "abc/def"
--- >>> parseRel "abc/def/." :: Maybe (Path Rel)
+-- >>> parseRel "abc/def/."  :: Maybe (Path Rel)
 -- Just "abc/def/"
--- >>> parseRel "/abc" :: Maybe (Path Rel)
+-- >>> parseRel "/abc"       :: Maybe (Path Rel)
 -- Nothing
--- >>> parseRel "" :: Maybe (Path Rel)
+-- >>> parseRel ""           :: Maybe (Path Rel)
 -- Nothing
 -- >>> parseRel "abc/../foo" :: Maybe (Path Rel)
 -- Nothing
--- >>> parseRel "." :: Maybe (Path Rel)
+-- >>> parseRel "."          :: Maybe (Path Rel)
 -- Nothing
--- >>> parseRel ".." :: Maybe (Path Rel)
+-- >>> parseRel ".."         :: Maybe (Path Rel)
 -- Nothing
 parseRel :: MonadThrow m
          => ByteString -> m (Path Rel)
@@ -176,25 +173,25 @@ parseRel filepath =
 --
 -- Throws: 'PathParseException'
 --
--- >>> parseFn "abc" :: Maybe (Path Fn)
+-- >>> parseFn "abc"        :: Maybe (Path Fn)
 -- Just "abc"
--- >>> parseFn "..." :: Maybe (Path Fn)
+-- >>> parseFn "..."        :: Maybe (Path Fn)
 -- Just "..."
--- >>> parseFn "def/" :: Maybe (Path Fn)
+-- >>> parseFn "def/"       :: Maybe (Path Fn)
 -- Nothing
--- >>> parseFn "abc/def" :: Maybe (Path Fn)
+-- >>> parseFn "abc/def"    :: Maybe (Path Fn)
 -- Nothing
--- >>> parseFn "abc/def/." :: Maybe (Path Fn)
+-- >>> parseFn "abc/def/."  :: Maybe (Path Fn)
 -- Nothing
--- >>> parseFn "/abc" :: Maybe (Path Fn)
+-- >>> parseFn "/abc"       :: Maybe (Path Fn)
 -- Nothing
--- >>> parseFn "" :: Maybe (Path Fn)
+-- >>> parseFn ""           :: Maybe (Path Fn)
 -- Nothing
 -- >>> parseFn "abc/../foo" :: Maybe (Path Fn)
 -- Nothing
--- >>> parseFn "." :: Maybe (Path Fn)
+-- >>> parseFn "."          :: Maybe (Path Fn)
 -- Nothing
--- >>> parseFn ".." :: Maybe (Path Fn)
+-- >>> parseFn ".."         :: Maybe (Path Fn)
 -- Nothing
 parseFn :: MonadThrow m
         => ByteString -> m (Path Fn)
@@ -237,13 +234,13 @@ fromRel = toFilePath
 -- because this library is IO-agnostic and makes no assumptions about
 -- file types.
 --
--- >>> (MkPath "/") </> (MkPath "file" :: Path Rel)
+-- >>> (MkPath "/")        </> (MkPath "file"     :: Path Rel)
 -- "/file"
--- >>> (MkPath "/path/to") </> (MkPath "file" :: Path Rel)
+-- >>> (MkPath "/path/to") </> (MkPath "file"     :: Path Rel)
 -- "/path/to/file"
--- >>> (MkPath "/") </> (MkPath "file/lal" :: Path Rel)
+-- >>> (MkPath "/")        </> (MkPath "file/lal" :: Path Rel)
 -- "/file/lal"
--- >>> (MkPath "/") </> (MkPath "file/" :: Path Rel)
+-- >>> (MkPath "/")        </> (MkPath "file/"    :: Path Rel)
 -- "/file/"
 (</>) :: RelC r => Path b -> Path r -> Path b
 (</>) (MkPath a) (MkPath b) = MkPath (a' `BS.append` b)
@@ -257,15 +254,15 @@ fromRel = toFilePath
 --
 -- The bases must match.
 --
--- >>> (MkPath "/lal/lad") `stripDir` (MkPath "/lal/lad/fad") :: Maybe (Path Rel)
+-- >>> (MkPath "/lal/lad")     `stripDir` (MkPath "/lal/lad/fad") :: Maybe (Path Rel)
 -- Just "fad"
--- >>> (MkPath "lal/lad") `stripDir` (MkPath "lal/lad/fad") :: Maybe (Path Rel)
+-- >>> (MkPath "lal/lad")      `stripDir` (MkPath "lal/lad/fad")  :: Maybe (Path Rel)
 -- Just "fad"
--- >>> (MkPath "/") `stripDir` (MkPath "/") :: Maybe (Path Rel)
+-- >>> (MkPath "/")            `stripDir` (MkPath "/")            :: Maybe (Path Rel)
 -- Nothing
--- >>> (MkPath "/lal/lad/fad") `stripDir` (MkPath "/lal/lad") :: Maybe (Path Rel)
+-- >>> (MkPath "/lal/lad/fad") `stripDir` (MkPath "/lal/lad")     :: Maybe (Path Rel)
 -- Nothing
--- >>> (MkPath "fad") `stripDir` (MkPath "fad") :: Maybe (Path Rel)
+-- >>> (MkPath "fad")          `stripDir` (MkPath "fad")          :: Maybe (Path Rel)
 -- Nothing
 stripDir :: MonadThrow m
          => Path b -> Path b -> m (Path Rel)
@@ -281,15 +278,15 @@ stripDir (MkPath p) (MkPath l) =
 -- | Is p a parent of the given location? Implemented in terms of
 -- 'stripDir'. The bases must match.
 --
--- >>> (MkPath "/lal/lad") `isParentOf` (MkPath "/lal/lad/fad")
+-- >>> (MkPath "/lal/lad")     `isParentOf` (MkPath "/lal/lad/fad")
 -- True
--- >>> (MkPath "lal/lad") `isParentOf` (MkPath "lal/lad/fad")
+-- >>> (MkPath "lal/lad")      `isParentOf` (MkPath "lal/lad/fad")
 -- True
--- >>> (MkPath "/") `isParentOf` (MkPath "/")
+-- >>> (MkPath "/")            `isParentOf` (MkPath "/")
 -- False
 -- >>> (MkPath "/lal/lad/fad") `isParentOf` (MkPath "/lal/lad")
 -- False
--- >>> (MkPath "fad") `isParentOf` (MkPath "fad")
+-- >>> (MkPath "fad")          `isParentOf` (MkPath "fad")
 -- False
 isParentOf :: Path b -> Path b -> Bool
 isParentOf p l = isJust (stripDir p l :: Maybe (Path Rel))
@@ -333,7 +330,7 @@ dirname (MkPath fp) = MkPath (takeDirectory $ dropTrailingPathSeparator fp)
 --
 -- >>> basename (MkPath "/abc/def/dod") :: Maybe (Path Fn)
 -- Just "dod"
--- >>> basename (MkPath "/") :: Maybe (Path Fn)
+-- >>> basename (MkPath "/")            :: Maybe (Path Fn)
 -- Nothing
 basename :: MonadThrow m => Path b -> m (Path Fn)
 basename (MkPath l)

src/HPath/IO.hs

@@ -80,7 +80,6 @@ import Control.Applicative
 import Control.Exception
   (
     bracket
-  , bracketOnError
   , throwIO
   )
 import Control.Monad
@@ -107,6 +106,8 @@ import Data.Word
 import Foreign.C.Error
   (
     eEXIST
+  , eINVAL
+  , eNOSYS
   , eNOTEMPTY
   , eXDEV
   )
@@ -136,6 +137,11 @@ import System.IO.Error
     catchIOError
   , ioeGetErrorType
   )
+import System.Linux.Sendfile
+  (
+    sendfileFd
+  , FileRange(..)
+  )
 import System.Posix.ByteString
   (
     exclusive
@@ -172,6 +178,10 @@ import System.Posix.Files.ByteString
 import qualified System.Posix.Files.ByteString as PF
 import qualified "unix" System.Posix.IO.ByteString as SPI
 import qualified "unix-bytestring" System.Posix.IO.ByteString as SPB
+import System.Posix.FD
+  (
+    openFd
+  )
 import qualified System.Posix.Directory.Traversals as SPDT
 import qualified System.Posix.Directory.Foreign as SPDF
 import qualified System.Posix.Process.ByteString as SPP
@@ -229,8 +239,8 @@ data FileType = Directory
 --    - `PermissionDenied` if source directory can't be opened
 --    - `InvalidArgument` if source directory is wrong type (symlink)
 --    - `InvalidArgument` if source directory is wrong type (regular file)
---    - `SameFile` if source and destination are the same file (`HPathIOException`)
 --    - `AlreadyExists` if destination already exists
+--    - `SameFile` if source and destination are the same file (`HPathIOException`)
 --    - `DestinationInSource` if destination is contained in source (`HPathIOException`)
 copyDirRecursive :: Path Abs  -- ^ source dir
                  -> Path Abs  -- ^ full destination
@@ -338,10 +348,10 @@ recreateSymlink symsource newsym
 --    - `PermissionDenied` if source directory can't be opened
 --    - `InvalidArgument` if source file is wrong type (symlink)
 --    - `InvalidArgument` if source file is wrong type (directory)
---    - `SameFile` if source and destination are the same file (`HPathIOException`)
 --    - `AlreadyExists` if destination already exists
+--    - `SameFile` if source and destination are the same file (`HPathIOException`)
 --
--- Note: calls `sendfile`
+-- Note: calls `sendfile` and possibly `read`/`write` as fallback
 copyFile :: Path Abs  -- ^ source file
          -> Path Abs  -- ^ destination file
          -> IO ()
@@ -358,8 +368,7 @@ copyFile from to = do
 --
 -- Safety/reliability concerns:
 --
---    * not atomic
+--    * not atomic, since it uses read/write
---    * falls back to delete-copy method with explicit checks
 --
 -- Throws:
 --
@@ -370,7 +379,7 @@ copyFile from to = do
 --    - `InvalidArgument` if source file is wrong type (directory)
 --    - `SameFile` if source and destination are the same file (`HPathIOException`)
 --
--- Note: calls `sendfile`
+-- Note: calls `sendfile` and possibly `read`/`write` as fallback
 copyFileOverwrite :: Path Abs  -- ^ source file
                   -> Path Abs  -- ^ destination file
                   -> IO ()
@@ -398,24 +407,35 @@ _copyFile :: [SPDF.Flags]
           -> IO ()
 _copyFile sflags dflags from to
   =
-  -- TODO: add sendfile support
+    -- from sendfile(2) manpage:
-  void $ readWriteCopy (fromAbs from) (fromAbs to)
+    --   Applications  may  wish  to  fall back to read(2)/write(2) in the case
+    --   where sendfile() fails with EINVAL or ENOSYS.
+    withAbsPath to $ \to' -> withAbsPath from $ \from' ->
+      catchErrno [eINVAL, eNOSYS]
+                 (sendFileCopy from' to')
+                 (void $ readWriteCopy from' to')
   where
-    -- low-level copy operation utilizing read(2)/write(2)
+    copyWith copyAction source dest =
-    -- in case `sendFileCopy` fails/is unsupported
+      bracket (openFd source SPI.ReadOnly sflags Nothing)
-    readWriteCopy :: ByteString -> ByteString -> IO Int
-    readWriteCopy source dest =
-      bracket (SPDT.openFd source SPI.ReadOnly sflags Nothing)
               SPI.closeFd
               $ \sfd -> do
                 fileM <- System.Posix.Files.ByteString.fileMode
                          <$> getFdStatus sfd
-                bracketeer (SPDT.openFd dest SPI.WriteOnly
+                bracketeer (openFd dest SPI.WriteOnly
                              dflags $ Just fileM)
                            SPI.closeFd
                            (\fd -> SPI.closeFd fd >> deleteFile to)
-                            $ \dfd -> allocaBytes (fromIntegral bufSize) $ \buf ->
+                           $ \dfd -> copyAction sfd dfd
-                                        write' sfd dfd buf 0
+    -- this is low-level stuff utilizing sendfile(2) for speed
+    sendFileCopy :: ByteString -> ByteString -> IO ()
+    sendFileCopy = copyWith
+      (\sfd dfd -> sendfileFd dfd sfd EntireFile $ return ())
+    -- low-level copy operation utilizing read(2)/write(2)
+    -- in case `sendFileCopy` fails/is unsupported
+    readWriteCopy :: ByteString -> ByteString -> IO Int
+    readWriteCopy = copyWith
+      (\sfd dfd -> allocaBytes (fromIntegral bufSize)
+                     $ \buf -> write' sfd dfd buf 0)
       where
         bufSize :: CSize
         bufSize = 8192
@@ -473,7 +493,7 @@ easyCopyOverwrite from to = do
     ---------------------
 
 
--- |Deletes the given file, does not follow symlinks. Raises `eISDIR`
+-- |Deletes the given file. Raises `eISDIR`
 -- if run on a directory. Does not follow symbolic links.
 --
 -- Throws:
@@ -628,8 +648,8 @@ createDir dest = createDirectory (fromAbs dest) newDirPerms
 --     - `PermissionDenied` if output directory cannot be written to
 --     - `PermissionDenied` if source directory cannot be opened
 --     - `UnsupportedOperation` if source and destination are on different devices
---     - `FileDoesExist` if destination file already exists
+--     - `FileDoesExist` if destination file already exists (`HPathIOException`)
---     - `DirDoesExist` if destination directory already exists
+--     - `DirDoesExist` if destination directory already exists (`HPathIOException`)
 --     - `SameFile` if destination and source are the same file (`HPathIOException`)
 --
 -- Note: calls `rename` (but does not allow to rename over existing files)
@@ -655,8 +675,8 @@ renameFile fromf tof = do
 --     - `NoSuchThing` if source file does not exist
 --     - `PermissionDenied` if output directory cannot be written to
 --     - `PermissionDenied` if source directory cannot be opened
---     - `FileDoesExist` if destination file already exists
+--     - `FileDoesExist` if destination file already exists (`HPathIOException`)
---     - `DirDoesExist` if destination directory already exists
+--     - `DirDoesExist` if destination directory already exists (`HPathIOException`)
 --     - `SameFile` if destination and source are the same file (`HPathIOException`)
 --
 -- Note: calls `rename` (but does not allow to rename over existing files)
@@ -755,14 +775,12 @@ newDirPerms
 getDirsFiles :: Path Abs        -- ^ dir to read
              -> IO [Path Abs]
 getDirsFiles p =
-  withAbsPath p $ \fp ->
+  withAbsPath p $ \fp -> do
-    bracketOnError (SPDT.openFd fp SPI.ReadOnly [SPDF.oNofollow] Nothing)
+    fd <- openFd fp SPI.ReadOnly [SPDF.oNofollow] Nothing
-            SPI.closeFd
+    return
-            $ \fd ->
+      . catMaybes
-              return
+      .   fmap (\x -> (</>) p <$> (parseMaybe . snd $ x))
-                . catMaybes
+      =<< getDirectoryContents' fd
-                .   fmap (\x -> (</>) p <$> (parseMaybe . snd $ x))
-                =<< getDirectoryContents' fd
   where
     parseMaybe :: ByteString -> Maybe (Path Fn)
     parseMaybe = parseFn

src/HPath/IO/Errors.hs

@@ -66,6 +66,10 @@ import Data.ByteString
   (
     ByteString
   )
+import Data.ByteString.UTF8
+  (
+    toString
+  )
 import Data.Data
   (
     Data(..)
@@ -114,20 +118,20 @@ data HPathIOException = FileDoesNotExist ByteString
 
 
 instance Show HPathIOException where
-  show (FileDoesNotExist fp) = "File does not exist:" ++ fpToString fp
+  show (FileDoesNotExist fp) = "File does not exist:" ++ toString fp
   show (DirDoesNotExist fp) = "Directory does not exist: "
-                              ++ fpToString fp
+                              ++ toString fp
-  show (SameFile fp1 fp2) = fpToString fp1
+  show (SameFile fp1 fp2) = toString fp1
-                            ++ " and " ++ fpToString fp2
+                            ++ " and " ++ toString fp2
                             ++ " are the same file!"
-  show (DestinationInSource fp1 fp2) = fpToString fp1
+  show (DestinationInSource fp1 fp2) = toString fp1
                                        ++ " is contained in "
-                                       ++ fpToString fp2
+                                       ++ toString fp2
-  show (FileDoesExist fp) = "File does exist: " ++ fpToString fp
+  show (FileDoesExist fp) = "File does exist: " ++ toString fp
-  show (DirDoesExist fp) = "Directory does exist: " ++ fpToString fp
+  show (DirDoesExist fp) = "Directory does exist: " ++ toString fp
   show (InvalidOperation str) = "Invalid operation: " ++ str
   show (Can'tOpenDirectory fp) = "Can't open directory: "
-                                 ++ fpToString fp
+                                 ++ toString fp
   show (CopyFailed str) = "Copying failed: " ++ str
 
 
@@ -209,12 +213,13 @@ sameFile fp1 fp2 =
         else return False
 
 
+-- TODO: make this more robust when destination does not exist
 -- |Checks whether the destination directory is contained
 -- within the source directory by comparing the device+file ID of the
 -- source directory with all device+file IDs of the parent directories
 -- of the destination.
 throwDestinationInSource :: Path Abs -- ^ source dir
-                         -> Path Abs -- ^ full destination, `dirname dest`
+                         -> Path Abs -- ^ full destination, @dirname dest@
                                      --   must exist
                          -> IO ()
 throwDestinationInSource source dest = do
@@ -266,7 +271,7 @@ canOpenDirectory fp =
     return True
 
 
--- |Throws a `Can'tOpenDirectory` FmIOException if the directory at the given
+-- |Throws a `Can'tOpenDirectory` HPathIOException if the directory at the given
 -- path cannot be opened.
 throwCantOpenDirectory :: Path Abs -> IO ()
 throwCantOpenDirectory fp =
@@ -332,8 +337,8 @@ bracketeer before after afterEx thing =
 
 
 reactOnError :: IO a
-             -> [(IOErrorType, IO a)]   -- ^ reaction on IO errors
+             -> [(IOErrorType, IO a)]      -- ^ reaction on IO errors
-             -> [(HPathIOException, IO a)] -- ^ reaction on FmIOException
+             -> [(HPathIOException, IO a)] -- ^ reaction on HPathIOException
              -> IO a
 reactOnError a ios fmios =
   a `catches` [iohandler, fmiohandler]

src/System/Posix/Directory/Traversals.hs

@@ -1,9 +1,24 @@
+-- |
+-- Module      :  System.Posix.Directory.Traversals
+-- Copyright   :  © 2016 Julian Ospald
+-- License     :  BSD3
+--
+-- Maintainer  :  Julian Ospald <hasufell@posteo.de>
+-- Stability   :  experimental
+-- Portability :  portable
+--
+-- Traversal and read operations on directories.
+
+
 {-# LANGUAGE ForeignFunctionInterface #-}
 {-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE PackageImports #-}
 {-# LANGUAGE TupleSections #-}
 {-# LANGUAGE ViewPatterns #-}
 
 {-# OPTIONS_GHC -Wall #-}
+
+
 module System.Posix.Directory.Traversals (
 
   getDirectoryContents
@@ -17,7 +32,7 @@ module System.Posix.Directory.Traversals (
 , readDirEnt
 , packDirStream
 , unpackDirStream
-, openFd
+, fdOpendir
 
 , realpath
 ) where
@@ -36,6 +51,7 @@ import System.Posix.Directory.ByteString as PosixBS
 import System.Posix.Files.ByteString
 
 import System.IO.Unsafe
+import "unix" System.Posix.IO.ByteString (closeFd)
 import Unsafe.Coerce (unsafeCoerce)
 import Foreign.C.Error
 import Foreign.C.String
@@ -54,6 +70,8 @@ import Foreign.Storable
 -- Upon entering a directory, 'allDirectoryContents' will get all entries
 -- strictly.  However the returned list is lazy in that directories will only
 -- be accessed on demand.
+--
+-- Follows symbolic links for the input dir.
 allDirectoryContents :: RawFilePath -> IO [RawFilePath]
 allDirectoryContents topdir = do
     namesAndTypes <- getDirectoryContents topdir
@@ -71,6 +89,8 @@ allDirectoryContents topdir = do
     return (topdir : concat paths)
 
 -- | Get all files from a directory and its subdirectories strictly.
+--
+-- Follows symbolic links for the input dir.
 allDirectoryContents' :: RawFilePath -> IO [RawFilePath]
 allDirectoryContents' = fmap reverse . traverseDirectory (\acc fp -> return (fp:acc)) []
 -- this uses traverseDirectory because it's more efficient than forcing the
@@ -80,6 +100,8 @@ allDirectoryContents' = fmap reverse . traverseDirectory (\acc fp -> return (fp:
 -- files/subdirectories.
 --
 -- This function allows for memory-efficient traversals.
+--
+-- Follows symbolic links for the input dir.
 traverseDirectory :: (s -> RawFilePath -> IO s) -> s -> RawFilePath -> IO s
 traverseDirectory act s0 topdir = toploop
   where
@@ -103,17 +125,17 @@ actOnDirContents :: RawFilePath
                  -> IO b
 actOnDirContents pathRelToTop b f =
   modifyIOError ((`ioeSetFileName` (BS.unpack pathRelToTop)) .
-                 (`ioeSetLocation` "findBSTypRel")) $ do
+                 (`ioeSetLocation` "findBSTypRel")) $
     bracket
       (openDirStream pathRelToTop)
-      (Posix.closeDirStream)
+      Posix.closeDirStream
       (\dirp -> loop dirp b)
  where
   loop dirp b' = do
     (typ,e) <- readDirEnt dirp
     if (e == "")
       then return b'
-      else do
+      else
           if (e == "." || e == "..")
               then loop dirp b'
               else f typ (pathRelToTop </> e) b' >>= loop dirp
@@ -154,9 +176,6 @@ foreign import ccall "realpath"
 foreign import ccall unsafe "fdopendir"
   c_fdopendir :: Posix.Fd -> IO (Ptr ())
 
-foreign import ccall unsafe "open"
-   c_open :: CString -> CInt -> Posix.CMode -> IO CInt
-
 ----------------------------------------------------------
 -- less dodgy but still lower-level
 
@@ -189,81 +208,53 @@ readDirEnt (unpackDirStream -> dirp) =
                     else throwErrno "readDirEnt"
 
 
+-- |Gets all directory contents (not recursively).
 getDirectoryContents :: RawFilePath -> IO [(DirType, RawFilePath)]
 getDirectoryContents path =
   modifyIOError ((`ioeSetFileName` (BS.unpack path)) .
-                 (`ioeSetLocation` "System.Posix.Directory.Traversals.getDirectoryContents")) $ do
+                 (`ioeSetLocation` "System.Posix.Directory.Traversals.getDirectoryContents")) $
     bracket
       (PosixBS.openDirStream path)
       PosixBS.closeDirStream
-      loop
+      _dirloop
- where
-  loop dirp = do
-     t@(_typ,e) <- readDirEnt dirp
-     if BS.null e then return [] else do
-       es <- loop dirp
-       return (t:es)
 
 
+-- |Binding to @fdopendir(3)@.
 fdOpendir :: Posix.Fd -> IO DirStream
 fdOpendir fd =
     packDirStream <$> throwErrnoIfNull "fdOpendir" (c_fdopendir fd)
 
 
+-- |Like `getDirectoryContents` except for a file descriptor.
+--
+-- To avoid complicated error checks, the file descriptor is
+-- __always__ closed, even if `fdOpendir` fails. Usually, this
+-- only happens on successful `fdOpendir` and after the directory
+-- stream is closed. Also see the manpage of @fdopendir(3)@ for
+-- more details.
 getDirectoryContents' :: Posix.Fd -> IO [(DirType, RawFilePath)]
-getDirectoryContents' fd =
+getDirectoryContents' fd = do
-    bracket
+  dirstream <- fdOpendir fd `catchIOError` \e -> do
-      (fdOpendir fd)
+    closeFd fd
-      PosixBS.closeDirStream
+    ioError e
-      loop
+  -- closeDirStream closes the filedescriptor
- where
+  finally (_dirloop dirstream) (PosixBS.closeDirStream dirstream)
-  loop dirp = do
-     t@(_typ,e) <- readDirEnt dirp
-     if BS.null e then return [] else do
-       es <- loop dirp
-       return (t:es)
 
 
-open_  :: CString
+_dirloop :: DirStream -> IO [(DirType, RawFilePath)]
-       -> Posix.OpenMode
+{-# INLINE _dirloop #-}
-       -> [Flags]
+_dirloop dirp = do
-       -> Maybe Posix.FileMode
+   t@(_typ,e) <- readDirEnt dirp
-       -> IO Posix.Fd
+   if BS.null e then return [] else do
-open_ str how optional_flags maybe_mode = do
+     es <- _dirloop dirp
-    fd <- c_open str all_flags mode_w
+     return (t:es)
-    return (Posix.Fd fd)
-  where
-    all_flags  = unionFlags $ optional_flags ++ [open_mode] ++ creat
-
-
-    (creat, mode_w) = case maybe_mode of
-                        Nothing -> ([],0)
-                        Just x  -> ([oCreat], x)
-
-    open_mode = case how of
-                   Posix.ReadOnly  -> oRdonly
-                   Posix.WriteOnly -> oWronly
-                   Posix.ReadWrite -> oRdwr
-
-
--- |Open and optionally create this file.  See 'System.Posix.Files'
--- for information on how to use the 'FileMode' type.
-openFd :: RawFilePath
-       -> Posix.OpenMode
-       -> [Flags]
-       -> Maybe Posix.FileMode
-       -> IO Posix.Fd
-openFd name how optional_flags maybe_mode =
-   withFilePath name $ \str ->
-     throwErrnoPathIfMinus1Retry "openFd" name $
-       open_ str how optional_flags maybe_mode
 
 
 -- | return the canonicalized absolute pathname
 --
--- like canonicalizePath, but uses realpath(3)
+-- like canonicalizePath, but uses @realpath(3)@
 realpath :: RawFilePath -> IO RawFilePath
-realpath inp = do
+realpath inp =
     allocaBytes pathMax $ \tmp -> do
         void $ BS.useAsCString inp $ \cstr -> throwErrnoIfNull "realpath" $ c_realpath cstr tmp
         BS.packCString tmp

src/System/Posix/FD.hs

@@ -0,0 +1,75 @@
+-- |
+-- Module      :  System.Posix.FD
+-- Copyright   :  © 2016 Julian Ospald
+-- License     :  BSD3
+--
+-- Maintainer  :  Julian Ospald <hasufell@posteo.de>
+-- Stability   :  experimental
+-- Portability :  portable
+--
+-- Provides an alternative for `System.Posix.IO.ByteString.openFd`
+-- which gives us more control on what status flags to pass to the
+-- low-level @open(2)@ call, in contrast to the unix package.
+
+
+{-# LANGUAGE ForeignFunctionInterface #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TupleSections #-}
+
+{-# OPTIONS_GHC -Wall #-}
+
+
+module System.Posix.FD (
+    openFd
+) where
+
+
+import Foreign.C.String
+import Foreign.C.Types
+import System.Posix.Directory.Foreign
+import qualified System.Posix as Posix
+import System.Posix.ByteString.FilePath
+
+
+foreign import ccall unsafe "open"
+   c_open :: CString -> CInt -> Posix.CMode -> IO CInt
+
+
+open_  :: CString
+       -> Posix.OpenMode
+       -> [Flags]
+       -> Maybe Posix.FileMode
+       -> IO Posix.Fd
+open_ str how optional_flags maybe_mode = do
+    fd <- c_open str all_flags mode_w
+    return (Posix.Fd fd)
+  where
+    all_flags  = unionFlags $ optional_flags ++ [open_mode] ++ creat
+
+
+    (creat, mode_w) = case maybe_mode of
+                        Nothing -> ([],0)
+                        Just x  -> ([oCreat], x)
+
+    open_mode = case how of
+                   Posix.ReadOnly  -> oRdonly
+                   Posix.WriteOnly -> oWronly
+                   Posix.ReadWrite -> oRdwr
+
+
+-- |Open and optionally create this file. See 'System.Posix.Files'
+-- for information on how to use the 'FileMode' type.
+--
+-- Note that passing @Just x@ as the 4th argument triggers the
+-- `oCreat` status flag, which must be set when you pass in `oExcl`
+-- to the status flags. Also see the manpage for @open(2)@.
+openFd :: RawFilePath
+       -> Posix.OpenMode
+       -> [Flags]               -- ^ status flags of @open(2)@
+       -> Maybe Posix.FileMode  -- ^ @Just x@ => creates the file with the given modes, Nothing => the file must exist.
+       -> IO Posix.Fd
+openFd name how optional_flags maybe_mode =
+   withFilePath name $ \str ->
+     throwErrnoPathIfMinus1Retry "openFd" name $
+       open_ str how optional_flags maybe_mode
+

src/System/Posix/FilePath.hs

@@ -11,6 +11,8 @@
 --
 -- Not all functions of "System.FilePath" are implemented yet. Feel free to contribute!
 
+
+{-# LANGUAGE CPP #-}
 {-# LANGUAGE TupleSections #-}
 
 {-# OPTIONS_GHC -Wall #-}
@@ -18,7 +20,7 @@
 
 module System.Posix.FilePath (
 
-  -- * Separators
+  -- * Separator predicates
   pathSeparator
 , isPathSeparator
 , searchPathSeparator
@@ -26,7 +28,11 @@ module System.Posix.FilePath (
 , extSeparator
 , isExtSeparator
 
-  -- * File extensions
+  -- * $PATH methods
+, splitSearchPath
+, getSearchPath
+
+  -- * Extension functions
 , splitExtension
 , takeExtension
 , replaceExtension
@@ -37,8 +43,9 @@ module System.Posix.FilePath (
 , splitExtensions
 , dropExtensions
 , takeExtensions
+, stripExtension
 
-  -- * Filenames/Directory names
+  -- * Filename\/directory functions
 , splitFileName
 , takeFileName
 , replaceFileName
@@ -47,92 +54,135 @@ module System.Posix.FilePath (
 , replaceBaseName
 , takeDirectory
 , replaceDirectory
-
-  -- * Path combinators and splitters
 , combine
 , (</>)
 , splitPath
 , joinPath
 , splitDirectories
 
-  -- * Path conversions
+  -- * Trailing slash functions
-, normalise
-
-  -- * Trailing path separator
 , hasTrailingPathSeparator
 , addTrailingPathSeparator
 , dropTrailingPathSeparator
 
-  -- * Queries
+  -- * File name manipulations
+, normalise
+, makeRelative
+, equalFilePath
 , isRelative
 , isAbsolute
 , isValid
+, makeValid
 , isFileName
 , hasParentDir
-, equalFilePath
 , hiddenFile
 
-  -- * Type conversion
-, fpToString
-, userStringToFP
-
 , module System.Posix.ByteString.FilePath
 ) where
 
 import           Data.ByteString (ByteString)
 import qualified Data.ByteString as BS
-import           Data.ByteString.UTF8 (fromString, toString)
+import Data.String (fromString)
 import           System.Posix.ByteString.FilePath
+import qualified System.Posix.Env.ByteString as PE
 
 import           Data.Maybe (isJust)
 import           Data.Word8
-
+#if !MIN_VERSION_bytestring(0,10,8)
+import qualified Data.List as L
+#endif
 import           Control.Arrow (second)
 
 -- $setup
 -- >>> import Data.Char
+-- >>> import Data.Maybe
 -- >>> import Test.QuickCheck
 -- >>> import Control.Applicative
 -- >>> import qualified Data.ByteString as BS
--- >>> import Data.ByteString (ByteString)
 -- >>> instance Arbitrary ByteString where arbitrary = BS.pack <$> arbitrary
 -- >>> instance CoArbitrary ByteString where coarbitrary = coarbitrary . BS.unpack
 --
 -- >>> let _chr :: Word8 -> Char; _chr = chr . fromIntegral
 
 
+
+------------------------
+-- Separator predicates
+
+
 -- | Path separator character
 pathSeparator :: Word8
 pathSeparator = _slash
 
+
 -- | Check if a character is the path separator
 --
 -- prop> \n ->  (_chr n == '/') == isPathSeparator n
 isPathSeparator :: Word8 -> Bool
 isPathSeparator = (== pathSeparator)
 
+
 -- | Search path separator
 searchPathSeparator :: Word8
 searchPathSeparator = _colon
 
+
 -- | Check if a character is the search path separator
 --
 -- prop> \n -> (_chr n == ':') == isSearchPathSeparator n
 isSearchPathSeparator :: Word8 -> Bool
 isSearchPathSeparator = (== searchPathSeparator)
 
+
 -- | File extension separator
 extSeparator :: Word8
 extSeparator = _period
 
+
 -- | Check if a character is the file extension separator
 --
 -- prop> \n -> (_chr n == '.') == isExtSeparator n
 isExtSeparator :: Word8 -> Bool
 isExtSeparator = (== extSeparator)
 
+
+
 ------------------------
--- extension stuff
+-- $PATH methods
+
+
+-- | Take a ByteString, split it on the 'searchPathSeparator'.
+-- Blank items are converted to @.@.
+--
+-- Follows the recommendations in
+-- <http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html>
+--
+-- >>> splitSearchPath "File1:File2:File3"
+-- ["File1","File2","File3"]
+-- >>> splitSearchPath "File1::File2:File3"
+-- ["File1",".","File2","File3"]
+-- >>> splitSearchPath ""
+-- ["."]
+splitSearchPath :: ByteString -> [RawFilePath]
+splitSearchPath = f
+  where
+    f bs = let (pre, post) = BS.break isSearchPathSeparator bs
+           in if BS.null post
+                 then g pre
+                 else g pre ++ f (BS.tail post)
+    g x
+      | BS.null x = [BS.singleton _period]
+      | otherwise = [x]
+
+
+-- | Get a list of 'RawFilePath's in the $PATH variable.
+getSearchPath :: IO [RawFilePath]
+getSearchPath = fmap (maybe [] splitSearchPath) (PE.getEnv $ fromString "PATH")
+
+
+
+------------------------
+-- Extension functions
 
 -- | Split a 'RawFilePath' into a path+filename and extension
 --
@@ -152,6 +202,7 @@ splitExtension x = if BS.null basename
     (path,file) = splitFileNameRaw x
     (basename,fileExt) = BS.breakEnd isExtSeparator file
 
+
 -- | Get the final extension from a 'RawFilePath'
 --
 -- >>> takeExtension "file.exe"
@@ -163,12 +214,14 @@ splitExtension x = if BS.null basename
 takeExtension :: RawFilePath -> ByteString
 takeExtension = snd . splitExtension
 
+
 -- | Change a file's extension
 --
 -- prop> \path -> let ext = takeExtension path in replaceExtension path ext == path
 replaceExtension :: RawFilePath -> ByteString -> RawFilePath
 replaceExtension path ext = dropExtension path <.> ext
 
+
 -- | Drop the final extension from a 'RawFilePath'
 --
 -- >>> dropExtension "file.exe"
@@ -180,6 +233,7 @@ replaceExtension path ext = dropExtension path <.> ext
 dropExtension :: RawFilePath -> RawFilePath
 dropExtension = fst . splitExtension
 
+
 -- | Add an extension to a 'RawFilePath'
 --
 -- >>> addExtension "file" ".exe"
@@ -195,10 +249,6 @@ addExtension file ext
     | otherwise = BS.intercalate (BS.singleton extSeparator) [file, ext]
 
 
--- | Operator version of 'addExtension'
-(<.>) :: RawFilePath -> ByteString -> RawFilePath
-(<.>) = addExtension
-
 -- | Check if a 'RawFilePath' has an extension
 --
 -- >>> hasExtension "file"
@@ -210,7 +260,13 @@ addExtension file ext
 hasExtension :: RawFilePath -> Bool
 hasExtension = isJust . BS.elemIndex extSeparator . takeFileName
 
--- | Split a 'RawFilePath' on the first extension
+
+-- | Operator version of 'addExtension'
+(<.>) :: RawFilePath -> ByteString -> RawFilePath
+(<.>) = addExtension
+
+
+-- | Split a 'RawFilePath' on the first extension.
 --
 -- >>> splitExtensions "/path/file.tar.gz"
 -- ("/path/file",".tar.gz")
@@ -224,6 +280,7 @@ splitExtensions x = if BS.null basename
     (path,file) = splitFileNameRaw x
     (basename,fileExt) = BS.break isExtSeparator file
 
+
 -- | Remove all extensions from a 'RawFilePath'
 --
 -- >>> dropExtensions "/path/file.tar.gz"
@@ -231,6 +288,7 @@ splitExtensions x = if BS.null basename
 dropExtensions :: RawFilePath -> RawFilePath
 dropExtensions = fst . splitExtensions
 
+
 -- | Take all extensions from a 'RawFilePath'
 --
 -- >>> takeExtensions "/path/file.tar.gz"
@@ -238,8 +296,48 @@ dropExtensions = fst . splitExtensions
 takeExtensions :: RawFilePath -> ByteString
 takeExtensions = snd . splitExtensions
 
+
+-- | Drop the given extension from a FilePath, and the @\".\"@ preceding it.
+-- Returns 'Nothing' if the FilePath does not have the given extension, or
+-- 'Just' and the part before the extension if it does.
+--
+-- This function can be more predictable than 'dropExtensions',
+-- especially if the filename might itself contain @.@ characters.
+--
+-- >>> stripExtension "hs.o" "foo.x.hs.o"
+-- Just "foo.x"
+-- >>> stripExtension "hi.o" "foo.x.hs.o"
+-- Nothing
+-- >>> stripExtension ".c.d" "a.b.c.d"
+-- Just "a.b"
+-- >>> stripExtension ".c.d" "a.b..c.d"
+-- Just "a.b."
+-- >>> stripExtension "baz"  "foo.bar"
+-- Nothing
+-- >>> stripExtension "bar"  "foobar"
+-- Nothing
+--
+-- prop> \path -> stripExtension "" path == Just path
+-- prop> \path -> dropExtension path  == fromJust (stripExtension (takeExtension path) path)
+-- prop> \path -> dropExtensions path == fromJust (stripExtension (takeExtensions path) path)
+stripExtension :: ByteString -> RawFilePath -> Maybe RawFilePath
+stripExtension bs path
+  | BS.null bs = Just path
+  | otherwise  = stripSuffix' dotExt path
+  where
+    dotExt = if isExtSeparator $ BS.head bs
+                then bs
+                else extSeparator `BS.cons` bs
+#if MIN_VERSION_bytestring(0,10,8)
+    stripSuffix' = BS.stripSuffix
+#else
+    stripSuffix' xs ys = fmap (BS.pack . reverse) $ L.stripPrefix (reverse $ BS.unpack xs) (reverse $ BS.unpack ys)
+#endif
+
+
 ------------------------
--- more stuff
+-- Filename/directory functions
+
 
 -- | Split a 'RawFilePath' into (path,file).  'combine' is the inverse
 --
@@ -269,12 +367,14 @@ splitFileName x = if BS.null path
 takeFileName :: RawFilePath -> RawFilePath
 takeFileName = snd . splitFileName
 
+
 -- | Change the file name
 --
 -- prop> \path -> replaceFileName path (takeFileName path) == path
 replaceFileName :: RawFilePath -> ByteString -> RawFilePath
 replaceFileName x y = fst (splitFileNameRaw x) </> y
 
+
 -- | Drop the file name
 --
 -- >>> dropFileName "path/file.txt"
@@ -284,6 +384,7 @@ replaceFileName x y = fst (splitFileNameRaw x) </> y
 dropFileName :: RawFilePath -> RawFilePath
 dropFileName = fst . splitFileName
 
+
 -- | Get the file name, without a trailing extension
 --
 -- >>> takeBaseName "path/file.tar.gz"
@@ -293,6 +394,7 @@ dropFileName = fst . splitFileName
 takeBaseName :: RawFilePath -> ByteString
 takeBaseName = dropExtension . takeFileName
 
+
 -- | Change the base name
 --
 -- >>> replaceBaseName "path/file.tar.gz" "bob"
@@ -305,6 +407,7 @@ replaceBaseName path name = combineRaw dir (name <.> ext)
     (dir,file) = splitFileNameRaw path
     ext = takeExtension file
 
+
 -- | Get the directory, moving up one level if it's already a directory
 --
 -- >>> takeDirectory "path/file.txt"
@@ -324,12 +427,14 @@ takeDirectory x = case () of
     res = fst $ BS.spanEnd isPathSeparator file
     file = dropFileName x
 
+
 -- | Change the directory component of a 'RawFilePath'
 --
 -- prop> \path -> replaceDirectory path (takeDirectory path) `equalFilePath` path || takeDirectory path == "."
 replaceDirectory :: RawFilePath -> ByteString -> RawFilePath
 replaceDirectory file dir = combineRaw dir (takeFileName file)
 
+
 -- | Join two paths together
 --
 -- >>> combine "/" "file"
@@ -342,6 +447,7 @@ combine :: RawFilePath -> RawFilePath -> RawFilePath
 combine a b | not (BS.null b) && isPathSeparator (BS.head b) = b
             | otherwise = combineRaw a b
 
+
 -- | Operator version of combine
 (</>) :: RawFilePath -> RawFilePath -> RawFilePath
 (</>) = combine
@@ -363,6 +469,17 @@ splitPath = splitter
                           Nothing -> [x]
                           Just runlen -> uncurry (:) . second splitter $ BS.splitAt (ix+1+runlen) x
 
+
+-- | Join a split path back together
+--
+-- prop> \path -> joinPath (splitPath path) == path
+--
+-- >>> joinPath ["path","to","file.txt"]
+-- "path/to/file.txt"
+joinPath :: [RawFilePath] -> RawFilePath
+joinPath = foldr (</>) BS.empty
+
+
 -- | Like 'splitPath', but without trailing slashes
 --
 -- >>> splitDirectories "/path/to/file.txt"
@@ -378,14 +495,60 @@ splitDirectories x
   where
     splitter = filter (not . BS.null) . BS.split pathSeparator
 
--- | Join a split path back together
+
+
+------------------------
+-- Trailing slash functions
+
+-- | Check if the last character of a 'RawFilePath' is '/'.
 --
--- prop> \path -> joinPath (splitPath path) == path
+-- >>> hasTrailingPathSeparator "/path/"
+-- True
+-- >>> hasTrailingPathSeparator "/"
+-- True
+-- >>> hasTrailingPathSeparator "/path"
+-- False
+hasTrailingPathSeparator :: RawFilePath -> Bool
+hasTrailingPathSeparator x
+  | BS.null x = False
+  | otherwise = isPathSeparator $ BS.last x
+
+
+-- | Add a trailing path separator.
 --
--- >>> joinPath ["path","to","file.txt"]
+-- >>> addTrailingPathSeparator "/path"
--- "path/to/file.txt"
+-- "/path/"
-joinPath :: [RawFilePath] -> RawFilePath
+-- >>> addTrailingPathSeparator "/path/"
-joinPath = foldr (</>) BS.empty
+-- "/path/"
+-- >>> addTrailingPathSeparator "/"
+-- "/"
+addTrailingPathSeparator :: RawFilePath -> RawFilePath
+addTrailingPathSeparator x = if hasTrailingPathSeparator x
+    then x
+    else x `BS.snoc` pathSeparator
+
+
+-- | Remove a trailing path separator
+--
+-- >>> dropTrailingPathSeparator "/path/"
+-- "/path"
+-- >>> dropTrailingPathSeparator "/path////"
+-- "/path"
+-- >>> dropTrailingPathSeparator "/"
+-- "/"
+-- >>> dropTrailingPathSeparator "//"
+-- "/"
+dropTrailingPathSeparator :: RawFilePath -> RawFilePath
+dropTrailingPathSeparator x
+  | x == BS.singleton pathSeparator = x
+  | otherwise = if hasTrailingPathSeparator x
+                  then dropTrailingPathSeparator $ BS.init x
+                  else x
+
+
+
+------------------------
+-- File name manipulations
 
 
 -- |Normalise a file.
@@ -442,139 +605,47 @@ normalise filepath =
     dropDots = filter (BS.singleton _period /=)
 
 
-------------------------
--- trailing path separators
 
--- | Check if the last character of a 'RawFilePath' is '/'.
+-- | Contract a filename, based on a relative path. Note that the resulting
+-- path will never introduce @..@ paths, as the presence of symlinks
+-- means @..\/b@ may not reach @a\/b@ if it starts from @a\/c@. For a
+-- worked example see
+-- <http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html this blog post>.
 --
--- >>> hasTrailingPathSeparator "/path/"
+-- >>> makeRelative "/directory" "/directory/file.ext"
--- True
+-- "file.ext"
--- >>> hasTrailingPathSeparator "/"
+-- >>> makeRelative "/Home" "/home/bob"
--- True
+-- "/home/bob"
--- >>> hasTrailingPathSeparator "/path"
+-- >>> makeRelative "/home/" "/home/bob/foo/bar"
--- False
+-- "bob/foo/bar"
-hasTrailingPathSeparator :: RawFilePath -> Bool
+-- >>> makeRelative "/fred" "bob"
-hasTrailingPathSeparator x
+-- "bob"
-  | BS.null x = False
+-- >>> makeRelative "/file/test" "/file/test/fred"
-  | otherwise = isPathSeparator $ BS.last x
+-- "fred"
-
+-- >>> makeRelative "/file/test" "/file/test/fred/"
--- | Add a trailing path separator.
+-- "fred/"
+-- >>> makeRelative "some/path" "some/path/a/b/c"
+-- "a/b/c"
 --
--- >>> addTrailingPathSeparator "/path"
+-- prop> \p -> makeRelative p p == "."
--- "/path/"
+-- prop> \p -> makeRelative (takeDirectory p) p `equalFilePath` takeFileName p
--- >>> addTrailingPathSeparator "/path/"
+-- prop \x y -> equalFilePath x y || (isRelative x && makeRelative y x == x) || equalFilePath (y </> makeRelative y x) x
--- "/path/"
+makeRelative :: RawFilePath -> RawFilePath -> RawFilePath
--- >>> addTrailingPathSeparator "/"
+makeRelative root path
--- "/"
+  | equalFilePath root path = BS.singleton _period
-addTrailingPathSeparator :: RawFilePath -> RawFilePath
+  | takeAbs root /= takeAbs path = path
-addTrailingPathSeparator x = if hasTrailingPathSeparator x
+  | otherwise = f (dropAbs root) (dropAbs path)
-    then x
-    else x `BS.snoc` pathSeparator
-
--- | Remove a trailing path separator
---
--- >>> dropTrailingPathSeparator "/path/"
--- "/path"
--- >>> dropTrailingPathSeparator "/path////"
--- "/path"
--- >>> dropTrailingPathSeparator "/"
--- "/"
--- >>> dropTrailingPathSeparator "//"
--- "/"
-dropTrailingPathSeparator :: RawFilePath -> RawFilePath
-dropTrailingPathSeparator x
-  | x == BS.singleton pathSeparator = x
-  | otherwise = if hasTrailingPathSeparator x
-                  then dropTrailingPathSeparator $ BS.init x
-                  else x
-
-------------------------
--- Filename/system stuff
-
--- | Check if a path is absolute
---
--- >>> isAbsolute "/path"
--- True
--- >>> isAbsolute "path"
--- False
--- >>> isAbsolute ""
--- False
-isAbsolute :: RawFilePath -> Bool
-isAbsolute x
-    | BS.length x > 0 = isPathSeparator (BS.head x)
-    | otherwise = False
-
--- | Check if a path is relative
---
--- prop> \path -> isRelative path /= isAbsolute path
-isRelative :: RawFilePath -> Bool
-isRelative = not . isAbsolute
-
--- | Is a FilePath valid, i.e. could you create a file like it?
---
--- >>> isValid ""
--- False
--- >>> isValid "\0"
--- False
--- >>> isValid "/random_ path:*"
--- True
-isValid :: RawFilePath -> Bool
-isValid filepath
-  | BS.null filepath        = False
-  | _nul `BS.elem` filepath = False
-  | otherwise               = True
-
--- | Is the given filename a valid filename?
---
--- >>> isFileName "lal"
--- True
--- >>> isFileName "."
--- True
--- >>> isFileName ".."
--- True
--- >>> isFileName ""
--- False
--- >>> isFileName "\0"
--- False
--- >>> isFileName "/random_ path:*"
--- False
-isFileName :: ByteString -> Bool
-isFileName filepath =
-  not (BS.singleton pathSeparator `BS.isInfixOf` filepath) &&
-  not (BS.null filepath) &&
-  not (_nul `BS.elem` filepath)
-
--- | Helper function: check if the filepath has any parent directories in it.
---
--- >>> hasParentDir "/.."
--- True
--- >>> hasParentDir "foo/bar/.."
--- True
--- >>> hasParentDir "foo/../bar/."
--- True
--- >>> hasParentDir "foo/bar"
--- False
--- >>> hasParentDir "foo"
--- False
--- >>> hasParentDir ""
--- False
--- >>> hasParentDir ".."
--- False
-hasParentDir :: ByteString -> Bool
-hasParentDir filepath =
-  ((pathSeparator `BS.cons` pathDoubleDot)
-    `BS.isSuffixOf` filepath
-  ) ||
-  ((BS.singleton pathSeparator
-     `BS.append` pathDoubleDot
-     `BS.append` BS.singleton pathSeparator
-   ) `BS.isInfixOf`  filepath
-  ) ||
-  ((pathDoubleDot `BS.append` BS.singleton pathSeparator
-   ) `BS.isPrefixOf` filepath
-  )
   where
-    pathDoubleDot = BS.pack [_period, _period]
+    f x y
+      | BS.null x = BS.dropWhile isPathSeparator y
+      | otherwise = let (x1,x2) = g x
+                        (y1,y2) = g y
+                    in if equalFilePath x1 y1 then f x2 y2 else path
+    g x = (BS.dropWhile isPathSeparator a, BS.dropWhile isPathSeparator b)
+      where (a, b) = BS.break isPathSeparator $ BS.dropWhile isPathSeparator x
+    dropAbs x = snd $ BS.span (== _slash) x
+    takeAbs x = fst $ BS.span (== _slash) x
+
 
 -- |Equality of two filepaths. The filepaths are normalised
 -- and trailing path separators are dropped.
@@ -585,6 +656,8 @@ hasParentDir filepath =
 -- True
 -- >>> equalFilePath "foo" "./foo"
 -- True
+-- >>> equalFilePath "" ""
+-- True
 -- >>> equalFilePath "foo" "/foo"
 -- False
 -- >>> equalFilePath "foo" "FOO"
@@ -599,37 +672,138 @@ equalFilePath p1 p2 = f p1 == f p2
     f x = dropTrailingPathSeparator $ normalise x
 
 
+-- | Check if a path is relative
+--
+-- prop> \path -> isRelative path /= isAbsolute path
+isRelative :: RawFilePath -> Bool
+isRelative = not . isAbsolute
+
+
+-- | Check if a path is absolute
+--
+-- >>> isAbsolute "/path"
+-- True
+-- >>> isAbsolute "path"
+-- False
+-- >>> isAbsolute ""
+-- False
+isAbsolute :: RawFilePath -> Bool
+isAbsolute x
+    | BS.length x > 0 = isPathSeparator (BS.head x)
+    | otherwise = False
+
+
+-- | Is a FilePath valid, i.e. could you create a file like it?
+--
+-- >>> isValid ""
+-- False
+-- >>> isValid "\0"
+-- False
+-- >>> isValid "/random_ path:*"
+-- True
+isValid :: RawFilePath -> Bool
+isValid filepath
+  | BS.null filepath        = False
+  | _nul `BS.elem` filepath = False
+  | otherwise               = True
+
+
+-- | Take a FilePath and make it valid; does not change already valid FilePaths.
+--
+-- >>> makeValid ""
+-- "_"
+-- >>> makeValid "file\0name"
+-- "file_name"
+--
+-- prop> \p -> if isValid p then makeValid p == p else makeValid p /= p
+-- prop> \p -> isValid (makeValid p)
+makeValid :: RawFilePath -> RawFilePath
+makeValid path
+  | BS.null path = BS.singleton _underscore
+  | otherwise    = BS.map (\x -> if x == _nul then _underscore else x) path
+
+
+-- | Is the given path a valid filename? This includes
+-- "." and "..".
+--
+-- >>> isFileName "lal"
+-- True
+-- >>> isFileName "."
+-- True
+-- >>> isFileName ".."
+-- True
+-- >>> isFileName ""
+-- False
+-- >>> isFileName "\0"
+-- False
+-- >>> isFileName "/random_ path:*"
+-- False
+isFileName :: RawFilePath -> Bool
+isFileName filepath =
+  not (BS.singleton pathSeparator `BS.isInfixOf` filepath) &&
+  not (BS.null filepath) &&
+  not (_nul `BS.elem` filepath)
+
+
+-- | Check if the filepath has any parent directories in it.
+--
+-- >>> hasParentDir "/.."
+-- True
+-- >>> hasParentDir "foo/bar/.."
+-- True
+-- >>> hasParentDir "foo/../bar/."
+-- True
+-- >>> hasParentDir "foo/bar"
+-- False
+-- >>> hasParentDir "foo"
+-- False
+-- >>> hasParentDir ""
+-- False
+-- >>> hasParentDir ".."
+-- False
+hasParentDir :: RawFilePath -> Bool
+hasParentDir filepath =
+    (pathSeparator `BS.cons` pathDoubleDot)
+     `BS.isSuffixOf` filepath
+   ||
+    (BS.singleton pathSeparator
+        `BS.append` pathDoubleDot
+        `BS.append` BS.singleton pathSeparator)
+     `BS.isInfixOf`  filepath
+   ||
+    (pathDoubleDot `BS.append` BS.singleton pathSeparator)
+      `BS.isPrefixOf` filepath
+  where
+    pathDoubleDot = BS.pack [_period, _period]
+
+
 -- | Whether the file is a hidden file.
 --
 -- >>> hiddenFile ".foo"
 -- True
 -- >>> hiddenFile "..foo.bar"
 -- True
+-- >>> hiddenFile "some/path/.bar"
+-- True
 -- >>> hiddenFile "..."
 -- True
--- >>> hiddenFile "dod"
--- False
 -- >>> hiddenFile "dod.bar"
 -- False
+-- >>> hiddenFile "."
+-- False
+-- >>> hiddenFile ".."
+-- False
+-- >>> hiddenFile ""
+-- False
 hiddenFile :: RawFilePath -> Bool
 hiddenFile fp
-  | fp == BS.pack [_period, _period] = False
+  | fn == BS.pack [_period, _period] = False
-  | fp == BS.pack [_period]          = False
+  | fn == BS.pack [_period]          = False
   | otherwise                        = BS.pack [extSeparator]
-                                         `BS.isPrefixOf` fp
+                                         `BS.isPrefixOf` fn
+  where
+    fn = takeFileName fp
 
-------------------------
--- conversion
-
--- |Uses UTF-8 decoding to convert the bytestring into a String.
-fpToString :: ByteString -> String
-fpToString = toString
-
-
--- |Uses UTF-8 encoding to convert a user provided String into
--- a ByteString, which represents a filepath.
-userStringToFP :: String -> ByteString
-userStringToFP = fromString
 
 
 ------------------------
@@ -638,7 +812,7 @@ userStringToFP = fromString
 -- Just split the input FileName without adding/normalizing or changing
 -- anything.
 splitFileNameRaw :: RawFilePath -> (RawFilePath, RawFilePath)
-splitFileNameRaw x = BS.breakEnd isPathSeparator x
+splitFileNameRaw = BS.breakEnd isPathSeparator
 
 -- | Combine two paths, assuming rhs is NOT absolute.
 combineRaw :: RawFilePath -> RawFilePath -> RawFilePath