Modulefs-api-0.4.0.0Haskell2010

System.FS.API

An abstract view over the filesystem.

Contents

Record that abstracts over the filesystem
Types
Opening and closing files
SomeHasFS
File I/O with user-supplied buffers

Synopsis

data HasFS
value hClose'
value withFile
data SomeHasFS
newtype BufferOffset
value hGetBufExactly
value hGetBufExactlyAt
value hPutBufExactly
value hPutBufExactlyAt

Packagefs-api-0.4.0.0
Exports9
LanguageHaskell2010
LicenceApache-2.0
SourceAPI.hs

Record that abstracts over the filesystem

datadata HasFS (m :: Type -> Type) h

Source#

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
- 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.

Instances1NFData

NFData (HasFS m h)Defined in fs-api-0.4.0.0 · System.FS.API

Types

module System.FS.API.Types

Opening and closing files

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

Source#

Returns True when the handle was still open.

valuewithFile

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

SomeHasFS

datadata SomeHasFS (m :: Type -> Type) where

Source#

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

newtypenewtype BufferOffset

Source#

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
- unBufferOffset :: Int

Instances6Bounded, Enum, Eq, Num, Ord, Show

Bounded BufferOffsetDefined in fs-api-0.4.0.0 · System.FS.API
Enum BufferOffsetDefined in fs-api-0.4.0.0 · System.FS.API
Eq BufferOffsetDefined in fs-api-0.4.0.0 · System.FS.API
Num BufferOffsetDefined in fs-api-0.4.0.0 · System.FS.API
Ord BufferOffsetDefined in fs-api-0.4.0.0 · System.FS.API
Show BufferOffsetDefined in fs-api-0.4.0.0 · System.FS.API

valuehGetBufExactly

:: (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

Source#

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.

valuehGetBufExactlyAt

:: (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

Source#

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.

valuehPutBufExactly

:: (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

Source#

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

valuehPutBufExactlyAt

:: (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

Source#

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