diff --git a/System/IO/SaferFileHandles.hs b/System/IO/SaferFileHandles.hs --- a/System/IO/SaferFileHandles.hs +++ b/System/IO/SaferFileHandles.hs @@ -25,12 +25,15 @@ -- * Secondly this module provides all the file operations of @System.IO@ lifted -- to the region monad. -- +-- * Third, filepaths that are given to functions like 'openFile' are created +-- and manipulated in a type-safe way using the @pathtype@ package. +-- -- * The final contribution of this module is that file handles are -- parameterised with the IOMode in which the file was opened. This can be --- either 'R', 'W', 'A' or 'RW'. All operations on files explicitly specify the --- needed IOMode using the 'ReadModes' and 'WriteModes' type classes. This way --- it is impossible to read from a write-only handle or write to a read-only --- handle for example. +-- either 'ReadMode', 'WriteMode', 'AppendMode' or 'ReadWriteMode'. All +-- operations on files explicitly specify the needed IOMode using the +-- 'ReadModes' and 'WriteModes' type classes. This way it is impossible to read +-- from a write-only handle or write to a read-only handle for example. -- -- See the @safer-file-handles-examples@ package for examples how to use this -- package: @@ -74,7 +77,6 @@ , cast -- ** Opening files in a region - , FilePath , openFile, withFile -- *** Opening files by inferring the IOMode @@ -86,7 +88,7 @@ * Run a region using 'runRegionT'. - * Concurrently run a region inside another region using 'forkTopRegion'. + * Concurrently run a region inside another region using 'forkIOTopRegion'. * Duplicate a 'RegionalFileHandle' to a parent region using 'dup'. -} @@ -274,7 +276,6 @@ , CheckMode - , FilePath , BufferMode(..) , HandlePosn , SeekMode(..) @@ -297,6 +298,13 @@ import qualified System.IO.ExplicitIOModes as E +-- from pathtype: +import System.Path ( DirPath, FilePath + , AbsFile, RelFile + , AbsRelClass + , getPathString, asAbsFile + ) + -- from ourselves: import System.IO.SaferFileHandles.Internal ( RegionalFileHandle(RegionalFileHandle) ) import System.IO.SaferFileHandles.Unsafe ( wrap, wrap2, wrap3, sanitizeIOError ) @@ -373,21 +381,22 @@ Note: if you will be working with files containing binary data, you'll want to be using 'openBinaryFile'. -} -openFile ∷ MonadCatchIO pr - ⇒ FilePath +openFile ∷ (MonadCatchIO pr, AbsRelClass ar) + ⇒ FilePath ar → IOMode ioMode → RegionT s pr (RegionalFileHandle ioMode (RegionT s pr)) openFile = openNormal E.openFile -openNormal ∷ MonadCatchIO pr - ⇒ (FilePath → IOMode ioMode → IO (E.Handle ioMode)) - → FilePath - → IOMode ioMode - → RegionT s pr - (RegionalFileHandle ioMode (RegionT s pr)) -openNormal open filePath ioMode = block $ do - h ← liftIO $ open filePath ioMode +openNormal ∷ (MonadCatchIO pr, AbsRelClass ar) + ⇒ (E.FilePath → IOMode ioMode → IO (E.Handle ioMode)) + → ( FilePath ar + → IOMode ioMode + → RegionT s pr + (RegionalFileHandle ioMode (RegionT s pr)) + ) +openNormal open = \filePath ioMode → block $ do + h ← liftIO $ open (getPathString filePath) ioMode ch ← onExit $ sanitizeIOError $ hClose h return $ RegionalFileHandle h $ Just ch @@ -395,8 +404,8 @@ function to the resulting regional file handle and runs the resulting region. This provides a safer safer replacement for @System.IO.'SIO.withFile'@. -} -withFile ∷ MonadCatchIO pr - ⇒ FilePath +withFile ∷ (MonadCatchIO pr, AbsRelClass ar) + ⇒ FilePath ar → IOMode ioMode → (∀ s. RegionalFileHandle ioMode (RegionT s pr) → RegionT s pr α) → pr α @@ -408,15 +417,15 @@ -- inferred from the type of the resulting 'RegionalFileHandle'. -- -- Note that: @openFile' fp = 'openFile' fp 'mkIOMode'@. -openFile' ∷ (MonadCatchIO pr, MkIOMode ioMode) - ⇒ FilePath +openFile' ∷ (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) + ⇒ FilePath ar → RegionT s pr (RegionalFileHandle ioMode (RegionT s pr)) openFile' filePath = openFile filePath mkIOMode -- | Note that: @withFile' filePath = 'withFile' filePath 'mkIOMode'@. -withFile' ∷ (MonadCatchIO pr, MkIOMode ioMode) - ⇒ FilePath +withFile' ∷ (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) + ⇒ FilePath ar → (∀ s. RegionalFileHandle ioMode (RegionT s pr) → RegionT s pr α) → pr α withFile' filePath = withFile filePath mkIOMode @@ -874,8 +883,8 @@ -- characters. (See also 'hSetBinaryMode'.) -- -- This provides a safer replacement for @System.IO.'SIO.openBinaryFile'@. -openBinaryFile ∷ MonadCatchIO pr - ⇒ FilePath +openBinaryFile ∷ (MonadCatchIO pr, AbsRelClass ar) + ⇒ FilePath ar → IOMode ioMode → RegionT s pr (RegionalFileHandle ioMode (RegionT s pr)) @@ -886,8 +895,8 @@ resulting region. This provides a safer replacement for @System.IO.'SIO.withBinaryFile'@. -} -withBinaryFile ∷ MonadCatchIO pr - ⇒ FilePath +withBinaryFile ∷ (MonadCatchIO pr, AbsRelClass ar) + ⇒ FilePath ar → IOMode ioMode → (∀ s. RegionalFileHandle ioMode (RegionT s pr) → RegionT s pr α) → pr α @@ -896,15 +905,15 @@ -- ** Opening binary files by inferring the IOMode -- | Note that: @openBinaryFile' filePath = 'openBinaryFile' filePath 'mkIOMode'@. -openBinaryFile' ∷ (MonadCatchIO pr, MkIOMode ioMode) - ⇒ FilePath +openBinaryFile' ∷ (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) + ⇒ FilePath ar → RegionT s pr (RegionalFileHandle ioMode (RegionT s pr)) openBinaryFile' filePath = openBinaryFile filePath mkIOMode -- | Note that: @withBinaryFile' filePath = 'withBinaryFile' filePath 'mkIOMode'@. -withBinaryFile' ∷ (MonadCatchIO pr, MkIOMode ioMode) - ⇒ FilePath +withBinaryFile' ∷ (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) + ⇒ FilePath ar → (∀ s. RegionalFileHandle ioMode (RegionT s pr) → RegionT s pr α) → pr α withBinaryFile' filePath = withBinaryFile filePath mkIOMode @@ -1006,24 +1015,25 @@ -- -- If the template is \"foo.ext\" then the created file will be \"fooXXX.ext\" -- where XXX is some random number. -type Template = String +type Template = RelFile -openTemp ∷ MonadCatchIO pr - ⇒ (FilePath → Template → IO (FilePath, E.Handle ReadWriteMode)) - → FilePath - → Template - → RegionT s pr ( FilePath - , RegionalFileHandle ReadWriteMode (RegionT s pr) - ) -openTemp open filePath template = block $ do - (fp, h) ← liftIO $ open filePath template +openTemp ∷ (MonadCatchIO pr, AbsRelClass ar) + ⇒ (E.FilePath → String → IO (E.FilePath, E.Handle ReadWriteMode)) + → ( DirPath ar + → Template + → RegionT s pr ( AbsFile + , RegionalFileHandle ReadWriteMode (RegionT s pr) + ) + ) +openTemp open = \dirPath template → block $ do + (fp, h) ← liftIO $ open (getPathString dirPath) (getPathString template) ch ← onExit $ sanitizeIOError $ hClose h - return (fp, RegionalFileHandle h $ Just ch) + return (asAbsFile fp, RegionalFileHandle h $ Just ch) -- | The function creates a temporary file in 'ReadWriteMode'. The created file -- isn\'t deleted automatically, so you need to delete it manually. -- --- The file is creates with permissions such that only the current +-- The file is created with permissions such that only the current -- user can read\/write it. -- -- With some exceptions (see below), the file will be created securely in the @@ -1035,10 +1045,10 @@ -- so if you rely on this behaviour it is best to use local filesystems only. -- -- This provides a safer replacement for @System.IO.'SIO.openTempFile'@. -openTempFile ∷ MonadCatchIO pr - ⇒ FilePath -- ^ Directory in which to create the file. - → Template -- ^ File name template. - → RegionT s pr ( FilePath +openTempFile ∷ (MonadCatchIO pr, AbsRelClass ar) + ⇒ DirPath ar -- ^ Directory in which to create the file. + → Template -- ^ File name template. + → RegionT s pr ( AbsFile , RegionalFileHandle ReadWriteMode (RegionT s pr) ) openTempFile = openTemp E.openTempFile @@ -1048,10 +1058,10 @@ -- -- This provides a safer replacement for @System.IO.'SIO.openBinaryTempFile'@. openBinaryTempFile ∷ - MonadCatchIO pr - ⇒ FilePath + (MonadCatchIO pr, AbsRelClass ar) + ⇒ DirPath ar → Template - → RegionT s pr ( FilePath + → RegionT s pr ( AbsFile , RegionalFileHandle ReadWriteMode (RegionT s pr) ) openBinaryTempFile = openTemp E.openBinaryTempFile @@ -1062,10 +1072,10 @@ -- This provides a safer replacement for -- @System.IO.'SIO.openTempFileWithDefaultPermissions'@. openTempFileWithDefaultPermissions ∷ - MonadCatchIO pr - ⇒ FilePath + (MonadCatchIO pr, AbsRelClass ar) + ⇒ DirPath ar → Template - → RegionT s pr ( FilePath + → RegionT s pr ( AbsFile , RegionalFileHandle ReadWriteMode (RegionT s pr) ) openTempFileWithDefaultPermissions = openTemp E.openTempFileWithDefaultPermissions @@ -1075,10 +1085,10 @@ -- This provides a safer replacement for -- @System.IO.'SIO.openBinaryTempFileWithDefaultPermissions'@. openBinaryTempFileWithDefaultPermissions ∷ - MonadCatchIO pr - ⇒ FilePath + (MonadCatchIO pr, AbsRelClass ar) + ⇒ DirPath ar → Template - → RegionT s pr ( FilePath + → RegionT s pr ( AbsFile , RegionalFileHandle ReadWriteMode (RegionT s pr) ) openBinaryTempFileWithDefaultPermissions = openTemp $ E.openBinaryTempFileWithDefaultPermissions diff --git a/safer-file-handles.cabal b/safer-file-handles.cabal --- a/safer-file-handles.cabal +++ b/safer-file-handles.cabal @@ -1,5 +1,5 @@ name: safer-file-handles -version: 0.6.1 +version: 0.7 cabal-version: >=1.6 build-type: Custom license: BSD3 @@ -10,7 +10,7 @@ stability: experimental category: System, Monadic Regions synopsis: Type-safe file handling -description: This package adds two safety features on top of the regular +description: This package adds three safety features on top of the regular @System.IO@ file handles and operations: . * Regional file handles. Files must be opened in a /region/. When @@ -25,6 +25,9 @@ impossible to read from a write-only handle or write to a read-only handle for example. . + * Type-safe filepath creation and manipulation + using the @pathtype@ package. + . The primary technique used in this package is called \"Lightweight monadic regions\" which was invented by Oleg Kiselyov and Chung-chieh Shan. See: @@ -50,10 +53,11 @@ GHC-Options: -Wall build-depends: base >= 4 && < 4.3 , base-unicode-symbols >= 0.1.1 && < 0.3 - , regions >= 0.6 && < 0.7 + , regions >= 0.6 && < 0.8 , transformers >= 0.2 && < 0.3 , MonadCatchIO-transformers >= 0.2 && < 0.3 - , explicit-iomodes >= 0.4.1 && < 0.5 + , explicit-iomodes >= 0.5 && < 0.6 + , pathtype >= 0.0.1 && < 0.6 exposed-modules: System.IO.SaferFileHandles System.IO.SaferFileHandles.Unsafe other-modules: System.IO.SaferFileHandles.Internal