diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 1.2.1.1 + +* Improve the docs + ## 1.2.1 * Limit support to GHC 7.0+ diff --git a/System/IO/Temp.hs b/System/IO/Temp.hs --- a/System/IO/Temp.hs +++ b/System/IO/Temp.hs @@ -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 diff --git a/temporary.cabal b/temporary.cabal --- a/temporary.cabal +++ b/temporary.cabal @@ -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)