diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2010 Bas van Dijk +Copyright (c) 2010-2011 Bas van Dijk All rights reserved. diff --git a/NEWS b/NEWS new file mode 100644 --- /dev/null +++ b/NEWS @@ -0,0 +1,148 @@ +0.10 + +(Released on: Wed Mar 9 12:21:05 UTC 2011) + +* Switch from monad-peel to monad-control. + +* Support regional-pointers-0.6 and use its overloaded pointers. + +* Add separate type for standard handles. + +* Add FileHandle type class. + +* Overload the filehandle in operations. + + +0.9 + +(Released on: Sat Nov 6 15:57:09 UTC 2010) + +* Released at BelHac 2010! + +* Depend on regions-0.8 and regional-pointers-0.5. + +* Set the region parameter of the standard handles to RootRegion + This allows them to be used in any region + because the RootRegion is the ancestor of any region. + +* Tested with GHC-7 and base-4.3 and added hGetBufSome. + +* Use MonadPeelIO instead of MonadCatchIO. + + +0.8 + +(Released on: Sat Sep 11 14:18:20 UTC 2010) + +* Replaced Ptrs by RegionalPtrs + +* Added strictness flags to the arguments of the RegionalFileHandle data constructor + + +0.7 + +(Released on: Wed Sep 1 20:11:50 UTC 2010) + +* Use the safer Path type from the pathtype package + +* Depend on explicit-iomodes >= 0.5 && < 0.6 + + The, from explicit-iomodes imported, ReadModes and WriteModes classes + have gotten private super classes which prevents users from accidentally + defining for example: 'instance ReadModes WriteMode' + which would defeat the safety guarantees of this package. + + +0.6.1 + +(Released on: Sat Aug 14 09:20:55 UTC 2010) + +* Support explicit-iomodes-0.4.1 + Added convenience functions: + withFile', openFile', withBinaryFile' and openBinaryFile' + that open files without explicitly specifying the IOMode. + Instead the IOMode is inferred from the type of the resulting handle + + +0.6 + +(Released on: Wed Jun 16 09:11:55 UTC 2010) + +* Depend on regions >= 0.6 + (This actually changed the API) + +* Added the standard handles again. Now they work properly! + +* Renamed Control.Monad.Trans.Region.Close to Control.Monad.Trans.Region.OnExit + +* Added System.IO.SaferFileHandles.Unsafe + +* Moved the ByteString operations to their own package: safer-file-handles-bytestring + + +0.5 + +(Released on: Sun May 2 20:28:22 UTC 2010) + +* Updated dependencies + base-unicode-symbols >= 0.1.1 && < 0.3 + regions >= 0.5 && < 0.6 + transformers >= 0.2 && < 0.3 + MonadCatchIO-transformers >= 0.2 && < 0.3 + +* Updated dependency: explicit-iomodes >= 0.3 && < 0.4 + (This actually changed the API) + + +0.4 + +(Released on: Sun Feb 28 13:00:23 UTC 2010) + +* Catch IOErrors and remove the internal handle from them + +* Removed support for the standard handles + + +0.3.0.1 + +(Released on: Thu Feb 4 10:20:34 UTC 2010) + +* Depend on more compatible versions of MonadCatchIO-transformers + +* Added more documentation + +* Conditional import of *withDefaultPermissions functions + + +0.3 + +(Released on: Sat Jan 23 14:25:55 UTC 2010) + +* Make File A GADT again and parameterize it with the IOMode + +* Added support for bytestring IO + + +0.2.0.1 + +(Released on: Thu Jan 7 22:55:00 UTC 2010) + +* Only import encoding and newline stuff from System.IO if base >= 4.2 + +* Only use DefaultPermissions if base >= 4.2 + +* Removed redundant #ifdef...#endif + + +0.2 + +(Released on: Thu Jan 7 14:19:15 UTC 2010) + +* Depend on regions-0.2 + + +0.1 + +(Released on: Wed Jan 6 22:04:27 UTC 2010) + +* Initial release diff --git a/README.markdown b/README.markdown new file mode 100644 --- /dev/null +++ b/README.markdown @@ -0,0 +1,44 @@ +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 the + region terminates all opened files are automatically closed. The + main advantage of regions is that the handles to the opened files + can not be returned from the region which ensures no I/O with closed + files is possible. + +* Explicit IOModes. The regional file handles are parameterized by the + IOMode in which they were opened. All operations on handles + explicitly specify the needed IOMode. This way it is 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][1] by Oleg Kiselyov and +Chung-chieh Shan. + +This technique is implemented in the [regions] package which is +re-exported from `safer-file-handles`. + +See the [safer-file-handles-examples] package for examples how +to use this package: + + git clone git://github.com/basvandijk/safer-file-handles-examples.git + +See the [safer-file-handles-bytestring] and [safer-file-handles-text] +packages for `ByteString` / `Text` operations on regional file +handles. + +[System.IO]: http://hackage.haskell.org/packages/archive/base/latest/doc/html/System-IO.html + +[1]: http://okmij.org/ftp/Haskell/regions.html#light-weight + +[pathtype]: http://hackage.haskell.org/package/pathtype +[regions]: http://hackage.haskell.org/package/regions +[safer-file-handles-bytestring]: http://hackage.haskell.org/package/safer-file-handles-bytestring +[safer-file-handles-text]: http://hackage.haskell.org/package/safer-file-handles-text + +[safer-file-handles-examples]: https://github.com/basvandijk/safer-file-handles-examples diff --git a/System/IO/SaferFileHandles.hs b/System/IO/SaferFileHandles.hs --- a/System/IO/SaferFileHandles.hs +++ b/System/IO/SaferFileHandles.hs @@ -8,7 +8,7 @@ ------------------------------------------------------------------------------- -- | -- Module : System.IO.SaferFileHandles --- Copyright : (c) 2010 Bas van Dijk +-- Copyright : (c) 2010-2011 Bas van Dijk -- License : BSD3 (see the file LICENSE) -- Maintainer : Bas van Dijk -- @@ -39,7 +39,7 @@ -- See the @safer-file-handles-examples@ package for examples how to use this -- package: -- --- @darcs get @ +-- @git clone @ -- -- /NOTE:/ This module also provides functions from @System.IO@ which don't -- directly work with file handles like 'putStrLn' or 'getLine' for @@ -73,12 +73,13 @@ , MkIOMode(mkIOMode) -- ** Standard handles - {-| These standard handles have concrete IOModes by default which work + {-| The standard handles have concrete IOModes by default which work for the majority of cases. In the rare occasion that you know these - handles have different IOModes you can 'cast' them. + handles have different IOModes you can safely 'cast' them + to the expected IOMode. - Note that these handles are pure values. This means they don't perform the - side-effect of registering a finalizer like @hClose stdin@ in the + Note that these handles are pure values. This means they don't perform + side-effects like registering finalizers like @hClose stdin@ in the 'RegionT' monad. Finally note that the region parameter of the handles is set to @@ -247,7 +248,7 @@ import Data.Bool ( Bool(..) ) import Data.Function ( ($) ) import Data.Functor ( fmap ) -import Data.Char ( Char, String ) +import Data.Char ( Char ) import Data.Int ( Int ) import Data.Maybe ( Maybe ) import Text.Show ( Show ) @@ -260,6 +261,12 @@ import Control.Monad ( fail ) #endif +#if MIN_VERSION_base(4,4,0) +import Data.String ( String ) +#else +import Data.Char ( String ) +#endif + #ifdef __HADDOCK__ import System.IO.Error #endif @@ -273,6 +280,7 @@ -- from regions: import Control.Monad.Trans.Region -- ( re-exported entirely ) import Control.Monad.Trans.Region.OnExit ( onExit ) +import Control.Monad.Trans.Region.Unsafe ( unsafeLiftIOOp_ ) -- from explicit-iomodes import System.IO.ExplicitIOModes ( IO @@ -340,11 +348,11 @@ import Control.Monad.IO.Control ( MonadControlIO ) #if MIN_VERSION_base(4,3,0) -import Control.Exception.Control ( mask_ ) +import Control.Exception ( mask_ ) #else -import Control.Exception.Control ( block ) +import Control.Exception ( block ) -mask_ ∷ MonadControlIO m ⇒ m a → m a +mask_ ∷ IO a → IO a mask_ = block #endif @@ -438,7 +446,7 @@ → RegionT s pr (RegionalFileHandle ioMode (RegionT s pr)) ) -openNormal open = \filePath ioMode → mask_ $ do +openNormal open = \filePath ioMode → unsafeLiftIOOp_ mask_ $ do h ← liftIO $ open (getPathString filePath) ioMode ch ← onExit $ sanitizeIOError $ hClose h return $ RegionalFileHandle h ch @@ -1146,7 +1154,7 @@ , RegionalFileHandle ReadWriteMode (RegionT s pr) ) ) -openTemp open = \dirPath template → mask_ $ do +openTemp open = \dirPath template → unsafeLiftIOOp_ mask_ $ do (fp, h) ← liftIO $ open (getPathString dirPath) (getPathString template) ch ← onExit $ sanitizeIOError $ hClose h return (asAbsFile fp, RegionalFileHandle h ch) diff --git a/System/IO/SaferFileHandles/Internal.hs b/System/IO/SaferFileHandles/Internal.hs --- a/System/IO/SaferFileHandles/Internal.hs +++ b/System/IO/SaferFileHandles/Internal.hs @@ -7,7 +7,7 @@ -------------------------------------------------------------------------------- -- | -- Module : System.IO.SaferFileHandles.Internal --- Copyright : (c) 2010 Bas van Dijk +-- Copyright : (c) 2010-2011 Bas van Dijk -- License : BSD3 (see the file LICENSE) -- Maintainer : Bas van Dijk -- diff --git a/System/IO/SaferFileHandles/Unsafe.hs b/System/IO/SaferFileHandles/Unsafe.hs --- a/System/IO/SaferFileHandles/Unsafe.hs +++ b/System/IO/SaferFileHandles/Unsafe.hs @@ -3,7 +3,7 @@ -------------------------------------------------------------------------------- -- | -- Module : System.IO.SaferFileHandles.Unsafe --- Copyright : (c) 2010 Bas van Dijk +-- Copyright : (c) 2010-2011 Bas van Dijk -- License : BSD3 (see the file LICENSE) -- Maintainer : Bas van Dijk -- diff --git a/safer-file-handles.cabal b/safer-file-handles.cabal --- a/safer-file-handles.cabal +++ b/safer-file-handles.cabal @@ -1,12 +1,14 @@ name: safer-file-handles -version: 0.10 +version: 0.10.0.1 cabal-version: >=1.6 build-type: Custom license: BSD3 license-file: LICENSE -copyright: 2010 Bas van Dijk +copyright: 2010-2011 Bas van Dijk author: Bas van Dijk maintainer: Bas van Dijk +homepage: https://github.com/basvandijk/safer-file-handles/ +bug-reports: https://github.com/basvandijk/safer-file-handles/issues stability: experimental category: System, Monadic Regions synopsis: Type-safe file handling @@ -40,20 +42,22 @@ See the @safer-file-handles-examples@ package for examples how to use this package: . - @darcs get @ + @git clone @ . See the @safer-file-handles-bytestring/text@ package for @ByteString/Text@ operations on regional file handles. +extra-source-files: README.markdown, NEWS + source-repository head - Type: darcs - Location: http://code.haskell.org/~basvandijk/code/safer-file-handles + Type: git + Location: git://github.com/basvandijk/safer-file-handles.git Library GHC-Options: -Wall - build-depends: base >= 4 && < 4.4 + build-depends: base >= 4 && < 4.5 , base-unicode-symbols >= 0.1.1 && < 0.3 - , regions >= 0.9 && < 0.10 + , regions >= 0.10 && < 0.11 , transformers >= 0.2 && < 0.3 , monad-control >= 0.2 && < 0.3 , explicit-iomodes >= 0.5 && < 0.7