conduit-extra-1.3.6: Batteries included conduit: adapters for common libraries.

Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.Conduit.Binary

Contents

- Files and `Handle`s
  - Sources
  - Sinks
  - Conduits
- Utilities
  - Sources
  - Sinks
    - Storable
  - Conduits

Description

NOTE It is recommended to start using Data.Conduit.Combinators instead of this module.

Functions for interacting with bytes.

For many purposes, it's recommended to use the conduit-combinators library, which provides a more complete set of functions.

Synopsis

- sourceFile :: forall (m :: Type -> Type) i. MonadResource m => FilePath -> ConduitT i ByteString m ()
- sourceHandle :: forall (m :: Type -> Type) i. MonadIO m => Handle -> ConduitT i ByteString m ()
- sourceHandleUnsafe :: forall (m :: Type -> Type) i. MonadIO m => Handle -> ConduitT i ByteString m ()
- sourceIOHandle :: forall (m :: Type -> Type) i. MonadResource m => IO Handle -> ConduitT i ByteString m ()
- sourceFileRange :: MonadResource m => FilePath -> Maybe Integer -> Maybe Integer -> ConduitT i ByteString m ()
- sourceHandleRange :: MonadIO m => Handle -> Maybe Integer -> Maybe Integer -> ConduitT i ByteString m ()
- sourceHandleRangeWithBuffer :: MonadIO m => Handle -> Maybe Integer -> Maybe Integer -> Int -> ConduitT i ByteString m ()
- withSourceFile :: forall m (n :: Type -> Type) i a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM i ByteString n () -> m a) -> m a
- sinkFile :: forall (m :: Type -> Type) o. MonadResource m => FilePath -> ConduitT ByteString o m ()
- sinkFileCautious :: forall (m :: Type -> Type) o. MonadResource m => FilePath -> ConduitM ByteString o m ()
- sinkTempFile :: forall (m :: Type -> Type) o. MonadResource m => FilePath -> String -> ConduitM ByteString o m FilePath
- sinkSystemTempFile :: forall (m :: Type -> Type) o. MonadResource m => String -> ConduitM ByteString o m FilePath
- sinkHandle :: forall (m :: Type -> Type) o. MonadIO m => Handle -> ConduitT ByteString o m ()
- sinkIOHandle :: forall (m :: Type -> Type) o. MonadResource m => IO Handle -> ConduitT ByteString o m ()
- sinkHandleBuilder :: forall (m :: Type -> Type) o. MonadIO m => Handle -> ConduitM Builder o m ()
- sinkHandleFlush :: forall (m :: Type -> Type) o. MonadIO m => Handle -> ConduitM (Flush ByteString) o m ()
- withSinkFile :: forall m (n :: Type -> Type) o a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a
- withSinkFileBuilder :: forall m (n :: Type -> Type) o a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM Builder o n () -> m a) -> m a
- withSinkFileCautious :: forall m (n :: Type -> Type) o a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a
- conduitFile :: MonadResource m => FilePath -> ConduitT ByteString ByteString m ()
- conduitHandle :: MonadIO m => Handle -> ConduitT ByteString ByteString m ()
- sourceLbs :: Monad m => ByteString -> ConduitT i ByteString m ()
- head :: Monad m => ConduitT ByteString o m (Maybe Word8)
- dropWhile :: Monad m => (Word8 -> Bool) -> ConduitT ByteString o m ()
- take :: Monad m => Int -> ConduitT ByteString o m ByteString
- drop :: Monad m => Int -> ConduitT ByteString o m ()
- sinkCacheLength :: (MonadResource m1, MonadResource m2) => ConduitT ByteString o m1 (Word64, ConduitT i ByteString m2 ())
- sinkLbs :: Monad m => ConduitT ByteString o m ByteString
- mapM_ :: Monad m => (Word8 -> m ()) -> ConduitT ByteString o m ()
- sinkStorable :: (Monad m, Storable a) => ConduitT ByteString o m (Maybe a)
- sinkStorableEx :: (MonadThrow m, Storable a) => ConduitT ByteString o m a
- isolate :: Monad m => Int -> ConduitT ByteString ByteString m ()
- takeWhile :: Monad m => (Word8 -> Bool) -> ConduitT ByteString ByteString m ()
- lines :: Monad m => ConduitT ByteString ByteString m ()

# Files and `Handle`s

Note that most of these functions live in the `MonadResource` monad to ensure resource finalization even in the presence of exceptions. In order to run such code, you will need to use `runResourceT`.

## Sources

sourceFile :: forall (m :: Type -> Type) i. MonadResource m => FilePath -> ConduitT i ByteString m () #

Stream the contents of a file as binary data.

Since: conduit-1.3.0

sourceHandle :: forall (m :: Type -> Type) i. MonadIO m => Handle -> ConduitT i ByteString m () #

Stream the contents of a `Handle` as binary data. Note that this function will not automatically close the `Handle` when processing completes, since it did not acquire the `Handle` in the first place.

Since: conduit-1.3.0

sourceHandleUnsafe :: forall (m :: Type -> Type) i. MonadIO m => Handle -> ConduitT i ByteString m () #

Same as `sourceHandle`, but instead of allocating a new buffer for each incoming chunk of data, reuses the same buffer. Therefore, the `ByteString`s yielded by this function are not referentially transparent between two different `yield`s.

This function will be slightly more efficient than `sourceHandle` by avoiding allocations and reducing garbage collections, but should only be used if you can guarantee that you do not reuse a `ByteString` (or any slice thereof) between two calls to `await`.

Since: conduit-1.3.0

sourceIOHandle :: forall (m :: Type -> Type) i. MonadResource m => IO Handle -> ConduitT i ByteString m () #

An alternative to `sourceHandle`. Instead of taking a pre-opened `Handle`, it takes an action that opens a `Handle` (in read mode), so that it can open it only when needed and close it as soon as possible.

Since: conduit-1.3.0

sourceFileRange #

Arguments

:: MonadResource m |
=> FilePath |
-> Maybe Integer | Offset
-> Maybe Integer | Maximum count
-> ConduitT i ByteString m () |

Stream the contents of a file as binary data, starting from a certain offset and only consuming up to a certain number of bytes.

Since 0.3.0

sourceHandleRange #

Arguments

:: MonadIO m |
=> Handle |
-> Maybe Integer | Offset
-> Maybe Integer | Maximum count
-> ConduitT i ByteString m () |

Stream the contents of a handle as binary data, starting from a certain offset and only consuming up to a certain number of bytes.

Since 1.0.8

sourceHandleRangeWithBuffer #

Arguments

:: MonadIO m |
=> Handle |
-> Maybe Integer | Offset
-> Maybe Integer | Maximum count
-> Int | Buffer size
-> ConduitT i ByteString m () |

Stream the contents of a handle as binary data, starting from a certain offset and only consuming up to a certain number of bytes. This function consumes chunks as specified by the buffer size.

Since 1.1.8

withSourceFile :: forall m (n :: Type -> Type) i a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM i ByteString n () -> m a) -> m a #

Like `withBinaryFile`, but provides a source to read bytes from.

Since: conduit-1.3.0

## Sinks

sinkFile :: forall (m :: Type -> Type) o. MonadResource m => FilePath -> ConduitT ByteString o m () #

Stream all incoming data to the given file.

Since: conduit-1.3.0

sinkFileCautious :: forall (m :: Type -> Type) o. MonadResource m => FilePath -> ConduitM ByteString o m () #

Cautious version of `sinkFile`. The idea here is to stream the values to a temporary file in the same directory of the destination file, and only on successfully writing the entire file, moves it atomically to the destination path.

In the event of an exception occurring, the temporary file will be deleted and no move will be made. If the application shuts down without running exception handling (such as machine failure or a SIGKILL), the temporary file will remain and the destination file will be untouched.

Since: conduit-1.3.0

sinkTempFile #

Arguments

:: forall (m :: Type -> Type) o. MonadResource m |
=> FilePath | temp directory
-> String | filename pattern
-> ConduitM ByteString o m FilePath |

Stream data into a temporary file in the given directory with the given filename pattern, and return the temporary filename. The temporary file will be automatically deleted when exiting the active `ResourceT` block, if it still exists.

Since: conduit-1.3.0

sinkSystemTempFile #

Arguments

:: forall (m :: Type -> Type) o. MonadResource m |
=> String | filename pattern
-> ConduitM ByteString o m FilePath |

Same as `sinkTempFile`, but will use the default temp file directory for the system as the first argument.

Since: conduit-1.3.0

sinkHandle :: forall (m :: Type -> Type) o. MonadIO m => Handle -> ConduitT ByteString o m () #

Stream all incoming data to the given `Handle`. Note that this function does not flush and will not close the `Handle` when processing completes.

Since: conduit-1.3.0

sinkIOHandle :: forall (m :: Type -> Type) o. MonadResource m => IO Handle -> ConduitT ByteString o m () #

An alternative to `sinkHandle`. Instead of taking a pre-opened `Handle`, it takes an action that opens a `Handle` (in write mode), so that it can open it only when needed and close it as soon as possible.

Since: conduit-1.3.0

sinkHandleBuilder :: forall (m :: Type -> Type) o. MonadIO m => Handle -> ConduitM Builder o m () #

Stream incoming builders, executing them directly on the buffer of the given `Handle`. Note that this function does not automatically close the `Handle` when processing completes. Pass `flush` to flush the buffer.

Since: conduit-1.3.0

sinkHandleFlush :: forall (m :: Type -> Type) o. MonadIO m => Handle -> ConduitM (Flush ByteString) o m () #

Stream incoming `Flush`es, executing them on `IO.Handle` Note that this function does not automatically close the `Handle` when processing completes

Since: conduit-1.3.0

withSinkFile :: forall m (n :: Type -> Type) o a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a #

Like `withBinaryFile`, but provides a sink to write bytes to.

Since: conduit-1.3.0

withSinkFileBuilder :: forall m (n :: Type -> Type) o a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM Builder o n () -> m a) -> m a #

Same as `withSinkFile`, but lets you use a `Builder`.

Since: conduit-1.3.0

withSinkFileCautious :: forall m (n :: Type -> Type) o a. (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a #

Like `sinkFileCautious`, but uses the `with` pattern instead of `MonadResource`.

Since: conduit-1.3.0

## Conduits

conduitFile :: MonadResource m => FilePath -> ConduitT ByteString ByteString m () #

Stream the contents of the input to a file, and also send it along the pipeline. Similar in concept to the Unix command `tee`.

Since 0.3.0

conduitHandle :: MonadIO m => Handle -> ConduitT ByteString ByteString m () #

Stream the contents of the input to a `Handle`, and also send it along the pipeline. Similar in concept to the Unix command `tee`. Like `sourceHandle`, does not close the handle on completion. Related to: `conduitFile`.

Since 1.0.9

# Utilities

## Sources

sourceLbs :: Monad m => ByteString -> ConduitT i ByteString m () #

Stream the chunks from a lazy bytestring.

Since 0.5.0

## Sinks

head :: Monad m => ConduitT ByteString o m (Maybe Word8) #

Return the next byte from the stream, if available.

Since 0.3.0

dropWhile :: Monad m => (Word8 -> Bool) -> ConduitT ByteString o m () #

Ignore all bytes while the predicate returns `True`.

Since 0.3.0

take :: Monad m => Int -> ConduitT ByteString o m ByteString #

Take the given number of bytes, if available.

Since 0.3.0

drop :: Monad m => Int -> ConduitT ByteString o m () #

Drop up to the given number of bytes.

Since 0.5.0

sinkCacheLength :: (MonadResource m1, MonadResource m2) => ConduitT ByteString o m1 (Word64, ConduitT i ByteString m2 ()) #

Stream the input data into a temp file and count the number of bytes present. When complete, return a new `Source` reading from the temp file together with the length of the input in bytes.

All resources will be cleaned up automatically.

Since 1.0.5

sinkLbs :: Monad m => ConduitT ByteString o m ByteString #

Consume a stream of input into a lazy bytestring. Note that no lazy I/O is performed, but rather all content is read into memory strictly.

Since 1.0.5

mapM_ :: Monad m => (Word8 -> m ()) -> ConduitT ByteString o m () #

Perform a computation on each `Word8` in a stream.

Since 1.0.10

### Storable

sinkStorable :: (Monad m, Storable a) => ConduitT ByteString o m (Maybe a) #

Consume some instance of `Storable` from the incoming byte stream. In the event of insufficient bytes in the stream, returns a `Nothing` and returns all unused input as leftovers.

Since: 1.1.13

sinkStorableEx :: (MonadThrow m, Storable a) => ConduitT ByteString o m a #

Same as `sinkStorable`, but throws a `SinkStorableInsufficientBytes` exception (via `throwM`) in the event of insufficient bytes. This can be more efficient to use than `sinkStorable` as it avoids the need to construct/deconstruct a `Maybe` wrapper in the success case.

Since: 1.1.13

## Conduits

isolate :: Monad m => Int -> ConduitT ByteString ByteString m () #

Ensure that only up to the given number of bytes are consumed by the inner sink. Note that this does not ensure that all of those bytes are in fact consumed.

Since 0.3.0

takeWhile :: Monad m => (Word8 -> Bool) -> ConduitT ByteString ByteString m () #

Return all bytes while the predicate returns `True`.

Since 0.3.0

lines :: Monad m => ConduitT ByteString ByteString m () #

Split the input bytes into lines. In other words, split on the LF byte (10), and strip it from the output.

Since 0.3.0