-- 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.2.0.0 -- | 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 a wrapped 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. data Path a -- | Wrapped takeDirectory takeDirectory :: Path a -> Path a -- | Wrapped takeFileName takeFileName :: Path a -> Path Unrooted -- | Type to represent filepath extensions. -- -- File extensions are usually a high-level convention and in most cases -- the low-level filesystem layer is agnostic to them. newtype FileExt FileExt :: String -> FileExt -- | Wrapped <.> (<.>) :: Path a -> FileExt -> Path a infixr 7 <.> -- | Wrapped -<.> (-<.>) :: Path a -> FileExt -> Path a infixr 7 -<.> -- | Wrapped splitExtension splitExtension :: Path a -> (Path a, Maybe FileExt) -- | Wrapped splitExtensions splitExtensions :: Path a -> (Path a, Maybe FileExt) -- | Wrapped takeExtension takeExtension :: Path a -> Maybe FileExt -- | Wrapped takeExtensions takeExtensions :: Path a -> Maybe FileExt -- | Wrapped takeBaseName takeBaseName :: Path a -> Path Unrooted -- | Wrapped stripExtension stripExtension :: FileExt -> Path a -> Maybe (Path a) -- | Wrapped isExtensionOf isExtensionOf :: FileExt -> Path a -> Bool -- | Wrapped hasTrailingPathSeparator hasTrailingPathSeparator :: Path a -> Bool -- | Wrapped addTrailingPathSeparator addTrailingPathSeparator :: Path a -> Path a -- | Wrapped dropTrailingPathSeparator dropTrailingPathSeparator :: Path a -> Path a -- | Type-level tag for unrooted paths -- -- Unrooted paths need a root before they can be interpreted. data Unrooted -- | Wrapped </> -- -- The empty fragment fragment "" acts as the right-identity -- -- 
--   root / fragment "" == root
--
-- -- This is the inverse to splitFileName. () :: Path a -> Path Unrooted -> Path a infixr 5 -- | Forget a path's root -- -- NOTE: If the original Path is considered an absolute -- POSIX style FilePath, it's automatically converted to a relative -- FilePath. 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). -- -- NOTE: If the argument is considered an absolute POSIX style -- FilePath, it's automatically converted to a relative FilePath. fromUnrootedFilePath :: FilePath -> Path Unrooted -- | A path fragment (like a single directory or filename) -- -- NOTE: If the argument would be considered an absolute POSIX -- style FilePath, it's automatically converted to a relative FilePath. fragment :: String -> Path Unrooted -- | Version of fragment taking a list of fragments -- -- NOTE: If any argument would be considered an absolute POSIX -- style FilePath, it's automatically converted to a relative FilePath. fragments :: [String] -> Path Unrooted -- | Wrapped joinPath joinFragments :: [Path Unrooted] -> Path Unrooted -- | Wrapped splitDirectories splitFragments :: Path Unrooted -> [Path Unrooted] -- | Normalise Path according to POSIX rules. -- -- See documentation of normalise for details. normalise :: Path a -> Path a -- | A file system root can be interpreted as an (absolute) FilePath class FsRoot root -- | Convert a Path to an absolute native FilePath (using native style -- directory separators). -- -- This operation needs to be in IO for resolving paths with -- dynamic roots, such as CWD or HomeDir. -- -- See also makeAbsolute toAbsoluteFilePath :: FsRoot root => Path root -> IO FilePath -- | Abstract over a file system root -- -- FsPath can be constructed directly or via fromFilePath -- or fspath. data FsPath FsPath :: (Path root) -> FsPath -- | Path tag for paths rooted at the current working -- directory data CWD -- | Compatibility type-synonym -- | Deprecated: Please use CWD instead type Relative = CWD -- | Path tag for absolute paths data Absolute -- | Path tag for paths rooted at $HOME data HomeDir -- | Export absolute path to a native FilePath. -- -- This is the inverse to fromAbsoluteFilePath. toFilePath :: Path Absolute -> FilePath -- | Construct a FsPath from a native FilePath. -- -- NOTE: Native FilePaths whose first path component is a -- ~ (and not preceded by anything else) are interpreted to be -- relative to $HOME (even on non-POSIX systems). fromFilePath :: FilePath -> FsPath -- | Export filesystem path to an absolute Path -- -- See also toAbsoluteFilePath makeAbsolute :: FsPath -> IO (Path Absolute) -- | Construct Absolute path from a native FilePath. -- -- This is the inverse to toFilePath. -- -- NOTE: If the argument is not an absolute path this function -- will throw an error. fromAbsoluteFilePath :: FilePath -> Path Absolute -- | 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) -- | Wrapper around lazy readFile readLazyByteString :: FsRoot root => Path root -> IO ByteString -- | Wrapper around strict readFile readStrictByteString :: FsRoot root => Path root -> IO ByteString -- | Wrapper around lazy writeFile writeLazyByteString :: FsRoot root => Path root -> ByteString -> IO () -- | Wrapper around strict writeFile writeStrictByteString :: FsRoot root => Path root -> ByteString -> IO () -- | Wrapper around lazy appendFile appendLazyByteString :: FsRoot root => Path root -> ByteString -> IO () -- | Wrapper around strict appendFile appendStrictByteString :: FsRoot root => Path root -> ByteString -> IO () -- | Wrapper around lazy readFile readLazyText :: FsRoot root => Path root -> IO Text -- | Wrapper around strict readFile readStrictText :: FsRoot root => Path root -> IO Text -- | Wrapper around lazy writeFile writeLazyText :: FsRoot root => Path root -> Text -> IO () -- | Wrapper around strict writeFile writeStrictText :: FsRoot root => Path root -> Text -> IO () -- | Wrapper around lazy appendFile appendLazyText :: FsRoot root => Path root -> Text -> IO () -- | Wrapper around strict appendFile appendStrictText :: FsRoot root => Path root -> Text -> IO () -- | Read lazy Text from a file (using UTF-8 encoding). -- -- NOTE: Since the file is read lazily UTF-8 decoding errors are -- detected lazily as well. Such errors will result in an -- UnicodeException being thrown within the lazy Text -- stream. readLazyTextUtf8 :: FsRoot root => Path root -> IO Text -- | Read strict Text from a file (using UTF-8 encoding). -- -- NOTE: In case of UTF-8 decoding errors an -- UnicodeException will be thrown. readStrictTextUtf8 :: FsRoot root => Path root -> IO Text -- | Write lazy Text to a file (using UTF-8 encoding). The file is -- truncated to zero length before writing begins. writeLazyTextUtf8 :: FsRoot root => Path root -> Text -> IO () -- | Write strict Text to a file (using UTF-8 encoding). The file -- is truncated to zero length before writing begins. writeStrictTextUtf8 :: FsRoot root => Path root -> Text -> IO () -- | Append lazy Text to end of a file (using UTF-8 encoding). appendLazyTextUtf8 :: FsRoot root => Path root -> Text -> IO () -- | Append strict Text to end of a file (using UTF-8 encoding). appendStrictTextUtf8 :: FsRoot root => Path root -> Text -> 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 () -- | Lenses in the style of System.FilePath.Lens. module System.Path.Lens (~) :: ASetter s t (Path a) (Path a) -> (Path Unrooted) -> s -> t infixr 4 ~ (<.>~) :: ASetter s t (Path a) (Path a) -> FileExt -> s -> t infixr 4 <.>~ basename :: Lens' (Path a) (Path Unrooted) directory :: Lens' (Path a) (Path a) extension :: Lens' (Path a) (Maybe FileExt) filename :: Lens' (Path a) (Path Unrooted) -- | QuasiQuoters for Paths module System.Path.QQ -- | Quasiquoter that materialises a value with a type of one of -- -- -- -- depending on the POSIX-style path literal given. fspath :: QuasiQuoter -- | Quasiquoter for constructing Path Unrooted from -- POSIX-style path literals. unrooted :: QuasiQuoter -- | This module gives access to internals and operation which can subvert -- the type-safety of Path. module System.Path.Unsafe -- | Paths -- -- A Path is a wrapped 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' -- | Reinterpret an unrooted path (UNSAFE) -- -- This is an alias for castRoot; see comments there. rootPath :: Path Unrooted -> Path root