temporary 1.2.1 → 1.2.1.1
raw patch · 3 files changed
+49/−41 lines, 3 files
Files
- CHANGELOG.md +4/−0
- System/IO/Temp.hs +42/−40
- temporary.cabal +3/−1
CHANGELOG.md view
@@ -1,3 +1,7 @@+## 1.2.1.1++* Improve the docs+ ## 1.2.1 * Limit support to GHC 7.0+
System/IO/Temp.hs view
@@ -12,6 +12,20 @@ -- -- The action inside 'withTempFile' or 'withTempDirectory' is allowed to -- remove the temporary file/directory if it needs to.+--+-- == Templates and file names+--+-- The treatment of templates differs somewhat for files vs directories.+--+-- For files, the template has form @name.ext@, and a random number will be+-- placed between between the name and the extension to yield a unique file+-- name, e.g. @name1804289383846930886.ext@.+--+-- For directories, no extension is recognized, so a number will be simply+-- appended to the end of the template. Moreover, the number will be+-- smaller, as it is derived from the current process's PID+-- (but the result is still a unique directory name). So, for instance,+-- the directory template @dir@ may result in a directory named @dir30112@. module System.IO.Temp ( withSystemTempFile, withSystemTempDirectory, withTempFile, withTempDirectory,@@ -41,12 +55,14 @@ import qualified System.Posix #endif --- | Create and use a temporary file in the system standard temporary directory.+-- | Create, open, and use a temporary file in the system standard temporary directory. --+-- The temp file is deleted after use.+-- -- Behaves exactly the same as 'withTempFile', except that the parent temporary directory -- will be that returned by 'getCanonicalTemporaryDirectory'. withSystemTempFile :: (MonadIO m, MC.MonadMask m) =>- String -- ^ File name template. See 'openTempFile'.+ String -- ^ File name template -> (FilePath -> Handle -> m a) -- ^ Callback that can use the file -> m a withSystemTempFile template action = liftIO getCanonicalTemporaryDirectory >>= \tmpDir -> withTempFile tmpDir template action@@ -56,24 +72,18 @@ -- Behaves exactly the same as 'withTempDirectory', except that the parent temporary directory -- will be that returned by 'getCanonicalTemporaryDirectory'. withSystemTempDirectory :: (MonadIO m, MC.MonadMask m) =>- String -- ^ Directory name template. See 'openTempFile'.+ String -- ^ Directory name template -> (FilePath -> m a) -- ^ Callback that can use the directory -> m a withSystemTempDirectory template action = liftIO getCanonicalTemporaryDirectory >>= \tmpDir -> withTempDirectory tmpDir template action --- | Use a temporary filename that doesn't already exist.------ Creates a new temporary file inside the given directory, making use of the--- template. The temp file is deleted after use. For example:------ > withTempFile "src" "sdist." $ \tmpFile hFile -> do ...+-- | Create, open, and use a temporary file in the given directory. ----- The @tmpFile@ will be file in the given directory, e.g.--- @src/sdist.342@.+-- The temp file is deleted after use. withTempFile :: (MonadIO m, MC.MonadMask m) =>- FilePath -- ^ Temp dir to create the file in- -> String -- ^ File name template. See 'openTempFile'.+ FilePath -- ^ Parent directory to create the file in+ -> String -- ^ File name template -> (FilePath -> Handle -> m a) -- ^ Callback that can use the file -> m a withTempFile tmpDir template action =@@ -82,18 +92,12 @@ (\(name, handle) -> liftIO (hClose handle >> ignoringIOErrors (removeFile name))) (uncurry action) --- | Create and use a temporary directory.------ Creates a new temporary directory inside the given directory, making use--- of the template. The temp directory is deleted after use. For example:------ > withTempDirectory "src" "sdist." $ \tmpDir -> do ...+-- | Create and use a temporary directory inside the given directory. ----- The @tmpDir@ will be a new subdirectory of the given directory, e.g.--- @src/sdist.342@.+-- The directory is deleted after use. withTempDirectory :: (MC.MonadMask m, MonadIO m) =>- FilePath -- ^ Temp directory to create the directory in- -> String -- ^ Directory name template. See 'openTempFile'.+ FilePath -- ^ Parent directory to create the directory in+ -> String -- ^ Directory name template -> (FilePath -> m a) -- ^ Callback that can use the directory -> m a withTempDirectory targetDir template =@@ -101,17 +105,15 @@ (liftIO (createTempDirectory targetDir template)) (liftIO . ignoringIOErrors . removeDirectoryRecursive) - -- | Create a unique new file, write (text mode) a given data string to it, -- and close the handle again. The file will not be deleted automatically,--- and only the current user will have permission to access the file--- (see `openTempFile` for details).+-- and only the current user will have permission to access the file. -- -- @since 1.2.1-writeTempFile :: FilePath -- ^ Directory in which to create the file- -> String -- ^ File name template.- -> String -- ^ Data to store in the file.- -> IO FilePath -- ^ Path to the (written and closed) file.+writeTempFile :: FilePath -- ^ Parent directory to create the file in+ -> String -- ^ File name template+ -> String -- ^ Data to store in the file+ -> IO FilePath -- ^ Path to the (written and closed) file writeTempFile targetDir template content = MC.bracket (openTempFile targetDir template) (\(_, handle) -> hClose handle)@@ -120,9 +122,9 @@ -- | Like 'writeTempFile', but use the system directory for temporary files. -- -- @since 1.2.1-writeSystemTempFile :: String -- ^ File name template.- -> String -- ^ Data to store in the file.- -> IO FilePath -- ^ Path to the (written and closed) file.+writeSystemTempFile :: String -- ^ File name template+ -> String -- ^ Data to store in the file+ -> IO FilePath -- ^ Path to the (written and closed) file writeSystemTempFile template content = getCanonicalTemporaryDirectory >>= \tmpDir -> writeTempFile tmpDir template content @@ -130,9 +132,9 @@ -- This is useful if the actual content is provided by an external process. -- -- @since 1.2.1-emptyTempFile :: FilePath -- ^ Directory in which to create the file- -> String -- ^ File name template.- -> IO FilePath -- ^ Path to the (written and closed) file.+emptyTempFile :: FilePath -- ^ Parent directory to create the file in+ -> String -- ^ File name template+ -> IO FilePath -- ^ Path to the (written and closed) file emptyTempFile targetDir template = MC.bracket (openTempFile targetDir template) (\(_, handle) -> hClose handle)@@ -141,8 +143,8 @@ -- | Like 'emptyTempFile', but use the system directory for temporary files. -- -- @since 1.2.1-emptySystemTempFile :: String -- ^ File name template.- -> IO FilePath -- ^ Path to the (written and closed) file.+emptySystemTempFile :: String -- ^ File name template+ -> IO FilePath -- ^ Path to the (written and closed) file emptySystemTempFile template = getCanonicalTemporaryDirectory >>= \tmpDir -> emptyTempFile tmpDir template @@ -157,9 +159,9 @@ openNewBinaryFile :: FilePath -> String -> IO (FilePath, Handle) openNewBinaryFile = openBinaryTempFileWithDefaultPermissions --- | Create a temporary directory. See 'withTempDirectory'.+-- | Create a temporary directory. createTempDirectory- :: FilePath -- ^ Temp directory to create the directory in+ :: FilePath -- ^ Parent directory to create the directory in -> String -- ^ Directory name template -> IO FilePath createTempDirectory dir template = do
temporary.cabal view
@@ -1,5 +1,5 @@ name: temporary-version: 1.2.1+version: 1.2.1.1 cabal-version: >= 1.10 synopsis: Portable temporary file and directory support description: Functions for creating temporary files and directories.@@ -21,6 +21,8 @@ exposed-modules: System.IO.Temp build-depends: base >= 3 && < 10, filepath >= 1.1, directory >= 1.0, transformers >= 0.2.0.0, exceptions >= 0.6+ -- note: the transformers dependency is needed for MonadIO+ -- on older GHCs; on newer ones, it is included in base. ghc-options: -Wall if !os(windows)