-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | ByteString support for pipes
--   
--   This library provides <tt>pipes</tt> utilities for
--   <tt>ByteString</tt>s
@package pipes-bytestring
@version 2.1.6


-- | This module provides <tt>pipes</tt> utilities for "byte streams",
--   which are streams of strict <a>ByteString</a>s chunks. Use byte
--   streams to interact with both <a>Handle</a>s and lazy
--   <a>ByteString</a>s.
--   
--   To stream to or from <a>Handle</a>s, use <a>fromHandle</a> or
--   <a>toHandle</a>. For example, the following program copies data from
--   one file to another:
--   
--   <pre>
--   import Pipes
--   import qualified Pipes.ByteString as P
--   import System.IO
--   
--   main =
--       withFile "inFile.txt"  ReadMode  $ \hIn  -&gt;
--       withFile "outFile.txt" WriteMode $ \hOut -&gt;
--       runEffect $ P.fromHandle hIn &gt;-&gt; P.toHandle hOut
--   </pre>
--   
--   You can stream to and from <a>stdin</a> and <a>stdout</a> using the
--   predefined <a>stdin</a> and <a>stdout</a> pipes, like in the following
--   "echo" program:
--   
--   <pre>
--   main = runEffect $ P.stdin &gt;-&gt; P.stdout
--   </pre>
--   
--   You can also translate pure lazy <a>ByteString</a>s to and from pipes:
--   
--   <pre>
--   import qualified Data.ByteString.Lazy.Char8 as BL
--   
--   main = runEffect $ P.fromLazy (BL.pack "Hello, world!\n") &gt;-&gt; P.stdout
--   </pre>
--   
--   In addition, this module provides many functions equivalent to lazy
--   <a>ByteString</a> functions so that you can transform or fold byte
--   streams. For example, to stream only the first three lines of
--   <a>stdin</a> to <a>stdout</a> you would write:
--   
--   <pre>
--   import Lens.Family (over)
--   import Pipes
--   import qualified Pipes.ByteString as PB
--   import Pipes.Group (takes)
--   
--   main = runEffect $ over PB.lines (takes 3) PB.stdin &gt;-&gt; PB.stdout
--   </pre>
--   
--   The above program will never bring more than one chunk (~ 32 KB) into
--   memory, no matter how long the lines are.
--   
--   Note that functions in this library are designed to operate on streams
--   that are insensitive to chunk boundaries. This means that they may
--   freely split chunks into smaller chunks and <i>discard empty
--   chunks</i>. However, they will <i>never concatenate chunks</i> in
--   order to provide strict upper bounds on memory usage.
module Pipes.ByteString

-- | Convert a lazy <a>ByteString</a> into a <a>Producer</a> of strict
--   <a>ByteString</a>s
fromLazy :: Monad m => ByteString -> Producer' ByteString m ()

-- | Stream bytes from <a>stdin</a>
stdin :: MonadIO m => Producer' ByteString m ()

-- | Convert a <a>Handle</a> into a byte stream using a default chunk size
fromHandle :: MonadIO m => Handle -> Producer' ByteString m ()

-- | Convert a handle into a byte stream using a maximum chunk size
--   
--   <a>hGetSome</a> forwards input immediately as it becomes available,
--   splitting the input into multiple chunks if it exceeds the maximum
--   chunk size.
hGetSome :: MonadIO m => Int -> Handle -> Producer' ByteString m ()

-- | Convert a handle into a byte stream using a fixed chunk size
--   
--   Similar to <a>hGet</a> except that it will never block waiting for
--   data to become available.
hGetNonBlocking :: MonadIO m => Int -> Handle -> Producer' ByteString m ()

-- | Convert a handle into a byte stream using a fixed chunk size
--   
--   <a>hGet</a> waits until exactly the requested number of bytes are
--   available for each chunk.
hGet :: MonadIO m => Int -> Handle -> Producer' ByteString m ()

-- | Like <a>hGet</a> but with an extra parameter specifying an initial
--   handle offset
hGetRange :: MonadIO m => Int -> Int -> Handle -> Producer' ByteString m ()

-- | Like <a>hGetSome</a>, except you can vary the maximum chunk size for
--   each request
hGetSomeN :: MonadIO m => Handle -> Int -> Server' Int ByteString m ()

-- | Like <a>hGet</a>, except you can vary the chunk size for each request
hGetN :: MonadIO m => Handle -> Int -> Server' Int ByteString m ()

-- | Stream bytes to <a>stdout</a>
--   
--   Unlike <a>toHandle</a>, <a>stdout</a> gracefully terminates on a
--   broken output pipe.
stdout :: MonadIO m => Consumer' ByteString m ()

-- | Convert a byte stream into a <tt>Handle</tt>
--   
--   <pre>
--   p &gt;-&gt; toHandle handle = for p (liftIO . hPutStr handle)
--   </pre>
toHandle :: MonadIO m => Handle -> Consumer' ByteString m r

-- | Apply a transformation to each <a>Word8</a> in the stream
map :: Monad m => (Word8 -> Word8) -> Pipe ByteString ByteString m r

-- | Map a function over the byte stream and concatenate the results
concatMap :: Monad m => (Word8 -> ByteString) -> Pipe ByteString ByteString m r

-- | <tt>(take n)</tt> only allows <tt>n</tt> bytes to pass
take :: (Monad m, Integral n) => n -> Pipe ByteString ByteString m ()

-- | Take bytes until they fail the predicate
takeWhile :: Monad m => (Word8 -> Bool) -> Pipe ByteString ByteString m ()

-- | Only allows <a>Word8</a>s to pass if they satisfy the predicate
filter :: Monad m => (Word8 -> Bool) -> Pipe ByteString ByteString m r

-- | Stream all indices whose elements match the given <a>Word8</a>
elemIndices :: (Monad m, Num n) => Word8 -> Pipe ByteString n m r

-- | Stream all indices whose elements satisfy the given predicate
findIndices :: (Monad m, Num n) => (Word8 -> Bool) -> Pipe ByteString n m r

-- | Strict left scan over the bytes
scan :: Monad m => (Word8 -> Word8 -> Word8) -> Word8 -> Pipe ByteString ByteString m r

-- | Fold a pure <a>Producer</a> of strict <a>ByteString</a>s into a lazy
--   <a>ByteString</a>
toLazy :: Producer ByteString Identity () -> ByteString

-- | Fold an effectful <a>Producer</a> of strict <a>ByteString</a>s into a
--   lazy <a>ByteString</a>
--   
--   Note: <a>toLazyM</a> is not an idiomatic use of <tt>pipes</tt>, but I
--   provide it for simple testing purposes. Idiomatic <tt>pipes</tt> style
--   consumes the chunks immediately as they are generated instead of
--   loading them all into memory.
toLazyM :: Monad m => Producer ByteString m () -> m ByteString

-- | Fold an effectful <a>Producer</a> of strict <a>ByteString</a>s into a
--   lazy <a>ByteString</a> alongside the return value
--   
--   Note: <a>toLazyM'</a> is not an idiomatic use of <tt>pipes</tt>, but I
--   provide it for simple testing purposes. Idiomatic <tt>pipes</tt> style
--   consumes the chunks immediately as they are generated instead of
--   loading them all into memory.
toLazyM' :: Monad m => Producer ByteString m a -> m (ByteString, a)

-- | Reduce the stream of bytes using a strict left fold
--   
--   Note: It's more efficient to use folds from
--   <tt>Control.Foldl.ByteString</tt> in conjunction with
--   <tt>Pipes.Prelude.<a>fold</a></tt> when possible
foldBytes :: Monad m => (x -> Word8 -> x) -> x -> (x -> r) -> Producer ByteString m () -> m r

-- | Retrieve the first <a>Word8</a>
head :: Monad m => Producer ByteString m () -> m (Maybe Word8)

-- | Retrieve the last <a>Word8</a>
last :: Monad m => Producer ByteString m () -> m (Maybe Word8)

-- | Determine if the stream is empty
null :: Monad m => Producer ByteString m () -> m Bool

-- | Count the number of bytes
length :: (Monad m, Num n) => Producer ByteString m () -> m n

-- | Fold that returns whether <a>Any</a> received <a>Word8</a>s satisfy
--   the predicate
any :: Monad m => (Word8 -> Bool) -> Producer ByteString m () -> m Bool

-- | Fold that returns whether <a>All</a> received <a>Word8</a>s satisfy
--   the predicate
all :: Monad m => (Word8 -> Bool) -> Producer ByteString m () -> m Bool

-- | Return the maximum <a>Word8</a> within a byte stream
maximum :: Monad m => Producer ByteString m () -> m (Maybe Word8)

-- | Return the minimum <a>Word8</a> within a byte stream
minimum :: Monad m => Producer ByteString m () -> m (Maybe Word8)

-- | Determine whether any element in the byte stream matches the given
--   <a>Word8</a>
elem :: Monad m => Word8 -> Producer ByteString m () -> m Bool

-- | Determine whether all elements in the byte stream do not match the
--   given <a>Word8</a>
notElem :: Monad m => Word8 -> Producer ByteString m () -> m Bool

-- | Find the first element in the stream that matches the predicate
find :: Monad m => (Word8 -> Bool) -> Producer ByteString m () -> m (Maybe Word8)

-- | Index into a byte stream
index :: (Monad m, Integral n) => n -> Producer ByteString m () -> m (Maybe Word8)

-- | Find the index of an element that matches the given <a>Word8</a>
elemIndex :: (Monad m, Num n) => Word8 -> Producer ByteString m () -> m (Maybe n)

-- | Store the first index of an element that satisfies the predicate
findIndex :: (Monad m, Num n) => (Word8 -> Bool) -> Producer ByteString m () -> m (Maybe n)

-- | Store a tally of how many elements match the given <a>Word8</a>
count :: (Monad m, Num n) => Word8 -> Producer ByteString m () -> m n

-- | Consume the first byte from a byte stream
--   
--   <a>next</a> either fails with a <a>Left</a> if the <a>Producer</a> has
--   no more bytes or succeeds with a <a>Right</a> providing the next byte
--   and the remainder of the <a>Producer</a>.
nextByte :: Monad m => Producer ByteString m r -> m (Either r (Word8, Producer ByteString m r))

-- | Draw one <a>Word8</a> from the underlying <a>Producer</a>, returning
--   <a>Nothing</a> if the <a>Producer</a> is empty
drawByte :: Monad m => Parser ByteString m (Maybe Word8)

-- | Push back a <a>Word8</a> onto the underlying <a>Producer</a>
unDrawByte :: Monad m => Word8 -> Parser ByteString m ()

-- | <a>peekByte</a> checks the first <a>Word8</a> in the stream, but uses
--   <a>unDrawByte</a> to push the <a>Word8</a> back
--   
--   <pre>
--   peekByte = do
--       x &lt;- drawByte
--       case x of
--           Nothing -&gt; return ()
--           Just w8 -&gt; unDrawByte w8
--       return x
--   </pre>
peekByte :: Monad m => Parser ByteString m (Maybe Word8)

-- | Check if the underlying <a>Producer</a> has no more bytes
--   
--   Note that this will skip over empty <a>ByteString</a> chunks, unlike
--   <a>isEndOfInput</a> from <tt>pipes-parse</tt>.
--   
--   <pre>
--   isEndOfBytes = liftM isNothing peekByte
--   </pre>
isEndOfBytes :: Monad m => Parser ByteString m Bool

-- | Improper lens that splits a <a>Producer</a> after the given number of
--   bytes
splitAt :: (Monad m, Integral n) => n -> Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | Improper lens that splits after the longest consecutive group of bytes
--   that satisfy the given predicate
span :: Monad m => (Word8 -> Bool) -> Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | Improper lens that splits after the longest consecutive group of bytes
--   that fail the given predicate
break :: Monad m => (Word8 -> Bool) -> Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | Improper lens that splits at the first occurrence of the pattern.
breakOn :: Monad m => ByteString -> Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | Improper lens that splits after the first group of matching bytes, as
--   defined by the given equality predicate
groupBy :: Monad m => (Word8 -> Word8 -> Bool) -> Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | Like <a>groupBy</a>, where the equality predicate is (<a>==</a>)
group :: Monad m => Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | Improper lens that splits a <a>Producer</a> after the first word
--   
--   Unlike <a>words</a>, this does not drop leading whitespace
--   
--   Note: This function is purely for demonstration purposes since it
--   assumes a particular encoding. You should prefer the <a>Text</a>
--   equivalent of this function from the <tt>pipes-text</tt> library.
word :: Monad m => Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | Improper lens that splits a <a>Producer</a> after the first line
--   
--   Unlike <a>lines</a>, this does not consume the newline marker, which
--   is stored within the inner <a>Producer</a>
--   
--   Note: This function is purely for demonstration purposes since it
--   assumes a particular encoding. You should prefer the <a>Text</a>
--   equivalent of this function from the <tt>pipes-text</tt> library.
line :: Monad m => Lens' (Producer ByteString m x) (Producer ByteString m (Producer ByteString m x))

-- | <tt>(drop n)</tt> drops the first <tt>n</tt> bytes
drop :: (Monad m, Integral n) => n -> Producer ByteString m r -> Producer ByteString m r

-- | Drop bytes until they fail the predicate
dropWhile :: Monad m => (Word8 -> Bool) -> Producer ByteString m r -> Producer ByteString m r

-- | Intersperse a <a>Word8</a> in between the bytes of the byte stream
intersperse :: Monad m => Word8 -> Producer ByteString m r -> Producer ByteString m r

-- | Improper lens from unpacked <a>Word8</a>s to packaged
--   <a>ByteString</a>s
pack :: Monad m => Lens' (Producer Word8 m x) (Producer ByteString m x)

-- | Improper lens from packed <a>ByteString</a>s to unpacked <a>Word8</a>s
unpack :: Monad m => Lens' (Producer ByteString m x) (Producer Word8 m x)

-- | Group byte stream chunks into chunks of fixed length
--   
--   Note: This is the <i>only</i> function in this API that concatenates
--   <a>ByteString</a> chunks, which requires allocating new
--   <a>ByteString</a>s
chunksOf' :: (Monad m, Integral n) => n -> Producer ByteString m r -> Producer ByteString m r

-- | Split a byte stream into <a>FreeT</a>-delimited byte streams of fixed
--   size
chunksOf :: (Monad m, Integral n) => n -> Lens' (Producer ByteString m x) (FreeT (Producer ByteString m) m x)

-- | Split a byte stream into groups separated by bytes that satisfy the
--   predicate
splitsWith :: Monad m => (Word8 -> Bool) -> Producer ByteString m x -> FreeT (Producer ByteString m) m x

-- | Split a byte stream into groups separated by the given byte
splits :: Monad m => Word8 -> Lens' (Producer ByteString m x) (FreeT (Producer ByteString m) m x)

-- | Split a byte stream into groups separated by the given
--   <a>ByteString</a>
splitOn :: Monad m => ByteString -> Lens' (Producer ByteString m x) (FreeT (Producer ByteString m) m x)

-- | Isomorphism between a byte stream and groups of identical bytes using
--   the supplied equality predicate
groupsBy :: Monad m => (Word8 -> Word8 -> Bool) -> Lens' (Producer ByteString m x) (FreeT (Producer ByteString m) m x)

-- | Like <a>groupsBy</a>, where the equality predicate is (<a>==</a>)
groups :: Monad m => Lens' (Producer ByteString m x) (FreeT (Producer ByteString m) m x)

-- | Improper lens between a bytestream and its lines
--   
--   Note: This function is purely for demonstration purposes since it
--   assumes a particular encoding. You should prefer the <a>Text</a>
--   equivalent of this function from the <tt>pipes-text</tt> library.
lines :: Monad m => Lens' (Producer ByteString m x) (FreeT (Producer ByteString m) m x)

-- | Improper lens between lines and a bytestream
--   
--   Note: This function is purely for demonstration purposes since it
--   assumes a particular encoding. You should prefer the <a>Text</a>
--   equivalent of this function from the <tt>pipes-text</tt> library.
unlines :: Monad m => Lens' (FreeT (Producer ByteString m) m x) (Producer ByteString m x)

-- | Convert a bytestream to delimited words
--   
--   Note: This function is purely for demonstration purposes since it
--   assumes a particular encoding. You should prefer the <a>Text</a>
--   equivalent of this function from the <tt>pipes-text</tt> library.
words :: Monad m => Producer ByteString m x -> FreeT (Producer ByteString m) m x

-- | Convert delimited words back to a byte stream
--   
--   Note: This function is purely for demonstration purposes since it
--   assumes a particular encoding. You should prefer the <a>Text</a>
--   equivalent of this function from the <tt>pipes-text</tt> library.
unwords :: Monad m => FreeT (Producer ByteString m) m x -> Producer ByteString m x
data ByteString
data Word8

-- | Join a <a>FreeT</a>-delimited stream of <a>Producer</a>s into a single
--   <a>Producer</a> by intercalating a <a>Producer</a> in between them
--   
--   <pre>
--   intercalates :: Monad m =&gt; <a>Producer</a> a m () -&gt; Joiner a m x
--   </pre>
intercalates :: forall (m :: Type -> Type) a x. Monad m => Producer a m () -> FreeT (Producer a m) m x -> Producer a m x

-- | Join a <a>FreeT</a>-delimited stream of <a>Producer</a>s into a single
--   <a>Producer</a>
--   
--   <pre>
--   concats :: Monad m =&gt; Joiner a m x
--   </pre>
concats :: forall (m :: Type -> Type) a x. Monad m => FreeT (Producer a m) m x -> Producer a m x
data FreeT (f :: Type -> Type) (m :: Type -> Type) a

-- | A <a>Parser</a> is an action that reads from and writes to a stored
--   <a>Producer</a>
type Parser a (m :: Type -> Type) r = forall x. () => StateT Producer a m x m r
