-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Library for representing and manipulating type-safe file paths -- -- This library provides a more type-safe version of FilePaths -- together with thin wrappers around common IO operations. -- -- This library is directly derived from hackage-security's -- Hackage.Security.Util.Path module. @package paths @version 0.1 -- | A more type-safe version of file paths -- -- This module provides the basic Path abstraction. See also -- System.Path.IO which extends this module by thin wrappers -- wrappers around common IO operations. module System.Path -- | Paths -- -- A Path is simply a FilePath with a type-level tag -- indicating where this path is rooted (relative to the current -- directory, absolute path, relative to a web domain, whatever). Most -- operations on Path are just lifted versions of the operations -- on the underlying FilePath. The tag however allows us to give a -- lot of operations a more meaningful type. For instance, it does not -- make sense to append two absolute paths together; instead, we can only -- append an unrooted path to another path. It also means we avoid bugs -- where we use one kind of path where we expect another. newtype Path a Path :: FilePath -> Path a -- | Reinterpret the root of a path -- -- This literally just changes the type-level tag; use with caution! castRoot :: Path root -> Path root' -- | Wrapped takeDirectory takeDirectory :: Path a -> Path a -- | Wrapped takeFileName takeFileName :: Path a -> String -- | Wrapped <.> (<.>) :: Path a -> String -> Path a -- | Wrapped splitExtension splitExtension :: Path a -> (Path a, String) -- | Wrapped takeExtension takeExtension :: Path a -> String -- | Type-level tag for unrooted paths -- -- Unrooted paths need a root before they can be interpreted. data Unrooted -- | Wrapped </> () :: Path a -> Path Unrooted -> Path a -- | Reinterpret an unrooted path -- -- This is an alias for castRoot; see comments there. rootPath :: Path Unrooted -> Path root -- | Forget a path's root -- -- This is an alias for castRoot; see comments there. unrootPath :: Path root -> Path Unrooted -- | Convert a relative/unrooted Path to a FilePath (using POSIX style -- directory separators). -- -- See also toAbsoluteFilePath toUnrootedFilePath :: Path Unrooted -> FilePath -- | Convert from a relative/unrooted FilePath (using POSIX style directory -- separators). fromUnrootedFilePath :: FilePath -> Path Unrooted -- | A path fragment (like a single directory or filename) fragment :: String -> Path Unrooted -- | Wrapped joinPath joinFragments :: [String] -> Path Unrooted -- | Wrapped splitDirectories splitFragments :: Path Unrooted -> [String] -- | A file system root can be interpreted as an (absolute) FilePath class FsRoot root -- | Convert a Path to an absolute FilePath (using native style directory -- separators). toAbsoluteFilePath :: FsRoot root => Path root -> IO FilePath -- | Abstract over a file system root -- -- see fromFilePath data FsPath FsPath :: (Path root) -> FsPath data Relative data Absolute data HomeDir toFilePath :: Path Absolute -> FilePath fromFilePath :: FilePath -> FsPath makeAbsolute :: FsPath -> IO (Path Absolute) fromAbsoluteFilePath :: FilePath -> Path Absolute instance GHC.Classes.Ord (System.Path.Path a) instance GHC.Classes.Eq (System.Path.Path a) instance GHC.Show.Show (System.Path.Path a) instance Control.DeepSeq.NFData (System.Path.Path a) instance System.Path.FsRoot System.Path.Relative instance System.Path.FsRoot System.Path.Absolute instance System.Path.FsRoot System.Path.HomeDir instance Control.DeepSeq.NFData System.Path.FsPath -- | This module extends System.Path (which is re-exported for -- convenience) with thin wrappers around common IO functions and is -- intended to replace imports of System.FilePath, -- -- To facilitate importing this module unqualified we also re-export some -- definitions from System.IO (importing both would likely lead to -- name clashes). module System.Path.IO -- | Wrapper around withFile withFile :: FsRoot root => Path root -> IOMode -> (Handle -> IO r) -> IO r -- | Wrapper around openBinaryTempFileWithDefaultPermissions -- -- NOTE: The caller is responsible for cleaning up the temporary file. openTempFile' :: FsRoot root => Path root -> String -> IO (Path Absolute, Handle) readLazyByteString :: FsRoot root => Path root -> IO ByteString readStrictByteString :: FsRoot root => Path root -> IO ByteString writeLazyByteString :: FsRoot root => Path root -> ByteString -> IO () writeStrictByteString :: FsRoot root => Path root -> ByteString -> IO () copyFile :: (FsRoot root, FsRoot root') => Path root -> Path root' -> IO () createDirectory :: FsRoot root => Path root -> IO () createDirectoryIfMissing :: FsRoot root => Bool -> Path root -> IO () removeDirectory :: FsRoot root => Path root -> IO () doesFileExist :: FsRoot root => Path root -> IO Bool doesDirectoryExist :: FsRoot root => Path root -> IO Bool getModificationTime :: FsRoot root => Path root -> IO UTCTime removeFile :: FsRoot root => Path root -> IO () getTemporaryDirectory :: IO (Path Absolute) -- | Return the immediate children of a directory -- -- Filters out "." and "..". getDirectoryContents :: FsRoot root => Path root -> IO [Path Unrooted] -- | Recursive traverse a directory structure -- -- Returns a set of paths relative to the directory specified. The list -- is lazily constructed, so that directories are only read when -- required. (This is also essential to ensure that this function does -- not build the entire result in memory before returning, potentially -- running out of heap.) getRecursiveContents :: FsRoot root => Path root -> IO [Path Unrooted] renameFile :: (FsRoot root, FsRoot root') => Path root -> Path root' -> IO () getCurrentDirectory :: IO (Path Absolute) -- | See openFile data IOMode :: * ReadMode :: IOMode WriteMode :: IOMode AppendMode :: IOMode ReadWriteMode :: IOMode -- | Three kinds of buffering are supported: line-buffering, -- block-buffering or no-buffering. These modes have the following -- effects. For output, items are written out, or flushed, from -- the internal buffer according to the buffer mode: -- -- -- -- An implementation is free to flush the buffer more frequently, but not -- less frequently, than specified above. The output buffer is emptied as -- soon as it has been written out. -- -- Similarly, input occurs according to the buffer mode for the handle: -- -- -- -- The default buffering mode when a handle is opened is -- implementation-dependent and may depend on the file system object -- which is attached to that handle. For most implementations, physical -- files will normally be block-buffered and terminals will normally be -- line-buffered. data BufferMode :: * -- | buffering is disabled if possible. NoBuffering :: BufferMode -- | line-buffering should be enabled if possible. LineBuffering :: BufferMode -- | block-buffering should be enabled if possible. The size of the buffer -- is n items if the argument is Just n and is -- otherwise implementation-dependent. BlockBuffering :: Maybe Int -> BufferMode -- | Haskell defines operations to read and write characters from and to -- files, represented by values of type Handle. Each value of -- this type is a handle: a record used by the Haskell run-time -- system to manage I/O with file system objects. A handle has at -- least the following properties: -- -- -- -- Most handles will also have a current I/O position indicating where -- the next input or output operation will occur. A handle is -- readable if it manages only input or both input and output; -- likewise, it is writable if it manages only output or both -- input and output. A handle is open when first allocated. Once -- it is closed it can no longer be used for either input or output, -- though an implementation cannot re-use its storage while references -- remain to it. Handles are in the Show and Eq classes. -- The string produced by showing a handle is system dependent; it should -- include enough information to identify the handle for debugging. A -- handle is equal according to == only to itself; no attempt is -- made to compare the internal state of different handles for equality. data Handle :: * -- | A mode that determines the effect of hSeek hdl mode -- i. data SeekMode :: * -- | the position of hdl is set to i. AbsoluteSeek :: SeekMode -- | the position of hdl is set to offset i from the -- current position. RelativeSeek :: SeekMode -- | the position of hdl is set to offset i from the end -- of the file. SeekFromEnd :: SeekMode -- | Computation hSetBuffering hdl mode sets the mode of -- buffering for handle hdl on subsequent reads and writes. -- -- If the buffer mode is changed from BlockBuffering or -- LineBuffering to NoBuffering, then -- -- -- -- This operation may fail with: -- -- hSetBuffering :: Handle -> BufferMode -> IO () -- | Computation hClose hdl makes handle hdl -- closed. Before the computation finishes, if hdl is writable -- its buffer is flushed as for hFlush. Performing hClose -- on a handle that has already been closed has no effect; doing so is -- not an error. All other operations on a closed handle will fail. If -- hClose fails for any reason, any further operations (apart from -- hClose) on the handle will still fail as if hdl had -- been successfully closed. hClose :: Handle -> IO () -- | For a handle hdl which attached to a physical file, -- hFileSize hdl returns the size of that file in 8-bit -- bytes. hFileSize :: Handle -> IO Integer -- | Computation hSeek hdl mode i sets the position of -- handle hdl depending on mode. The offset i -- is given in terms of 8-bit bytes. -- -- If hdl is block- or line-buffered, then seeking to a position -- which is not in the current buffer will first cause any items in the -- output buffer to be written to the device, and then cause the input -- buffer to be discarded. Some handles may not be seekable (see -- hIsSeekable), or only support a subset of the possible -- positioning operations (for instance, it may only be possible to seek -- to the end of a tape, or to a positive offset from the beginning or -- current position). It is not possible to set a negative I/O position, -- or for a physical file, an I/O position beyond the current -- end-of-file. -- -- This operation may fail with: -- -- hSeek :: Handle -> SeekMode -> Integer -> IO ()