Data.Conduit.Binary

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

Safe Haskell | None
Language | Haskell98

Data.Conduit.Binary

Contents

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

Description

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 :: MonadResource m => FilePath -> Producer m ByteString
- sourceHandle :: MonadIO m => Handle -> Producer m ByteString
- sourceHandleUnsafe :: MonadIO m => Handle -> Source m ByteString
- sourceIOHandle :: MonadResource m => IO Handle -> Producer m ByteString
- sourceFileRange :: MonadResource m => FilePath -> Maybe Integer -> Maybe Integer -> Producer m ByteString
- sourceHandleRange :: MonadIO m => Handle -> Maybe Integer -> Maybe Integer -> Producer m ByteString
- sourceHandleRangeWithBuffer :: MonadIO m => Handle -> Maybe Integer -> Maybe Integer -> Int -> Producer m ByteString
- sinkFile :: MonadResource m => FilePath -> Consumer ByteString m ()
- sinkHandle :: MonadIO m => Handle -> Consumer ByteString m ()
- sinkIOHandle :: MonadResource m => IO Handle -> Consumer ByteString m ()
- conduitFile :: MonadResource m => FilePath -> Conduit ByteString m ByteString
- conduitHandle :: MonadIO m => Handle -> Conduit ByteString m ByteString
- sourceLbs :: Monad m => ByteString -> Producer m ByteString
- head :: Monad m => Consumer ByteString m (Maybe Word8)
- dropWhile :: Monad m => (Word8 -> Bool) -> Consumer ByteString m ()
- take :: Monad m => Int -> Consumer ByteString m ByteString
- drop :: Monad m => Int -> Consumer ByteString m ()
- sinkCacheLength :: (MonadResource m1, MonadResource m2) => Sink ByteString m1 (Word64, Source m2 ByteString)
- sinkLbs :: Monad m => Sink ByteString m ByteString
- mapM_ :: Monad m => (Word8 -> m ()) -> Consumer ByteString m ()
- isolate :: Monad m => Int -> Conduit ByteString m ByteString
- takeWhile :: Monad m => (Word8 -> Bool) -> Conduit ByteString m ByteString
- lines :: Monad m => Conduit ByteString m ByteString

# 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 :: MonadResource m => FilePath -> Producer m ByteString

Stream the contents of a file as binary data.

Since 0.3.0

sourceHandle :: MonadIO m => Handle -> Producer m ByteString

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 0.3.0

sourceHandleUnsafe :: MonadIO m => Handle -> Source m ByteString

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 1.0.12

sourceIOHandle :: MonadResource m => IO Handle -> Producer m ByteString

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 0.3.0

sourceFileRange

Arguments

:: MonadResource m |
=> FilePath |
-> Maybe Integer | Offset
-> Maybe Integer | Maximum count
-> Producer m ByteString |

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
-> Producer m ByteString |

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
-> Producer m ByteString |

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

## Sinks

sinkFile :: MonadResource m => FilePath -> Consumer ByteString m ()

Stream all incoming data to the given file.

Since 0.3.0

sinkHandle :: MonadIO m => Handle -> Consumer ByteString m ()

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

Since 0.3.0

sinkIOHandle :: MonadResource m => IO Handle -> Consumer ByteString 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 0.3.0

## Conduits

conduitFile :: MonadResource m => FilePath -> Conduit ByteString m ByteString

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 -> Conduit ByteString m ByteString

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 -> Producer m ByteString

Stream the chunks from a lazy bytestring.

Since 0.5.0

## Sinks

head :: Monad m => Consumer ByteString m (Maybe Word8)

Return the next byte from the stream, if available.

Since 0.3.0

dropWhile :: Monad m => (Word8 -> Bool) -> Consumer ByteString m ()

Ignore all bytes while the predicate returns `True`.

Since 0.3.0

take :: Monad m => Int -> Consumer ByteString m ByteString

Take the given number of bytes, if available.

Since 0.3.0

drop :: Monad m => Int -> Consumer ByteString m ()

Drop up to the given number of bytes.

Since 0.5.0

sinkCacheLength :: (MonadResource m1, MonadResource m2) => Sink ByteString m1 (Word64, Source m2 ByteString)

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 => Sink ByteString 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 ()) -> Consumer ByteString m ()

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

Since 1.0.10

## Conduits

isolate :: Monad m => Int -> Conduit ByteString m ByteString

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) -> Conduit ByteString m ByteString

Return all bytes while the predicate returns `True`.

Since 0.3.0

lines :: Monad m => Conduit ByteString m ByteString

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