Safe Haskell | None |
---|---|
Language | Haskell98 |
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.
- 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
- withSourceFile :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM i ByteString n () -> m a) -> m a
- sinkFile :: MonadResource m => FilePath -> Consumer ByteString m ()
- sinkFileCautious :: MonadResource m => FilePath -> ConduitM ByteString o m ()
- sinkTempFile :: MonadResource m => FilePath -> String -> ConduitM ByteString o m FilePath
- sinkSystemTempFile :: MonadResource m => String -> ConduitM ByteString o m FilePath
- sinkHandle :: MonadIO m => Handle -> Consumer ByteString m ()
- sinkIOHandle :: MonadResource m => IO Handle -> Consumer ByteString m ()
- sinkHandleBuilder :: MonadIO m => Handle -> ConduitM Builder o m ()
- sinkHandleFlush :: MonadIO m => Handle -> ConduitM (Flush ByteString) o m ()
- withSinkFile :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a
- withSinkFileBuilder :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM Builder o n () -> m a) -> m a
- withSinkFileCautious :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a
- 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 ()
- sinkStorable :: (Monad m, Storable a) => Consumer ByteString m (Maybe a)
- sinkStorableEx :: (MonadThrow m, Storable a) => Consumer ByteString m a
- 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 Source #
Stream the contents of a file as binary data.
Since 0.3.0
sourceHandle :: MonadIO m => Handle -> Producer m ByteString Source #
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 Source #
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 Source #
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
:: 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
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 Source #
:: 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
withSourceFile :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM i ByteString n () -> m a) -> m a Source #
Like withBinaryFile
, but provides a source to read bytes from.
Since: 1.2.1
Sinks
sinkFile :: MonadResource m => FilePath -> Consumer ByteString m () Source #
Stream all incoming data to the given file.
Since 0.3.0
sinkFileCautious :: MonadResource m => FilePath -> ConduitM ByteString o m () Source #
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: 1.1.14
:: 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: 1.1.15
:: 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: 1.1.15
sinkHandle :: MonadIO m => Handle -> Consumer ByteString m () Source #
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 0.3.0
sinkIOHandle :: MonadResource m => IO Handle -> Consumer ByteString m () Source #
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
sinkHandleFlush :: MonadIO m => Handle -> ConduitM (Flush ByteString) o m () Source #
Stream incoming Flush
es, executing them on IO.Handle
Note that this function does not automatically close the Handle
when
processing completes
Since: 1.2.2
withSinkFile :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a Source #
Like withBinaryFile
, but provides a sink to write bytes to.
Since: 1.2.1
withSinkFileBuilder :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM Builder o n () -> m a) -> m a Source #
Same as withSinkFile
, but lets you use a Builder
.
Since: 1.2.1
withSinkFileCautious :: (MonadUnliftIO m, MonadIO n) => FilePath -> (ConduitM ByteString o n () -> m a) -> m a Source #
Like sinkFileCautious
, but uses the with
pattern instead of
MonadResource
.
Since: 1.2.2
Conduits
conduitFile :: MonadResource m => FilePath -> Conduit ByteString m ByteString Source #
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 Source #
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 Source #
Stream the chunks from a lazy bytestring.
Since 0.5.0
Sinks
head :: Monad m => Consumer ByteString m (Maybe Word8) Source #
Return the next byte from the stream, if available.
Since 0.3.0
dropWhile :: Monad m => (Word8 -> Bool) -> Consumer ByteString m () Source #
Ignore all bytes while the predicate returns True
.
Since 0.3.0
take :: Monad m => Int -> Consumer ByteString m ByteString Source #
Take the given number of bytes, if available.
Since 0.3.0
drop :: Monad m => Int -> Consumer ByteString m () Source #
Drop up to the given number of bytes.
Since 0.5.0
sinkCacheLength :: (MonadResource m1, MonadResource m2) => Sink ByteString m1 (Word64, Source m2 ByteString) Source #
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 Source #
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 () Source #
Perform a computation on each Word8
in a stream.
Since 1.0.10
Storable
sinkStorable :: (Monad m, Storable a) => Consumer ByteString m (Maybe a) Source #
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) => Consumer ByteString m a Source #
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 -> Conduit ByteString m ByteString Source #
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 Source #
Return all bytes while the predicate returns True
.
Since 0.3.0
lines :: Monad m => Conduit ByteString m ByteString Source #
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