System.FS.API

An abstract view over the filesystem.

Record that abstracts over the filesystem

data HasFS m h

Abstract interface for performing file I/O

User-supplied buffers

For functions that require user-supplied buffers (i.e., MutableByteArray), it is the user's responsiblity to provide buffers that are large enough. Behaviour is undefined if the I/O operations access the buffer outside it's allocated range.

Constructors

HasFS

Fields

• dumpState :: m String

  Debugging: human-readable description of file system state

• hOpen :: HasCallStack => FsPath -> OpenMode -> m (Handle h)

  Open a file

• hClose :: HasCallStack => Handle h -> m ()

  Close a file

• hIsOpen :: HasCallStack => Handle h -> m Bool

  Is the handle open?

• hSeek :: HasCallStack => Handle h -> SeekMode -> Int64 -> m ()

  Seek handle

  The offset is an Int64 rather than a Word64 because it may be negative (for use in relative positioning).

  Unlike the Posix lseek, hSeek does not return the new seek position because the value returned by Posix is rather strange and unreliable and we don't want to emulate it's behaviour.

• hGetSome :: HasCallStack => Handle h -> Word64 -> m ByteString

  Try to read n bytes from a handle

  When at the end of the file, an empty bytestring will be returned.

  The returned bytestring will typically have length n, but may be shorter in case of a partial read, see #277. However, a partial read will always return at least 1 byte, as returning 0 bytes would mean that we have reached EOF.

  Postcondition: for the length of the returned bytestring bs we have length bs >= 0 and length bs <= n.

• hGetSomeAt :: HasCallStack => Handle h -> Word64 -> AbsOffset -> m ByteString

  Same as hGetSome, but does not affect the file offset. An additional argument is used to specify the offset. This allows it to be called concurrently for the same file handle. However, the actual level of parallelism achieved depends on the implementation and the operating system: generally on Unix it will be "more parallel" than on Windows.

• hPutSome :: HasCallStack => Handle h -> ByteString -> m Word64

  Write to a handle

  The return value indicates the number of bytes written and will typically be equal to l, the length of the bytestring, but may be shorter in case of a partial write, see #277.

  If nothing can be written at all, an exception will be thrown.

  Postcondition: the return value n is n > 0 and n <= l, unless the given bytestring is empty, in which case n can be 0.

• hTruncate :: HasCallStack => Handle h -> Word64 -> m ()

  Truncate the file to the specified size

  NOTE: Only supported in append mode.

• hGetSize :: HasCallStack => Handle h -> m Word64

  Return current file size

  NOTE: This is not thread safe (changes made to the file in other threads may affect this thread).

• createDirectory :: HasCallStack => FsPath -> m ()

  Create new directory

• createDirectoryIfMissing :: HasCallStack => Bool -> FsPath -> m ()

  Create new directory if it doesn't exist.

  createDirectoryIfMissing True will also try to create all parent dirs.

• listDirectory :: HasCallStack => FsPath -> m (Set String)

  List contents of a directory

• doesDirectoryExist :: HasCallStack => FsPath -> m Bool

  Check if the path exists and is a directory

• doesFileExist :: HasCallStack => FsPath -> m Bool

  Check if the path exists and is a file

• removeDirectoryRecursive :: HasCallStack => FsPath -> m ()

  Remove the directory (which must exist) and its contents

• removeFile :: HasCallStack => FsPath -> m ()

  Remove the file (which must exist)

• renameFile :: HasCallStack => FsPath -> FsPath -> m ()

  Rename the file (which must exist) from the first path to the second path. If there is already a file at the latter path, it is replaced by the new one.

  NOTE: only works for files within the same folder.

• mkFsErrorPath :: FsPath -> FsErrorPath

  Useful for better error reporting

• unsafeToFilePath :: FsPath -> m FilePath

  Create an absolute FilePath from a relative FsPath.

  This is an escape hatch for creating absolute paths when m ~IO.

  Postcondition: Should throw an error for any m that is not IO (or for which we do not have MonadIO m).

• hGetBufSome :: HasCallStack => Handle h -> MutableByteArray (PrimState m) -> BufferOffset -> ByteCount -> m ByteCount

  Like hGetSome, but the bytes are read into a user-supplied buffer. See User-supplied buffers.

• hGetBufSomeAt :: HasCallStack => Handle h -> MutableByteArray (PrimState m) -> BufferOffset -> ByteCount -> AbsOffset -> m ByteCount

  Like hGetSomeAt, but the bytes are read into a user-supplied buffer. See User-supplied buffers.

• hPutBufSome :: HasCallStack => Handle h -> MutableByteArray (PrimState m) -> BufferOffset -> ByteCount -> m ByteCount

  Like hPutSome, but the bytes are written from a user-supplied buffer. See User-supplied buffers.

• hPutBufSomeAt :: HasCallStack => Handle h -> MutableByteArray (PrimState m) -> BufferOffset -> ByteCount -> AbsOffset -> m ByteCount

  Like hPutSome, but the bytes are written from a user-supplied buffer at a given file offset. This offset does not affect the offset stored in the file handle (see also hGetSomeAt). See User-supplied buffers.

Instances

NFData (HasFS m h)

Defined in System.FS.API

Methods

rnf :: HasFS m h -> ()

Types

module System.FS.API.Types

Opening and closing files

hClose' :: (HasCallStack, Monad m) => HasFS m h -> Handle h -> m Bool

Returns True when the handle was still open.

withFile :: (HasCallStack, MonadThrow m) => HasFS m h -> FsPath -> OpenMode -> (Handle h -> m a) -> m a

SomeHasFS

data SomeHasFS m where

It is often inconvenient to have to parameterise over h. This data type hides an existential h parameter of a HasFS.

Constructors

SomeHasFS :: Eq h => HasFS m h -> SomeHasFS m

File I/O with user-supplied buffers

newtype BufferOffset

Absolute offset into a buffer (i.e., MutableByteArray).

Can be negative, because buffer offsets can be added together to change offset positions. This is similar to plusPtr for Ptr types. However, note that reading or writing from a buffer at a negative offset leads to undefined behaviour.

Constructors

BufferOffset

Fields

• unBufferOffset :: Int

Instances

Bounded BufferOffset

Defined in System.FS.API

Methods

minBound :: BufferOffset

maxBound :: BufferOffset

Enum BufferOffset

Defined in System.FS.API

Methods

succ :: BufferOffset -> BufferOffset

pred :: BufferOffset -> BufferOffset

toEnum :: Int -> BufferOffset

fromEnum :: BufferOffset -> Int

enumFrom :: BufferOffset -> [BufferOffset]

enumFromThen :: BufferOffset -> BufferOffset -> [BufferOffset]

enumFromTo :: BufferOffset -> BufferOffset -> [BufferOffset]

enumFromThenTo :: BufferOffset -> BufferOffset -> BufferOffset -> [BufferOffset]

Num BufferOffset

Defined in System.FS.API

Methods

(+) :: BufferOffset -> BufferOffset -> BufferOffset

(-) :: BufferOffset -> BufferOffset -> BufferOffset

(*) :: BufferOffset -> BufferOffset -> BufferOffset

negate :: BufferOffset -> BufferOffset

abs :: BufferOffset -> BufferOffset

signum :: BufferOffset -> BufferOffset

fromInteger :: Integer -> BufferOffset

Show BufferOffset

Defined in System.FS.API

Methods

showsPrec :: Int -> BufferOffset -> ShowS

show :: BufferOffset -> String

showList :: [BufferOffset] -> ShowS

Eq BufferOffset

Defined in System.FS.API

Methods

(==) :: BufferOffset -> BufferOffset -> Bool

(/=) :: BufferOffset -> BufferOffset -> Bool

Ord BufferOffset

Defined in System.FS.API

Methods

compare :: BufferOffset -> BufferOffset -> Ordering

(<) :: BufferOffset -> BufferOffset -> Bool

(<=) :: BufferOffset -> BufferOffset -> Bool

(>) :: BufferOffset -> BufferOffset -> Bool

(>=) :: BufferOffset -> BufferOffset -> Bool

max :: BufferOffset -> BufferOffset -> BufferOffset

min :: BufferOffset -> BufferOffset -> BufferOffset

hGetBufExactly

Arguments

:: forall m h. (HasCallStack, MonadThrow m)

=> HasFS m h

-> Handle h

-> MutableByteArray (PrimState m)

Buffer to read bytes into

-> BufferOffset

Offset into buffer

-> ByteCount

The number of bytes to read

-> m ByteCount

Wrapper for hGetBufSome that ensures that we read exactly as many bytes as requested. If EOF is found before the requested number of bytes is read, an FsError exception is thrown.

hGetBufExactlyAt

Arguments

:: forall m h. (HasCallStack, MonadThrow m)

=> HasFS m h

-> Handle h

-> MutableByteArray (PrimState m)

Buffer to read bytes into

-> BufferOffset

Offset into buffer

-> ByteCount

The number of bytes to read

-> AbsOffset

The file offset at which to read

-> m ByteCount

Wrapper for hGetBufSomeAt that ensures that we read exactly as many bytes as requested. If EOF is found before the requested number of bytes is read, an FsError exception is thrown.

hPutBufExactly

Arguments

:: forall m h. (HasCallStack, MonadThrow m)

=> HasFS m h

-> Handle h

-> MutableByteArray (PrimState m)

Buffer to write bytes from

-> BufferOffset

Offset into buffer

-> ByteCount

The number of bytes to write

-> m ByteCount

Wrapper for hPutBufSome that ensures we write exactly as many bytes as requested.

hPutBufExactlyAt

Arguments

:: forall m h. (HasCallStack, MonadThrow m)

=> HasFS m h

-> Handle h

-> MutableByteArray (PrimState m)

Buffer to write bytes from

-> BufferOffset

Offset into buffer

-> ByteCount

The number of bytes to write

-> AbsOffset

The file offset at which to write

-> m ByteCount

Wrapper for hPutBufSomeAt that ensures we write exactly as many bytes as requested.