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


-- | Simple, composable, and easy-to-use stream I/O
--   
--   <i>Overview</i>
--   
--   The io-streams library contains simple and easy-to-use primitives for
--   I/O using streams. Most users will want to import the top-level
--   convenience module <a>System.IO.Streams</a>, which re-exports most of
--   the library:
--   
--   <pre>
--   import           System.IO.Streams (InputStream, OutputStream)
--   import qualified System.IO.Streams as Streams
--   </pre>
--   
--   For first-time users, <tt>io-streams</tt> comes with an included
--   tutorial, which can be found in the <a>System.IO.Streams.Tutorial</a>
--   module.
--   
--   <i>Features</i>
--   
--   The <tt>io-streams</tt> user API has two basic types: <tt>InputStream
--   a</tt> and <tt>OutputStream a</tt>, and three fundamental I/O
--   primitives:
--   
--   <pre>
--   -- read an item from an input stream
--   Streams.read :: InputStream a -&gt; IO (Maybe a)
--   
--   -- push an item back to an input stream
--   Streams.unRead :: a -&gt; InputStream a -&gt; IO ()
--   
--   -- write to an output stream
--   Streams.write :: Maybe a -&gt; OutputStream a -&gt; IO ()
--   </pre>
--   
--   Streams can be transformed by composition and hooked together with
--   provided combinators:
--   
--   <pre>
--   ghci&gt; Streams.fromList [1,2,3::Int] &gt;&gt;= Streams.map (*10) &gt;&gt;= Streams.toList
--   [10,20,30]
--   </pre>
--   
--   Stream composition leaves the original stream accessible:
--   
--   <pre>
--   ghci&gt; input &lt;- Streams.fromByteString "long string"
--   ghci&gt; wrapped &lt;- Streams.takeBytes 4 input
--   ghci&gt; Streams.read wrapped
--   Just "long"
--   ghci&gt; Streams.read wrapped
--   Nothing
--   ghci&gt; Streams.read input
--   Just " string"
--   </pre>
--   
--   Simple types and operations in the IO monad mean straightforward and
--   simple exception handling and resource cleanup using Haskell standard
--   library facilities like <a>Control.Exception.bracket</a>.
--   
--   <tt>io-streams</tt> comes with:
--   
--   <ul>
--   <li>functions to use files, handles, concurrent channels, sockets,
--   lists, vectors, and more as streams.</li>
--   <li>a variety of combinators for wrapping and transforming streams,
--   including compression and decompression using zlib, controlling
--   precisely how many bytes are read from or written to a stream,
--   buffering output using bytestring builders, folds, maps, filters,
--   zips, etc.</li>
--   <li>support for parsing from streams using <tt>attoparsec</tt>.</li>
--   <li>support for spawning processes and communicating with them using
--   streams.</li>
--   </ul>
@package io-streams
@version 1.5.2.2


-- | Internal implementation of the <tt>io-streams</tt> library, intended
--   for library writers
--   
--   Library users should use the interface provided by
--   <a>System.IO.Streams</a>
module System.IO.Streams.Internal

-- | A strict pair type.
data SP a b
SP :: !a -> !b -> SP a b

-- | Internal convenience synonym for a pair of input/output streams.
type StreamPair a = SP InputStream a OutputStream a

-- | An <a>InputStream</a> generates values of type <tt>c</tt> in the
--   <a>IO</a> monad.
--   
--   Two primitive operations are defined on <a>InputStream</a>:
--   
--   <ul>
--   <li><tt><a>read</a> :: <a>InputStream</a> c -&gt; <a>IO</a>
--   (<a>Maybe</a> c)</tt> reads a value from the stream, where "end of
--   stream" is signaled by <a>read</a> returning <a>Nothing</a>.</li>
--   <li><tt><a>unRead</a> :: c -&gt; <a>InputStream</a> c -&gt; <a>IO</a>
--   ()</tt> "pushes back" a value to the stream.</li>
--   </ul>
--   
--   It is intended that <a>InputStream</a>s obey the following law:
--   
--   <pre>
--   <a>unRead</a> c stream &gt;&gt; <a>read</a> stream === <a>return</a> (<a>Just</a> c)
--   </pre>
data InputStream a
InputStream :: IO (Maybe a) -> (a -> IO ()) -> InputStream a
[_read] :: InputStream a -> IO (Maybe a)
[_unRead] :: InputStream a -> a -> IO ()

-- | An <a>OutputStream</a> consumes values of type <tt>c</tt> in the
--   <a>IO</a> monad. The only primitive operation defined on
--   <a>OutputStream</a> is:
--   
--   <ul>
--   <li><pre><a>write</a> :: <a>Maybe</a> c -&gt; <a>OutputStream</a> c
--   -&gt; <a>IO</a> ()</pre></li>
--   </ul>
--   
--   Values of type <tt>c</tt> are written in an <a>OutputStream</a> by
--   wrapping them in <a>Just</a>, and the end of the stream is indicated
--   by supplying <a>Nothing</a>.
--   
--   If you supply a value after a <a>Nothing</a>, the behavior is defined
--   by the implementer of the given <a>OutputStream</a>. (All
--   <a>OutputStream</a> definitions in this library will simply discard
--   the extra input.)
data OutputStream a
OutputStream :: (Maybe a -> IO ()) -> OutputStream a
[_write] :: OutputStream a -> Maybe a -> IO ()

-- | Reads one value from an <a>InputStream</a>.
--   
--   Returns either a value wrapped in a <a>Just</a>, or <a>Nothing</a> if
--   the end of the stream is reached.
read :: InputStream a -> IO (Maybe a)

-- | Pushes a value back onto an input stream. <a>read</a> and
--   <a>unRead</a> should satisfy the following law, with the possible
--   exception of side effects:
--   
--   <pre>
--   Streams.<a>unRead</a> c stream &gt;&gt; Streams.<a>read</a> stream === <a>return</a> (<a>Just</a> c)
--   </pre>
--   
--   Note that this could be used to add values back to the stream that
--   were not originally drawn from the stream.
unRead :: a -> InputStream a -> IO ()

-- | Observes the first value from an <a>InputStream</a> without consuming
--   it.
--   
--   Returns <a>Nothing</a> if the <a>InputStream</a> is empty. <a>peek</a>
--   satisfies the following law:
--   
--   <pre>
--   Streams.<a>peek</a> stream &gt;&gt; Streams.<a>read</a> stream === Streams.<a>read</a> stream
--   </pre>
peek :: InputStream a -> IO (Maybe a)

-- | Feeds a value to an <a>OutputStream</a>. Values of type <tt>c</tt> are
--   written in an <a>OutputStream</a> by wrapping them in <a>Just</a>, and
--   the end of the stream is indicated by supplying <a>Nothing</a>.
write :: Maybe a -> OutputStream a -> IO ()

-- | Flipped version of <a>write</a>.
--   
--   <i>Since: 1.3.0.0.</i>
writeTo :: OutputStream a -> Maybe a -> IO ()

-- | Checks if an <a>InputStream</a> is at end-of-stream.
atEOF :: InputStream a -> IO Bool

-- | Creates an <a>InputStream</a> from a value-producing action.
--   
--   (<tt>makeInputStream m</tt>) calls the action <tt>m</tt> each time you
--   request a value from the <a>InputStream</a>. The given action is
--   extended with the default pushback mechanism (see
--   <a>System.IO.Streams.Internal#pushback</a>).
makeInputStream :: IO (Maybe a) -> IO (InputStream a)

-- | Creates an <a>OutputStream</a> from a value-consuming action.
--   
--   (<tt>makeOutputStream f</tt>) runs the computation <tt>f</tt> on each
--   value fed to it.
--   
--   Since version 1.2.0.0, <a>makeOutputStream</a> also ensures that
--   output streams no longer receive data once EOF is received (i.e. you
--   can now assume that makeOutputStream will feed your function
--   <tt>Nothing</tt> at most once.)
makeOutputStream :: (Maybe a -> IO ()) -> IO (OutputStream a)

-- | <a>appendInputStream</a> concatenates two <a>InputStream</a>s,
--   analogous to (<a>++</a>) for lists.
--   
--   The second <a>InputStream</a> continues where the first
--   <a>InputStream</a> ends.
--   
--   Note: values pushed back to <a>appendInputStream</a> are not
--   propagated to either wrapped <a>InputStream</a>.
appendInputStream :: InputStream a -> InputStream a -> IO (InputStream a)

-- | <a>concatInputStreams</a> concatenates a list of <a>InputStream</a>s,
--   analogous to (<a>++</a>) for lists.
--   
--   Subsequent <a>InputStream</a>s continue where the previous one
--   <a>InputStream</a> ends.
--   
--   Note: values pushed back to the <a>InputStream</a> returned by
--   <a>concatInputStreams</a> are not propagated to any of the source
--   <a>InputStream</a>s.
concatInputStreams :: [InputStream a] -> IO (InputStream a)

-- | Connects an <a>InputStream</a> and <a>OutputStream</a>, supplying
--   values from the <a>InputStream</a> to the <a>OutputStream</a>, and
--   propagating the end-of-stream message from the <a>InputStream</a>
--   through to the <a>OutputStream</a>.
--   
--   The connection ends when the <a>InputStream</a> yields a
--   <a>Nothing</a>.
connect :: InputStream a -> OutputStream a -> IO ()

-- | The <a>connectTo</a> function is just <tt><a>flip</a>
--   <a>connect</a></tt>.
--   
--   Useful for writing expressions like <tt>fromList [1,2,3] &gt;&gt;=
--   connectTo foo</tt>.
connectTo :: OutputStream a -> InputStream a -> IO ()

-- | Connects an <a>InputStream</a> to an <a>OutputStream</a> without
--   passing the end-of-stream notification through to the
--   <a>OutputStream</a>.
--   
--   Use this to supply an <a>OutputStream</a> with multiple
--   <a>InputStream</a>s and use <a>connect</a> for the final
--   <a>InputStream</a> to finalize the <a>OutputStream</a>, like so:
--   
--   <pre>
--   do Streams.<a>supply</a>  input1 output
--      Streams.<a>supply</a>  input2 output
--      Streams.<a>connect</a> input3 output
--   </pre>
supply :: InputStream a -> OutputStream a -> IO ()

-- | <a>supply</a> with the arguments flipped.
supplyTo :: OutputStream a -> InputStream a -> IO ()

-- | Converts an <a>InputStream</a> into a thread-safe <a>InputStream</a>,
--   at a slight performance penalty.
--   
--   For performance reasons, this library provides non-thread-safe streams
--   by default. Use the <tt>locking</tt> functions to convert these
--   streams into slightly slower, but thread-safe, equivalents.
lockingInputStream :: InputStream a -> IO (InputStream a)

-- | Converts an <a>OutputStream</a> into a thread-safe
--   <a>OutputStream</a>, at a slight performance penalty.
--   
--   For performance reasons, this library provides non-thread-safe streams
--   by default. Use the <tt>locking</tt> functions to convert these
--   streams into slightly slower, but thread-safe, equivalents.
lockingOutputStream :: OutputStream a -> IO (OutputStream a)

-- | An empty <a>InputStream</a> that yields <a>Nothing</a> immediately.
nullInput :: IO (InputStream a)

-- | An empty <a>OutputStream</a> that discards any input fed to it.
nullOutput :: IO (OutputStream a)

-- | A <a>Generator</a> is a coroutine monad that can be used to define
--   complex <a>InputStream</a>s. You can cause a value of type <tt>Just
--   r</tt> to appear when the <a>InputStream</a> is read by calling
--   <a>yield</a>:
--   
--   <pre>
--   g :: <a>Generator</a> Int ()
--   g = do
--       Streams.<a>yield</a> 1
--       Streams.<a>yield</a> 2
--       Streams.<a>yield</a> 3
--   </pre>
--   
--   A <a>Generator</a> can be turned into an <a>InputStream</a> by calling
--   <a>fromGenerator</a>:
--   
--   <pre>
--   m :: <a>IO</a> [<a>Int</a>]
--   m = Streams.<a>fromGenerator</a> g &gt;&gt;= Streams.<a>toList</a>     -- value returned is [1,2,3]
--   </pre>
--   
--   You can perform IO by calling <a>liftIO</a>, and turn a
--   <a>Generator</a> into an <a>InputStream</a> with <a>fromGenerator</a>.
--   
--   As a general rule, you should not acquire resources that need to be
--   freed from a <a>Generator</a>, because there is no guarantee the
--   coroutine continuation will ever be called, nor can you catch an
--   exception from within a <a>Generator</a>.
data Generator r a

-- | Turns a <a>Generator</a> into an <a>InputStream</a>.
fromGenerator :: Generator r a -> IO (InputStream r)

-- | Calling <tt><a>yield</a> x</tt> causes the value <tt><a>Just</a>
--   x</tt> to appear on the input when this generator is converted to an
--   <a>InputStream</a>. The rest of the computation after the call to
--   <a>yield</a> is resumed later when the <a>InputStream</a> is
--   <a>read</a> again.
yield :: r -> Generator r ()
data Consumer c a
fromConsumer :: Consumer r a -> IO (OutputStream r)
await :: Consumer r (Maybe r)
instance GHC.Internal.Base.Applicative (System.IO.Streams.Internal.Consumer r)
instance GHC.Internal.Base.Applicative (System.IO.Streams.Internal.Generator r)
instance GHC.Internal.IO.BufferedIO.BufferedIO (System.IO.Streams.Internal.InputStream Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.IO.BufferedIO.BufferedIO (System.IO.Streams.Internal.OutputStream Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.IO.BufferedIO.BufferedIO (System.IO.Streams.Internal.StreamPair Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.Base.Functor (System.IO.Streams.Internal.Consumer r)
instance GHC.Internal.Base.Functor (System.IO.Streams.Internal.Generator r)
instance GHC.Internal.IO.Device.IODevice (System.IO.Streams.Internal.InputStream Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.IO.Device.IODevice (System.IO.Streams.Internal.OutputStream Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.IO.Device.IODevice (System.IO.Streams.Internal.StreamPair Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.Base.Monad (System.IO.Streams.Internal.Consumer c)
instance GHC.Internal.Base.Monad (System.IO.Streams.Internal.Generator r)
instance Control.Monad.IO.Class.MonadIO (System.IO.Streams.Internal.Consumer c)
instance Control.Monad.IO.Class.MonadIO (System.IO.Streams.Internal.Generator r)
instance GHC.Internal.IO.Device.RawIO (System.IO.Streams.Internal.InputStream Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.IO.Device.RawIO (System.IO.Streams.Internal.OutputStream Data.ByteString.Internal.Type.ByteString)
instance GHC.Internal.IO.Device.RawIO (System.IO.Streams.Internal.StreamPair Data.ByteString.Internal.Type.ByteString)


-- | Input and output streams for file <a>Handle</a>s.
module System.IO.Streams.Handle

-- | Converts a read-only handle into an <a>InputStream</a> of strict
--   <a>ByteString</a>s.
--   
--   Note that the wrapped handle is <i>not</i> closed when it yields
--   end-of-stream; you can use <a>atEndOfInput</a> to close the handle if
--   you would like this behaviour.
handleToInputStream :: Handle -> IO (InputStream ByteString)

-- | Converts a writable handle into an <a>OutputStream</a> of strict
--   <a>ByteString</a>s.
--   
--   Note that the wrapped handle is <i>not</i> closed when it receives
--   end-of-stream; you can use <a>atEndOfOutput</a> to close the handle if
--   you would like this behaviour.
--   
--   <i>Note</i>: to force the <a>Handle</a> to be flushed, you can write a
--   null string to the returned <a>OutputStream</a>:
--   
--   <pre>
--   Streams.write (Just "") os
--   </pre>
handleToOutputStream :: Handle -> IO (OutputStream ByteString)

-- | Converts a readable and writable handle into an
--   <a>InputStream</a>/<a>OutputStream</a> of strict <a>ByteString</a>s.
--   
--   Note that the wrapped handle is <i>not</i> closed when it receives
--   end-of-stream; you can use <a>atEndOfOutput</a> to close the handle if
--   you would like this behaviour.
--   
--   <i>Note</i>: to force the <a>Handle</a> to be flushed, you can write a
--   null string to the returned <a>OutputStream</a>:
--   
--   <pre>
--   Streams.write (Just "") os
--   </pre>
--   
--   <i>Since: 1.3.4.0.</i>
handleToStreams :: Handle -> IO (InputStream ByteString, OutputStream ByteString)

-- | Converts an <a>InputStream</a> over bytestrings to a read-only
--   <a>Handle</a>. Note that the generated handle is opened unbuffered in
--   binary mode (i.e. no newline translation is performed).
--   
--   Note: the <a>InputStream</a> passed into this function is wrapped in
--   <a>lockingInputStream</a> to make it thread-safe.
--   
--   <i>Since: 1.0.2.0.</i>
inputStreamToHandle :: InputStream ByteString -> IO Handle

-- | Converts an <a>OutputStream</a> over bytestrings to a write-only
--   <a>Handle</a>. Note that the <a>Handle</a> will be opened in
--   non-buffering mode; if you buffer the <a>OutputStream</a> using the
--   <a>Handle</a> buffering then <tt>io-streams</tt> will copy the
--   <a>Handle</a> buffer when sending <a>ByteString</a> values to the
--   output, which might not be what you want.
--   
--   When the output buffer, if used, is flushed (using <a>hFlush</a>), an
--   empty string is written to the provided <a>OutputStream</a>.
--   
--   <i>Note</i>: the <a>OutputStream</a> passed into this function is
--   wrapped in <a>lockingOutputStream</a> to make it thread-safe.
--   
--   <i>Since: 1.0.2.0.</i>
outputStreamToHandle :: OutputStream ByteString -> IO Handle

-- | Converts a pair of <a>InputStream</a> and <a>OutputStream</a> over
--   bytestrings to a read-write <a>Handle</a>.
--   
--   Note: the streams passed into this function are wrapped in locking
--   primitives to make them thread-safe.
--   
--   <i>Since: 1.0.2.0.</i>
streamPairToHandle :: InputStream ByteString -> OutputStream ByteString -> IO Handle

-- | An <a>InputStream</a> for <a>stdin</a>.
stdin :: InputStream ByteString

-- | An <a>OutputStream</a> for <a>stdout</a>.
stdout :: OutputStream ByteString

-- | An <a>OutputStream</a> for <a>stderr</a>.
stderr :: OutputStream ByteString


-- | Input and output streams for files.
--   
--   The functions in this file use "with*" or "bracket" semantics, i.e.
--   they open the supplied <a>FilePath</a>, run a user computation, and
--   then close the file handle. If you need more control over the
--   lifecycle of the underlying file descriptor resources, you are
--   encouraged to use the functions from <a>System.IO.Streams.Handle</a>
--   instead.
module System.IO.Streams.File

-- | <tt><a>withFileAsInput</a> name act</tt> opens the specified file in
--   "read mode" and passes the resulting <a>InputStream</a> to the
--   computation <tt>act</tt>. The file will be closed on exit from
--   <tt>withFileAsInput</tt>, whether by normal termination or by raising
--   an exception.
--   
--   If closing the file raises an exception, then <i>that</i> exception
--   will be raised by <a>withFileAsInput</a> rather than any exception
--   raised by <tt>act</tt>.
withFileAsInput :: FilePath -> (InputStream ByteString -> IO a) -> IO a

-- | Like <a>withFileAsInput</a>, but seeks to the specified byte offset
--   before attaching the given file descriptor to the <a>InputStream</a>.
withFileAsInputStartingAt :: Int64 -> FilePath -> (InputStream ByteString -> IO a) -> IO a

-- | Like <a>withFileAsInputStartingAt</a>, except that the
--   <a>ByteString</a> emitted by the created <a>InputStream</a> may reuse
--   its buffer. You may only use this function if you do not retain
--   references to the generated bytestrings emitted.
unsafeWithFileAsInputStartingAt :: Int64 -> FilePath -> (InputStream ByteString -> IO a) -> IO a

-- | Open a file for writing and attaches an <a>OutputStream</a> for you to
--   write to. The file will be closed on error or completion of your
--   action.
withFileAsOutput :: FilePath -> (OutputStream ByteString -> IO a) -> IO a

-- | Like <a>withFileAsOutput</a>, but allowing you control over the output
--   file mode and buffering behaviour.
withFileAsOutputExt :: FilePath -> IOMode -> BufferMode -> (OutputStream ByteString -> IO a) -> IO a


-- | Convenience module for debugging streams. Provides stream transformers
--   that wrap <a>InputStream</a>s and <a>OutputStream</a>s, sending a
--   description of all data to an <a>OutputStream</a> for debugging.
module System.IO.Streams.Debug
debugInput :: (a -> ByteString) -> ByteString -> OutputStream ByteString -> InputStream a -> IO (InputStream a)
debugOutput :: (a -> ByteString) -> ByteString -> OutputStream ByteString -> OutputStream a -> IO (OutputStream a)
debugInputBS :: ByteString -> OutputStream ByteString -> InputStream ByteString -> IO (InputStream ByteString)
debugOutputBS :: ByteString -> OutputStream ByteString -> OutputStream ByteString -> IO (OutputStream ByteString)


-- | Core types and functions for the <tt>io-streams</tt> library.
module System.IO.Streams.Core

-- | An <a>InputStream</a> generates values of type <tt>c</tt> in the
--   <a>IO</a> monad.
--   
--   Two primitive operations are defined on <a>InputStream</a>:
--   
--   <ul>
--   <li><tt><a>read</a> :: <a>InputStream</a> c -&gt; <a>IO</a>
--   (<a>Maybe</a> c)</tt> reads a value from the stream, where "end of
--   stream" is signaled by <a>read</a> returning <a>Nothing</a>.</li>
--   <li><tt><a>unRead</a> :: c -&gt; <a>InputStream</a> c -&gt; <a>IO</a>
--   ()</tt> "pushes back" a value to the stream.</li>
--   </ul>
--   
--   It is intended that <a>InputStream</a>s obey the following law:
--   
--   <pre>
--   <a>unRead</a> c stream &gt;&gt; <a>read</a> stream === <a>return</a> (<a>Just</a> c)
--   </pre>
data InputStream a

-- | An <a>OutputStream</a> consumes values of type <tt>c</tt> in the
--   <a>IO</a> monad. The only primitive operation defined on
--   <a>OutputStream</a> is:
--   
--   <ul>
--   <li><pre><a>write</a> :: <a>Maybe</a> c -&gt; <a>OutputStream</a> c
--   -&gt; <a>IO</a> ()</pre></li>
--   </ul>
--   
--   Values of type <tt>c</tt> are written in an <a>OutputStream</a> by
--   wrapping them in <a>Just</a>, and the end of the stream is indicated
--   by supplying <a>Nothing</a>.
--   
--   If you supply a value after a <a>Nothing</a>, the behavior is defined
--   by the implementer of the given <a>OutputStream</a>. (All
--   <a>OutputStream</a> definitions in this library will simply discard
--   the extra input.)
data OutputStream a

-- | Creates an <a>InputStream</a> from a value-producing action.
--   
--   (<tt>makeInputStream m</tt>) calls the action <tt>m</tt> each time you
--   request a value from the <a>InputStream</a>. The given action is
--   extended with the default pushback mechanism (see
--   <a>System.IO.Streams.Internal#pushback</a>).
makeInputStream :: IO (Maybe a) -> IO (InputStream a)

-- | Creates an <a>OutputStream</a> from a value-consuming action.
--   
--   (<tt>makeOutputStream f</tt>) runs the computation <tt>f</tt> on each
--   value fed to it.
--   
--   Since version 1.2.0.0, <a>makeOutputStream</a> also ensures that
--   output streams no longer receive data once EOF is received (i.e. you
--   can now assume that makeOutputStream will feed your function
--   <tt>Nothing</tt> at most once.)
makeOutputStream :: (Maybe a -> IO ()) -> IO (OutputStream a)

-- | Reads one value from an <a>InputStream</a>.
--   
--   Returns either a value wrapped in a <a>Just</a>, or <a>Nothing</a> if
--   the end of the stream is reached.
read :: InputStream a -> IO (Maybe a)

-- | Pushes a value back onto an input stream. <a>read</a> and
--   <a>unRead</a> should satisfy the following law, with the possible
--   exception of side effects:
--   
--   <pre>
--   Streams.<a>unRead</a> c stream &gt;&gt; Streams.<a>read</a> stream === <a>return</a> (<a>Just</a> c)
--   </pre>
--   
--   Note that this could be used to add values back to the stream that
--   were not originally drawn from the stream.
unRead :: a -> InputStream a -> IO ()

-- | Observes the first value from an <a>InputStream</a> without consuming
--   it.
--   
--   Returns <a>Nothing</a> if the <a>InputStream</a> is empty. <a>peek</a>
--   satisfies the following law:
--   
--   <pre>
--   Streams.<a>peek</a> stream &gt;&gt; Streams.<a>read</a> stream === Streams.<a>read</a> stream
--   </pre>
peek :: InputStream a -> IO (Maybe a)

-- | Feeds a value to an <a>OutputStream</a>. Values of type <tt>c</tt> are
--   written in an <a>OutputStream</a> by wrapping them in <a>Just</a>, and
--   the end of the stream is indicated by supplying <a>Nothing</a>.
write :: Maybe a -> OutputStream a -> IO ()

-- | Flipped version of <a>write</a>.
--   
--   <i>Since: 1.3.0.0.</i>
writeTo :: OutputStream a -> Maybe a -> IO ()

-- | Checks if an <a>InputStream</a> is at end-of-stream.
atEOF :: InputStream a -> IO Bool

-- | Connects an <a>InputStream</a> and <a>OutputStream</a>, supplying
--   values from the <a>InputStream</a> to the <a>OutputStream</a>, and
--   propagating the end-of-stream message from the <a>InputStream</a>
--   through to the <a>OutputStream</a>.
--   
--   The connection ends when the <a>InputStream</a> yields a
--   <a>Nothing</a>.
connect :: InputStream a -> OutputStream a -> IO ()

-- | The <a>connectTo</a> function is just <tt><a>flip</a>
--   <a>connect</a></tt>.
--   
--   Useful for writing expressions like <tt>fromList [1,2,3] &gt;&gt;=
--   connectTo foo</tt>.
connectTo :: OutputStream a -> InputStream a -> IO ()

-- | Connects an <a>InputStream</a> to an <a>OutputStream</a> without
--   passing the end-of-stream notification through to the
--   <a>OutputStream</a>.
--   
--   Use this to supply an <a>OutputStream</a> with multiple
--   <a>InputStream</a>s and use <a>connect</a> for the final
--   <a>InputStream</a> to finalize the <a>OutputStream</a>, like so:
--   
--   <pre>
--   do Streams.<a>supply</a>  input1 output
--      Streams.<a>supply</a>  input2 output
--      Streams.<a>connect</a> input3 output
--   </pre>
supply :: InputStream a -> OutputStream a -> IO ()

-- | <a>supply</a> with the arguments flipped.
supplyTo :: OutputStream a -> InputStream a -> IO ()

-- | <a>appendInputStream</a> concatenates two <a>InputStream</a>s,
--   analogous to (<a>++</a>) for lists.
--   
--   The second <a>InputStream</a> continues where the first
--   <a>InputStream</a> ends.
--   
--   Note: values pushed back to <a>appendInputStream</a> are not
--   propagated to either wrapped <a>InputStream</a>.
appendInputStream :: InputStream a -> InputStream a -> IO (InputStream a)

-- | <a>concatInputStreams</a> concatenates a list of <a>InputStream</a>s,
--   analogous to (<a>++</a>) for lists.
--   
--   Subsequent <a>InputStream</a>s continue where the previous one
--   <a>InputStream</a> ends.
--   
--   Note: values pushed back to the <a>InputStream</a> returned by
--   <a>concatInputStreams</a> are not propagated to any of the source
--   <a>InputStream</a>s.
concatInputStreams :: [InputStream a] -> IO (InputStream a)

-- | Converts an <a>InputStream</a> into a thread-safe <a>InputStream</a>,
--   at a slight performance penalty.
--   
--   For performance reasons, this library provides non-thread-safe streams
--   by default. Use the <tt>locking</tt> functions to convert these
--   streams into slightly slower, but thread-safe, equivalents.
lockingInputStream :: InputStream a -> IO (InputStream a)

-- | Converts an <a>OutputStream</a> into a thread-safe
--   <a>OutputStream</a>, at a slight performance penalty.
--   
--   For performance reasons, this library provides non-thread-safe streams
--   by default. Use the <tt>locking</tt> functions to convert these
--   streams into slightly slower, but thread-safe, equivalents.
lockingOutputStream :: OutputStream a -> IO (OutputStream a)

-- | An empty <a>InputStream</a> that yields <a>Nothing</a> immediately.
nullInput :: IO (InputStream a)

-- | An empty <a>OutputStream</a> that discards any input fed to it.
nullOutput :: IO (OutputStream a)

-- | A <a>Generator</a> is a coroutine monad that can be used to define
--   complex <a>InputStream</a>s. You can cause a value of type <tt>Just
--   r</tt> to appear when the <a>InputStream</a> is read by calling
--   <a>yield</a>:
--   
--   <pre>
--   g :: <a>Generator</a> Int ()
--   g = do
--       Streams.<a>yield</a> 1
--       Streams.<a>yield</a> 2
--       Streams.<a>yield</a> 3
--   </pre>
--   
--   A <a>Generator</a> can be turned into an <a>InputStream</a> by calling
--   <a>fromGenerator</a>:
--   
--   <pre>
--   m :: <a>IO</a> [<a>Int</a>]
--   m = Streams.<a>fromGenerator</a> g &gt;&gt;= Streams.<a>toList</a>     -- value returned is [1,2,3]
--   </pre>
--   
--   You can perform IO by calling <a>liftIO</a>, and turn a
--   <a>Generator</a> into an <a>InputStream</a> with <a>fromGenerator</a>.
--   
--   As a general rule, you should not acquire resources that need to be
--   freed from a <a>Generator</a>, because there is no guarantee the
--   coroutine continuation will ever be called, nor can you catch an
--   exception from within a <a>Generator</a>.
data Generator r a

-- | Turns a <a>Generator</a> into an <a>InputStream</a>.
fromGenerator :: Generator r a -> IO (InputStream r)

-- | Calling <tt><a>yield</a> x</tt> causes the value <tt><a>Just</a>
--   x</tt> to appear on the input when this generator is converted to an
--   <a>InputStream</a>. The rest of the computation after the call to
--   <a>yield</a> is resumed later when the <a>InputStream</a> is
--   <a>read</a> again.
yield :: r -> Generator r ()


-- | Stream utilities for working with concurrent channels.
module System.IO.Streams.Concurrent

-- | Writes the contents of an input stream to a channel until the input
--   stream yields end-of-stream.
inputToChan :: InputStream a -> Chan (Maybe a) -> IO ()

-- | Turns a <a>Chan</a> into an input stream.
chanToInput :: Chan (Maybe a) -> IO (InputStream a)

-- | Turns a <a>Chan</a> into an output stream.
chanToOutput :: Chan (Maybe a) -> IO (OutputStream a)

-- | Concurrently merges a list of <a>InputStream</a>s, combining values in
--   the order they become available.
--   
--   Note: does <i>not</i> forward individual end-of-stream notifications,
--   the produced stream does not yield end-of-stream until all of the
--   input streams have finished.
--   
--   Any exceptions raised in one of the worker threads will be trapped and
--   re-raised in the current thread.
--   
--   If the supplied list is empty, <a>concurrentMerge</a> will return an
--   empty stream. (<i>Since: 1.5.0.1</i>)
concurrentMerge :: [InputStream a] -> IO (InputStream a)

-- | Create a new pair of streams using an underlying <a>Chan</a>.
--   Everything written to the <a>OutputStream</a> will appear as-is on the
--   <a>InputStream</a>.
--   
--   Since reading from the <a>InputStream</a> and writing to the
--   <a>OutputStream</a> are blocking calls, be sure to do so in different
--   threads.
makeChanPipe :: IO (InputStream a, OutputStream a)


-- | Generic stream manipulations
module System.IO.Streams.Combinators

-- | A side-effecting fold over an <a>InputStream</a>, as a stream
--   transformer.
--   
--   The IO action returned by <a>inputFoldM</a> can be used to fetch and
--   reset the updated seed value. Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2, 3::Int]
--   ghci&gt; (is', getSeed) &lt;- Streams.<a>inputFoldM</a> (\x y -&gt; return (x+y)) 0 is
--   ghci&gt; Streams.<a>toList</a> is'
--   [1,2,3]
--   ghci&gt; getSeed
--   6
--   </pre>
inputFoldM :: (a -> b -> IO a) -> a -> InputStream b -> IO (InputStream b, IO a)

-- | A side-effecting fold over an <a>OutputStream</a>, as a stream
--   transformer.
--   
--   The IO action returned by <a>outputFoldM</a> can be used to fetch and
--   reset the updated seed value. Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2, 3::Int]
--   ghci&gt; (os, getList) &lt;- Streams.<a>listOutputStream</a>
--   ghci&gt; (os', getSeed) &lt;- Streams.<a>outputFoldM</a> (\x y -&gt; return (x+y)) 0 os
--   ghci&gt; Streams.<a>connect</a> is os'
--   ghci&gt; getList
--   [1,2,3]
--   ghci&gt; getSeed
--   6
--   </pre>
outputFoldM :: (a -> b -> IO a) -> a -> OutputStream b -> IO (OutputStream b, IO a)

-- | A left fold over an input stream. The input stream is fully consumed.
--   See <a>foldl</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> [1..10] &gt;&gt;= Streams.<a>fold</a> (+) 0
--   55
--   </pre>
fold :: (s -> a -> s) -> s -> InputStream a -> IO s

-- | A side-effecting left fold over an input stream. The input stream is
--   fully consumed. See <a>foldl</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> [1..10] &gt;&gt;= Streams.<a>foldM</a> (x y -&gt; <a>return</a> (x + y)) 0
--   55
--   </pre>
foldM :: (s -> a -> IO s) -> s -> InputStream a -> IO s

-- | A variant of <a>fold</a> suitable for use with composable folds from
--   'beautiful folding' libraries like <a>the foldl library</a>. The input
--   stream is fully consumed.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; let folds = liftA3 (,,) Foldl.length Foldl.mean Foldl.maximum
--   ghci&gt; Streams.<a>fromList</a> [1..10::Double] &gt;&gt;= Foldl.purely Streams.<a>fold_</a> folds is
--   ghci&gt; (10,5.5,Just 10.0)
--   </pre>
--   
--   <i>Since 1.3.6.0</i>
fold_ :: (x -> a -> x) -> x -> (x -> s) -> InputStream a -> IO s

-- | A variant of <a>foldM</a> suitable for use with composable folds from
--   'beautiful folding' libraries like <a>the foldl library</a>. The input
--   stream is fully consumed.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; let folds = Foldl.mapM_ print *&gt; Foldl.generalize (liftA2 (,) Foldl.sum Foldl.mean)
--   ghci&gt; Streams.<a>fromList</a> [1..3::Double] &gt;&gt;= Foldl.impurely Streams.<a>foldM_</a> folds
--   1.0
--   2.0
--   3.0
--   (6.0,2.0)
--   </pre>
--   
--   <i>Since 1.3.6.0</i>
foldM_ :: (x -> a -> IO x) -> IO x -> (x -> IO s) -> InputStream a -> IO s

-- | <tt>any predicate stream</tt> returns <a>True</a> if any element in
--   <tt>stream</tt> matches the predicate.
--   
--   <a>any</a> consumes as few elements as possible, ending consumption if
--   an element satisfies the predicate.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2, 3]
--   ghci&gt; Streams.<a>any</a> (&gt; 0) is    -- Consumes one element
--   True
--   ghci&gt; Streams.<a>read</a> is
--   Just 2
--   ghci&gt; Streams.<a>any</a> even is     -- Only 3 remains
--   False
--   </pre>
any :: (a -> Bool) -> InputStream a -> IO Bool

-- | <tt>all predicate stream</tt> returns <a>True</a> if every element in
--   <tt>stream</tt> matches the predicate.
--   
--   <a>all</a> consumes as few elements as possible, ending consumption if
--   any element fails the predicate.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2, 3]
--   ghci&gt; Streams.<a>all</a> (&lt; 0) is    -- Consumes one element
--   False
--   ghci&gt; Streams.<a>read</a> is
--   Just 2
--   ghci&gt; Streams.<a>all</a> odd is      -- Only 3 remains
--   True
--   </pre>
all :: (a -> Bool) -> InputStream a -> IO Bool

-- | <tt>maximum stream</tt> returns the greatest element in
--   <tt>stream</tt> or <a>Nothing</a> if the stream is empty.
--   
--   <a>maximum</a> consumes the entire stream.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2, 3]
--   ghci&gt; Streams.<a>maximum</a> is
--   3
--   ghci&gt; Streams.<a>read</a> is     -- The stream is now empty
--   Nothing
--   </pre>
maximum :: Ord a => InputStream a -> IO (Maybe a)

-- | <tt>minimum stream</tt> returns the greatest element in
--   <tt>stream</tt>
--   
--   <a>minimum</a> consumes the entire stream.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2, 3]
--   ghci&gt; Streams.<a>minimum</a> is
--   1
--   ghci&gt; Streams.<a>read</a> is    -- The stream is now empty
--   Nothing
--   </pre>
minimum :: Ord a => InputStream a -> IO (Maybe a)

-- | <tt>unfoldM f seed</tt> builds an <a>InputStream</a> from successively
--   applying <tt>f</tt> to the <tt>seed</tt> value, continuing if
--   <tt>f</tt> produces <a>Just</a> and halting on <a>Nothing</a>.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>unfoldM</a> (n -&gt; return $ if n &lt; 3 then Just (n, n + 1) else Nothing) 0
--   ghci&gt; Streams.<a>toList</a> is
--   [0,1,2]
--   </pre>
unfoldM :: (b -> IO (Maybe (a, b))) -> b -> IO (InputStream a)

-- | Maps a pure function over an <a>InputStream</a>.
--   
--   <tt>map f s</tt> passes all output from <tt>s</tt> through the
--   function <tt>f</tt>.
--   
--   Satisfies the following laws:
--   
--   <pre>
--   Streams.<a>map</a> (g . f) === Streams.<a>map</a> f &gt;=&gt; Streams.<a>map</a> g
--   Streams.<a>map</a> <a>id</a> === Streams.<a>makeInputStream</a> . Streams.<a>read</a>
--   </pre>
map :: (a -> b) -> InputStream a -> IO (InputStream b)

-- | Maps an impure function over an <a>InputStream</a>.
--   
--   <tt>mapM f s</tt> passes all output from <tt>s</tt> through the IO
--   action <tt>f</tt>.
--   
--   Satisfies the following laws:
--   
--   <pre>
--   Streams.<a>mapM</a> (f &gt;=&gt; g) === Streams.<a>mapM</a> f &gt;=&gt; Streams.<a>mapM</a> g
--   Streams.<a>mapM</a> <a>return</a> === Streams.<a>makeInputStream</a> . Streams.<a>read</a>
--   </pre>
mapM :: (a -> IO b) -> InputStream a -> IO (InputStream b)

-- | Maps a side effect over an <a>InputStream</a>.
--   
--   <tt>mapM_ f s</tt> produces a new input stream that passes all output
--   from <tt>s</tt> through the side-effecting IO action <tt>f</tt>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> [1,2,3] &gt;&gt;=
--         Streams.<a>mapM_</a> (<a>putStrLn</a> . <a>show</a> . (*2)) &gt;&gt;=
--         Streams.<a>toList</a>
--   2
--   4
--   6
--   [1,2,3]
--   </pre>
mapM_ :: (a -> IO b) -> InputStream a -> IO (InputStream a)

-- | A version of map that discards elements
--   
--   <tt>mapMaybe f s</tt> passes all output from <tt>s</tt> through the
--   function <tt>f</tt> and discards elements for which <tt>f s</tt>
--   evaluates to <a>Nothing</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> [Just 1, None, Just 3] &gt;&gt;=
--         Streams.<a>mapMaybe</a> <a>id</a> &gt;&gt;=
--         Streams.<a>toList</a>
--   [1,3]
--   </pre>
--   
--   <i>Since: 1.2.1.0</i>
mapMaybe :: (a -> Maybe b) -> InputStream a -> IO (InputStream b)

-- | Contravariant counterpart to <a>map</a>.
--   
--   <tt>contramap f s</tt> passes all input to <tt>s</tt> through the
--   function <tt>f</tt>.
--   
--   Satisfies the following laws:
--   
--   <pre>
--   Streams.<a>contramap</a> (g . f) === Streams.<a>contramap</a> g &gt;=&gt; Streams.<a>contramap</a> f
--   Streams.<a>contramap</a> <a>id</a> === <a>return</a>
--   </pre>
contramap :: (a -> b) -> OutputStream b -> IO (OutputStream a)

-- | Contravariant counterpart to <a>mapM</a>.
--   
--   <tt>contramapM f s</tt> passes all input to <tt>s</tt> through the IO
--   action <tt>f</tt>
--   
--   Satisfies the following laws:
--   
--   <pre>
--   Streams.<a>contramapM</a> (f &gt;=&gt; g) = Streams.<a>contramapM</a> g &gt;=&gt; Streams.<a>contramapM</a> f
--   Streams.<a>contramapM</a> <a>return</a> = <a>return</a>
--   </pre>
contramapM :: (a -> IO b) -> OutputStream b -> IO (OutputStream a)

-- | Equivalent to <a>mapM_</a> for output.
--   
--   <tt>contramapM f s</tt> passes all input to <tt>s</tt> through the
--   side-effecting IO action <tt>f</tt>.
contramapM_ :: (a -> IO b) -> OutputStream a -> IO (OutputStream a)

-- | Contravariant counterpart to <a>contramapMaybe</a>.
--   
--   <tt>contramap f s</tt> passes all input to <tt>s</tt> through the
--   function <tt>f</tt>. Discards all the elements for which <tt>f</tt>
--   returns <a>Nothing</a>.
--   
--   <i>Since: 1.2.1.0</i>
contramapMaybe :: (a -> Maybe b) -> OutputStream b -> IO (OutputStream a)

-- | Drops chunks from an input stream if they fail to match a given filter
--   predicate. See <a>filter</a>.
--   
--   Items pushed back to the returned stream are propagated back upstream.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> ["the", "quick", "brown", "fox"] &gt;&gt;=
--         Streams.<a>filter</a> (/= "brown") &gt;&gt;= Streams.<a>toList</a>
--   ["the","quick","fox"]
--   </pre>
filter :: (a -> Bool) -> InputStream a -> IO (InputStream a)

-- | Drops chunks from an input stream if they fail to match a given filter
--   predicate. See <a>filter</a>.
--   
--   Items pushed back to the returned stream are propagated back upstream.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> ["the", "quick", "brown", "fox"] &gt;&gt;=
--         Streams.<a>filterM</a> (<a>return</a> . (/= "brown")) &gt;&gt;= Streams.<a>toList</a>
--   ["the","quick","fox"]
--   </pre>
filterM :: (a -> IO Bool) -> InputStream a -> IO (InputStream a)

-- | Filters output to be sent to the given <a>OutputStream</a> using a
--   pure function. See <a>filter</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import qualified <a>Data.ByteString.Char8</a> as S
--   ghci&gt; os1 &lt;- Streams.<a>stdout</a> &gt;&gt;= Streams.'System.IO.Streams.unlines
--   ghci&gt; os2 &lt;- os1 &gt;&gt;= Streams.<a>contramap</a> (S.pack . show) &gt;&gt;= Streams.<a>filterOutput</a> even
--   ghci&gt; Streams.<a>write</a> (Just 3) os2
--   ghci&gt; Streams.<a>write</a> (Just 4) os2
--   4
--   </pre>
filterOutput :: (a -> Bool) -> OutputStream a -> IO (OutputStream a)

-- | Filters output to be sent to the given <a>OutputStream</a> using a
--   predicate function in IO. See <a>filterM</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; let check a = putStrLn a ("Allow " ++ show a ++ "?") &gt;&gt; readLn :: IO Bool
--   ghci&gt; import qualified Data.ByteString.Char8 as S
--   ghci&gt; os1 &lt;- Streams.<a>unlines</a> Streams.<a>stdout</a>
--   ghci&gt; os2 &lt;- os1 &gt;&gt;= Streams.<a>contramap</a> (S.pack . show) &gt;&gt;= Streams.<a>filterOutputM</a> check
--   ghci&gt; Streams.<a>write</a> (Just 3) os2
--   Allow 3?
--   False&lt;Enter&gt;
--   ghci&gt; Streams.<a>write</a> (Just 4) os2
--   Allow 4?
--   True&lt;Enter&gt;
--   4
--   </pre>
filterOutputM :: (a -> IO Bool) -> OutputStream a -> IO (OutputStream a)

-- | Wraps an <a>OutputStream</a>, producing a new <a>OutputStream</a> that
--   will pass at most <tt>n</tt> items on to the wrapped stream,
--   subsequently ignoring the rest of the input.
give :: Int64 -> OutputStream a -> IO (OutputStream a)

-- | Wraps an <a>InputStream</a>, producing a new <a>InputStream</a> that
--   will produce at most <tt>n</tt> items, subsequently yielding
--   end-of-stream forever.
--   
--   Items pushed back to the returned <a>InputStream</a> will be
--   propagated upstream, modifying the count of taken items accordingly.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<tt>fromList</tt> [1..9::Int]
--   ghci&gt; is' &lt;- Streams.<a>take</a> 1 is
--   ghci&gt; Streams.<a>read</a> is'
--   Just 1
--   ghci&gt; Streams.<a>read</a> is'
--   Nothing
--   ghci&gt; Streams.<a>peek</a> is
--   Just 2
--   ghci&gt; Streams.<a>unRead</a> 11 is'
--   ghci&gt; Streams.<a>peek</a> is
--   Just 11
--   ghci&gt; Streams.<a>peek</a> is'
--   Just 11
--   ghci&gt; Streams.<a>read</a> is'
--   Just 11
--   ghci&gt; Streams.<a>read</a> is'
--   Nothing
--   ghci&gt; Streams.<a>read</a> is
--   Just 2
--   ghci&gt; Streams.<tt>toList</tt> is
--   [3,4,5,6,7,8,9]
--   </pre>
take :: Int64 -> InputStream a -> IO (InputStream a)

-- | Wraps an <a>InputStream</a>, producing a new <a>InputStream</a> that
--   will drop the first <tt>n</tt> items produced by the wrapped stream.
--   See <a>drop</a>.
--   
--   Items pushed back to the returned <a>InputStream</a> will be
--   propagated upstream, modifying the count of dropped items accordingly.
drop :: Int64 -> InputStream a -> IO (InputStream a)

-- | Wraps an <a>OutputStream</a>, producing a new <a>OutputStream</a> that
--   will ignore the first <tt>n</tt> items received, subsequently passing
--   the rest of the input on to the wrapped stream.
ignore :: Int64 -> OutputStream a -> IO (OutputStream a)

-- | Combines two input streams. Continues yielding elements from both
--   input streams until one of them finishes.
zip :: InputStream a -> InputStream b -> IO (InputStream (a, b))

-- | Combines two input streams using the supplied function. Continues
--   yielding elements from both input streams until one of them finishes.
zipWith :: (a -> b -> c) -> InputStream a -> InputStream b -> IO (InputStream c)

-- | Combines two input streams using the supplied monadic function.
--   Continues yielding elements from both input streams until one of them
--   finishes.
zipWithM :: (a -> b -> IO c) -> InputStream a -> InputStream b -> IO (InputStream c)

-- | Takes apart a stream of pairs, producing a pair of input streams.
--   Reading from either of the produced streams will cause a pair of
--   values to be pulled from the original stream if necessary. Note that
--   reading <tt>n</tt> values from one of the returned streams will cause
--   <tt>n</tt> values to be buffered at the other stream.
--   
--   Access to the original stream is thread safe, i.e. guarded by a lock.
unzip :: InputStream (a, b) -> IO (InputStream a, InputStream b)

-- | Given two <a>OutputStream</a>s, returns a new stream that "unzips" the
--   tuples being written, writing the two elements to the corresponding
--   given streams.
--   
--   You can use this together with <tt><a>contramap</a> (\ x -&gt; (x,
--   x))</tt> to "fork" a stream into two.
--   
--   <i>Since: 1.5.2.0</i>
contraunzip :: OutputStream a -> OutputStream b -> IO (OutputStream (a, b))

-- | The function <tt>intersperse v s</tt> wraps the <a>OutputStream</a>
--   <tt>s</tt>, creating a new output stream that writes its input to
--   <tt>s</tt> interspersed with the provided value <tt>v</tt>. See
--   <a>intersperse</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import Control.Monad ((&gt;=&gt;))
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["nom", "nom", "nom"::<tt>ByteString</tt>]
--   ghci&gt; Streams.<a>outputToList</a> (Streams.<a>intersperse</a> "burp!" &gt;=&gt; Streams.<a>connect</a> is)
--   ["nom","burp!","nom","burp!","nom"]
--   </pre>
intersperse :: a -> OutputStream a -> IO (OutputStream a)

-- | Drives an <a>InputStream</a> to end-of-stream, discarding all of the
--   yielded values.
skipToEof :: InputStream a -> IO ()

-- | Wraps an <a>OutputStream</a>, ignoring any end-of-stream
--   <a>Nothing</a> values written to the returned stream.
--   
--   <i>Since: 1.0.1.0</i>
ignoreEof :: OutputStream a -> IO (OutputStream a)

-- | Wraps an <a>InputStream</a>, running the specified action when the
--   stream yields end-of-file.
--   
--   <i>Since: 1.0.2.0</i>
atEndOfInput :: IO b -> InputStream a -> IO (InputStream a)

-- | Wraps an <a>OutputStream</a>, running the specified action when the
--   stream receives end-of-file.
--   
--   <i>Since: 1.0.2.0</i>
atEndOfOutput :: IO b -> OutputStream a -> IO (OutputStream a)


-- | Buffering for output streams based on bytestring builders.
--   
--   Buffering an output stream can often improve throughput by reducing
--   the number of system calls made through the file descriptor. The
--   <tt>bytestring</tt> package provides an efficient monoidal datatype
--   used for serializing values directly to an output buffer, called a
--   <a>Builder</a>, originally implemented in the <tt>blaze-builder</tt>
--   package by Simon Meier. When compiling with <tt>bytestring</tt>
--   versions older than 0.10.4, (i.e. GHC &lt;= 7.6) users must depend on
--   the <tt>bytestring-builder</tt> library to get the new builder
--   implementation. Since we try to maintain compatibility with the last
--   three GHC versions, the dependency on <tt>bytestring-builder</tt> can
--   be dropped after the release of GHC 7.12.
--   
--   <i>Using this module</i>
--   
--   Given an <a>OutputStream</a> taking <a>ByteString</a>:
--   
--   <pre>
--   someOutputStream :: OutputStream ByteString
--   </pre>
--   
--   You create a new output stream wrapping the original one that accepts
--   <a>Builder</a> values:
--   
--   <pre>
--   do
--       newStream &lt;- Streams.<a>builderStream</a> someOutputStream
--       Streams.<a>write</a> (<a>Just</a> $ <a>byteString</a> "hello") newStream
--       ....
--   </pre>
--   
--   You can flush the output buffer using <a>flush</a>:
--   
--   <pre>
--   ....
--   Streams.<a>write</a> (<a>Just</a> <a>flush</a>) newStream
--   ....
--   </pre>
--   
--   As a convention, <a>builderStream</a> will write the empty string to
--   the wrapped <a>OutputStream</a> upon a builder buffer flush. Output
--   streams which receive <a>ByteString</a> should either ignore the empty
--   string or interpret it as a signal to flush their own buffers, as the
--   <tt>handleToOutputStream</tt> and <a>System.IO.Streams.Zlib</a>
--   functions do.
--   
--   <i>Example</i>
--   
--   <pre>
--   example :: IO [ByteString]
--   example = do
--       let l1 = <a>intersperse</a> " " ["the", "quick", "brown", "fox"]
--       let l2 = <a>intersperse</a> " " ["jumped", "over", "the"]
--       let l  = map <a>byteString</a> l1 ++ [<a>flush</a>] ++ map <a>byteString</a> l2
--       is          &lt;- Streams.<a>fromList</a> l
--       (os0, grab) &lt;- Streams.<a>listOutputStream</a>
--       os          &lt;- Streams.<a>builderStream</a> os0
--       Streams.<a>connect</a> is os &gt;&gt; grab
--   
--   ghci&gt; example
--   ["the quick brown fox","","jumped over the"]
--   </pre>
module System.IO.Streams.Builder

-- | Converts a <a>ByteString</a> sink into a <a>Builder</a> sink.
--   
--   Note that if the generated builder receives a <a>flush</a>, by
--   convention it will send an empty string to the supplied
--   <tt><a>OutputStream</a> <a>ByteString</a></tt> to indicate that any
--   output buffers are to be flushed.
builderStream :: OutputStream ByteString -> IO (OutputStream Builder)

-- | Converts a <a>ByteString</a> sink into a <a>Builder</a> sink, using
--   the supplied buffer size.
--   
--   Note that if the generated builder receives a <a>flush</a>, by
--   convention it will send an empty string to the supplied
--   <tt><a>OutputStream</a> <a>ByteString</a></tt> to indicate that any
--   output buffers are to be flushed.
--   
--   <i>Since: 1.3.0.0.</i>
builderStreamWithBufferSize :: Int -> OutputStream ByteString -> IO (OutputStream Builder)

-- | Unsafe variation on <a>builderStream</a> that reuses an existing
--   buffer for efficiency.
--   
--   <i>NOTE</i>: because the buffer is reused, subsequent
--   <a>ByteString</a> values written to the wrapped <tt>OutputString</tt>
--   will cause previous yielded strings to change. Do not retain
--   references to these <a>ByteString</a> values inside the
--   <a>OutputStream</a> you pass to this function, or you will violate
--   referential transparency.
--   
--   If you <i>must</i> retain copies of these values, then please use
--   <a>copy</a> to ensure that you have a fresh copy of the underlying
--   string.
--   
--   You can create a Buffer with <a>newBuffer</a>.
unsafeBuilderStream :: IO Buffer -> OutputStream ByteString -> IO (OutputStream Builder)


-- | This module provides support for parsing values from Text
--   <a>InputStream</a>s using <tt>attoparsec</tt>. <i>Since: 1.4.0.0.</i>
module System.IO.Streams.Attoparsec.Text

-- | Supplies an <tt>attoparsec</tt> <a>Parser</a> with an
--   <a>InputStream</a>, returning the final parsed value or throwing a
--   <a>ParseException</a> if parsing fails.
--   
--   <a>parseFromStream</a> consumes only as much input as necessary to
--   satisfy the <a>Parser</a>: any unconsumed input is pushed back onto
--   the <a>InputStream</a>.
--   
--   If the <a>Parser</a> exhausts the <a>InputStream</a>, the
--   end-of-stream signal is sent to attoparsec.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Data.Attoparsec.Text</a>
--   ghci&gt; is &lt;- <a>fromList</a> ["12345xxx" :: <a>Text</a>]
--   ghci&gt; <a>parseFromStream</a> (<a>takeWhile</a> <a>isDigit</a>) is
--   "12345"
--   ghci&gt; <a>read</a> is
--   Just "xxx"
--   </pre>
parseFromStream :: Parser r -> InputStream Text -> IO r

-- | Given a <a>Parser</a> yielding values of type <tt><a>Maybe</a> r</tt>,
--   transforms an <a>InputStream</a> over byte strings to an
--   <a>InputStream</a> yielding values of type <tt>r</tt>.
--   
--   If the parser yields <tt>Just x</tt>, then <tt>x</tt> will be passed
--   along downstream, and if the parser yields <tt>Nothing</tt>, that will
--   be interpreted as end-of-stream.
--   
--   Upon a parse error, <a>parserToInputStream</a> will throw a
--   <a>ParseException</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Control.Applicative</a>
--   ghci&gt; import <a>Data.Attoparsec.Text</a>
--   ghci&gt; is &lt;- <a>fromList</a> ["1 2 3 4 5" :: <a>Text</a>]
--   ghci&gt; let parser = (<a>endOfInput</a> &gt;&gt; <a>pure</a> <a>Nothing</a>) &lt;|&gt; (Just &lt;$&gt; (<a>skipWhile</a> <a>isSpace</a> *&gt; <a>decimal</a>))
--   ghci&gt; <a>parserToInputStream</a> parser is &gt;&gt;= <a>toList</a>
--   [1,2,3,4,5]
--   ghci&gt; is' &lt;- <a>fromList</a> ["1 2xx3 4 5" :: <a>Text</a>] &gt;&gt;= <a>parserToInputStream</a> parser
--   ghci&gt; <a>read</a> is'
--   Just 1
--   ghci&gt; <a>read</a> is'
--   Just 2
--   ghci&gt; <a>read</a> is'
--   *** Exception: Parse exception: Failed reading: takeWhile1
--   </pre>
parserToInputStream :: Parser (Maybe r) -> InputStream Text -> IO (InputStream r)

-- | An exception raised when parsing fails.
data ParseException
ParseException :: String -> ParseException


-- | This module provides support for parsing values from ByteString
--   <a>InputStream</a>s using <tt>attoparsec</tt>. <i>Since: 1.4.0.0.</i>
module System.IO.Streams.Attoparsec.ByteString

-- | Supplies an <tt>attoparsec</tt> <a>Parser</a> with an
--   <a>InputStream</a>, returning the final parsed value or throwing a
--   <a>ParseException</a> if parsing fails.
--   
--   <a>parseFromStream</a> consumes only as much input as necessary to
--   satisfy the <a>Parser</a>: any unconsumed input is pushed back onto
--   the <a>InputStream</a>.
--   
--   If the <a>Parser</a> exhausts the <a>InputStream</a>, the
--   end-of-stream signal is sent to attoparsec.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Data.Attoparsec.ByteString.Char8</a>
--   ghci&gt; is &lt;- <a>fromList</a> ["12345xxx" :: <a>ByteString</a>]
--   ghci&gt; <a>parseFromStream</a> (<a>takeWhile</a> <a>isDigit</a>) is
--   "12345"
--   ghci&gt; <a>read</a> is
--   Just "xxx"
--   </pre>
parseFromStream :: Parser r -> InputStream ByteString -> IO r

-- | Given a <a>Parser</a> yielding values of type <tt><a>Maybe</a> r</tt>,
--   transforms an <a>InputStream</a> over byte strings to an
--   <a>InputStream</a> yielding values of type <tt>r</tt>.
--   
--   If the parser yields <tt>Just x</tt>, then <tt>x</tt> will be passed
--   along downstream, and if the parser yields <tt>Nothing</tt>, that will
--   be interpreted as end-of-stream.
--   
--   Upon a parse error, <a>parserToInputStream</a> will throw a
--   <a>ParseException</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Control.Applicative</a>
--   ghci&gt; import <a>Data.Attoparsec.ByteString.Char8</a>
--   ghci&gt; is &lt;- <a>fromList</a> ["1 2 3 4 5" :: <a>ByteString</a>]
--   ghci&gt; let parser = (<a>endOfInput</a> &gt;&gt; <a>pure</a> <a>Nothing</a>) &lt;|&gt; (Just &lt;$&gt; (<a>skipWhile</a> <a>isSpace</a> *&gt; <a>decimal</a>))
--   ghci&gt; <a>parserToInputStream</a> parser is &gt;&gt;= <a>toList</a>
--   [1,2,3,4,5]
--   ghci&gt; is' &lt;- <a>fromList</a> ["1 2xx3 4 5" :: <a>ByteString</a>] &gt;&gt;= <a>parserToInputStream</a> parser
--   ghci&gt; <a>read</a> is'
--   Just 1
--   ghci&gt; <a>read</a> is'
--   Just 2
--   ghci&gt; <a>read</a> is'
--   *** Exception: Parse exception: Failed reading: takeWhile1
--   </pre>
parserToInputStream :: Parser (Maybe r) -> InputStream ByteString -> IO (InputStream r)

-- | An exception raised when parsing fails.
data ParseException
ParseException :: String -> ParseException


-- | This module is deprecated -- use
--   System.IO.Streams.Attoparsec.ByteString instead (this module simply
--   re-exports that one).
module System.IO.Streams.Attoparsec

-- | Supplies an <tt>attoparsec</tt> <a>Parser</a> with an
--   <a>InputStream</a>, returning the final parsed value or throwing a
--   <a>ParseException</a> if parsing fails.
--   
--   <a>parseFromStream</a> consumes only as much input as necessary to
--   satisfy the <a>Parser</a>: any unconsumed input is pushed back onto
--   the <a>InputStream</a>.
--   
--   If the <a>Parser</a> exhausts the <a>InputStream</a>, the
--   end-of-stream signal is sent to attoparsec.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Data.Attoparsec.ByteString.Char8</a>
--   ghci&gt; is &lt;- <a>fromList</a> ["12345xxx" :: <a>ByteString</a>]
--   ghci&gt; <a>parseFromStream</a> (<a>takeWhile</a> <a>isDigit</a>) is
--   "12345"
--   ghci&gt; <a>read</a> is
--   Just "xxx"
--   </pre>
parseFromStream :: Parser r -> InputStream ByteString -> IO r

-- | Given a <a>Parser</a> yielding values of type <tt><a>Maybe</a> r</tt>,
--   transforms an <a>InputStream</a> over byte strings to an
--   <a>InputStream</a> yielding values of type <tt>r</tt>.
--   
--   If the parser yields <tt>Just x</tt>, then <tt>x</tt> will be passed
--   along downstream, and if the parser yields <tt>Nothing</tt>, that will
--   be interpreted as end-of-stream.
--   
--   Upon a parse error, <a>parserToInputStream</a> will throw a
--   <a>ParseException</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Control.Applicative</a>
--   ghci&gt; import <a>Data.Attoparsec.ByteString.Char8</a>
--   ghci&gt; is &lt;- <a>fromList</a> ["1 2 3 4 5" :: <a>ByteString</a>]
--   ghci&gt; let parser = (<a>endOfInput</a> &gt;&gt; <a>pure</a> <a>Nothing</a>) &lt;|&gt; (Just &lt;$&gt; (<a>skipWhile</a> <a>isSpace</a> *&gt; <a>decimal</a>))
--   ghci&gt; <a>parserToInputStream</a> parser is &gt;&gt;= <a>toList</a>
--   [1,2,3,4,5]
--   ghci&gt; is' &lt;- <a>fromList</a> ["1 2xx3 4 5" :: <a>ByteString</a>] &gt;&gt;= <a>parserToInputStream</a> parser
--   ghci&gt; <a>read</a> is'
--   Just 1
--   ghci&gt; <a>read</a> is'
--   Just 2
--   ghci&gt; <a>read</a> is'
--   *** Exception: Parse exception: Failed reading: takeWhile1
--   </pre>
parserToInputStream :: Parser (Maybe r) -> InputStream ByteString -> IO (InputStream r)

-- | An exception raised when parsing fails.
data ParseException
ParseException :: String -> ParseException


-- | List conversions and utilities.
module System.IO.Streams.List

-- | Transforms a list into an <a>InputStream</a> that produces no side
--   effects.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2]
--   ghci&gt; <tt>replicateM</tt> 3 (Streams.<a>read</a> is)
--   [Just 1, Just 2, Nothing]
--   </pre>
fromList :: [c] -> IO (InputStream c)

-- | Drains an <a>InputStream</a>, converting it to a list. N.B. that this
--   function reads the entire <a>InputStream</a> strictly into memory and
--   as such is not recommended for streaming applications or where the
--   size of the input is not bounded or known.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [1, 2]
--   ghci&gt; Streams.<a>toList</a> is
--   [1, 2]
--   </pre>
toList :: InputStream a -> IO [a]

-- | Given an IO action that requires an <a>OutputStream</a>, creates one
--   and captures all the output the action sends to it as a list.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Control.Applicative</a>
--   ghci&gt; (<a>connect</a> <a>$</a> <a>fromList</a> ["a", "b", "c"]) &gt;&gt;= <a>outputToList</a>
--   ["a","b","c"]
--   </pre>
outputToList :: (OutputStream a -> IO b) -> IO [a]

-- | Feeds a list to an <a>OutputStream</a>. Does <i>not</i> write an
--   end-of-stream to the stream.
--   
--   <pre>
--   ghci&gt; os &lt;- Streams.<a>unlines</a> Streams.<a>stdout</a> &gt;&gt;= Streams.<a>contramap</a> (S.pack . show) :: IO (<a>OutputStream</a> Int)
--   ghci&gt; Streams.<a>writeList</a> [1, 2] os
--   1
--   2
--   ghci&gt; Streams.<a>writeList</a> [3, 4] os
--   3
--   4
--   </pre>
writeList :: [a] -> OutputStream a -> IO ()

-- | Splits an input stream into chunks of at most size <tt>n</tt>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; <a>fromList</a> [1..14::Int] &gt;&gt;= <a>chunkList</a> 4 &gt;&gt;= <a>toList</a>
--   [[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14]]
--   </pre>
chunkList :: Int -> InputStream a -> IO (InputStream [a])

-- | Splits an input stream into chunks whenever <tt>p elt count</tt>
--   returns true.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; <a>fromList</a> [1..14::Int] &gt;&gt;= <a>chunkListWith</a> (x n -&gt; n&gt;=4) &gt;&gt;= <a>toList</a>
--   [[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14]]
--   ghci&gt; <a>fromList</a> [<tt>a</tt>..<tt>z</tt>] &gt;&gt;= <a>chunkListWith</a> (x n -&gt; n&gt;=4 &amp;&amp; x <a>elem</a> "aeiouy") &gt;&gt;= <a>toList</a>
--   ["abcde","fghi","jklmno","pqrstu","vwxy","z"]
--   </pre>
--   
--   <i>Since: 1.3.3.0.</i>
chunkListWith :: (a -> Int -> Bool) -> InputStream a -> IO (InputStream [a])

-- | Given an input stream containing lists, produces a new input stream
--   that will yield the concatenation of these lists. See <a>concat</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> [[1,2,3::Int], [4,5,6]] &gt;&gt;=
--         Streams.<a>concatLists</a> &gt;&gt;=
--         Streams.<a>toList</a>
--   [1,2,3,4,5,6]
--   </pre>
concatLists :: InputStream [a] -> IO (InputStream a)

-- | <a>listOutputStream</a> returns an <a>OutputStream</a> which stores
--   values fed into it and an action which flushes all stored values to a
--   list.
--   
--   The flush action resets the store.
--   
--   Note that this function <i>will</i> buffer any input sent to it on the
--   heap. Please don't use this unless you're sure that the amount of
--   input provided is bounded and will fit in memory without issues.
--   
--   <pre>
--   ghci&gt; (os, flush) &lt;- Streams.<a>listOutputStream</a> :: IO (<a>OutputStream</a> Int, IO [Int])
--   ghci&gt; Streams.<a>writeList</a> [1, 2] os
--   ghci&gt; flush
--   [1, 2]
--   ghci&gt; Streams.<a>writeList</a> [3, 4] os
--   ghci&gt; flush
--   [3, 4]
--   </pre>
listOutputStream :: IO (OutputStream c, IO [c])


-- | Stream operations on <a>ByteString</a>.
module System.IO.Streams.ByteString

-- | Wraps an <a>InputStream</a>, counting the number of bytes produced by
--   the stream as a side effect. Produces a new <a>InputStream</a> as well
--   as an IO action to retrieve the count of bytes produced.
--   
--   Strings pushed back to the returned <a>InputStream</a> will be pushed
--   back to the original stream, and the count of produced bytes will be
--   subtracted accordingly.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["abc", "def", "ghi"::ByteString]
--   ghci&gt; (is', getCount) &lt;- Streams.<a>countInput</a> is
--   ghci&gt; Streams.<a>read</a> is'
--   Just "abc"
--   ghci&gt; getCount
--   3
--   ghci&gt; Streams.<a>unRead</a> "bc" is'
--   ghci&gt; getCount
--   1
--   ghci&gt; Streams.<a>peek</a> is
--   Just "bc"
--   ghci&gt; Streams.<a>toList</a> is'
--   ["bc","def","ghi"]
--   ghci&gt; getCount
--   9
--   </pre>
countInput :: InputStream ByteString -> IO (InputStream ByteString, IO Int64)

-- | Wraps an <a>OutputStream</a>, counting the number of bytes consumed by
--   the stream as a side effect. Produces a new <a>OutputStream</a> as
--   well as an IO action to retrieve the count of bytes consumed.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; (os :: OutputStream ByteString, getList) &lt;- Streams.<a>listOutputStream</a>
--   ghci&gt; (os', getCount) &lt;- Streams.<a>countOutput</a> os
--   ghci&gt; Streams.<a>fromList</a> ["abc", "def", "ghi"] &gt;&gt;= Streams.<a>connectTo</a> os'
--   ghci&gt; getList
--   ["abc","def","ghi"]
--   ghci&gt; getCount
--   9
--   </pre>
countOutput :: OutputStream ByteString -> IO (OutputStream ByteString, IO Int64)

-- | Creates an <a>InputStream</a> from a <a>ByteString</a>.
fromByteString :: ByteString -> IO (InputStream ByteString)

-- | Creates an <a>InputStream</a> from a lazy <a>ByteString</a>.
fromLazyByteString :: ByteString -> IO (InputStream ByteString)

-- | Reads an <tt>n</tt>-byte ByteString from an input stream. Throws a
--   <a>ReadTooShortException</a> if fewer than <tt>n</tt> bytes were
--   available.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> ["long string"] &gt;&gt;= Streams.<a>readExactly</a> 6
--   "long s"
--   ghci&gt; Streams.<a>fromList</a> ["short"] &gt;&gt;= Streams.<a>readExactly</a> 6
--   *** Exception: Short read, expected 6 bytes
--   </pre>
readExactly :: Int -> InputStream ByteString -> IO ByteString

-- | Takes from a stream until the given predicate is no longer satisfied.
--   Returns Nothing on end-of-stream, or <tt>Just ""</tt> if the predicate
--   is never satisfied. See <a>takeWhile</a> and <a>takeWhile</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> ["Hello, world!"] &gt;&gt;= Streams.<a>takeBytesWhile</a> (/= ',')
--   Just "Hello"
--   ghci&gt; import Data.Char
--   ghci&gt; Streams.<a>fromList</a> ["7 Samurai"] &gt;&gt;= Streams.<a>takeBytesWhile</a> isAlpha
--   Just ""
--   ghci&gt; Streams.<a>fromList</a> [] &gt;&gt;= Streams.<a>takeBytesWhile</a> isAlpha
--   Nothing
--   </pre>
takeBytesWhile :: (Char -> Bool) -> InputStream ByteString -> IO (Maybe ByteString)

-- | Writes a lazy <a>ByteString</a> to an <a>OutputStream</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>writeLazyByteString</a> "Test\n" Streams.<a>stdout</a>
--   Test
--   </pre>
writeLazyByteString :: ByteString -> OutputStream ByteString -> IO ()

-- | Splits an <a>InputStream</a> over <a>ByteString</a>s using a delimiter
--   predicate.
--   
--   Note that:
--   
--   <ul>
--   <li>data pushed back with <a>unRead</a> is *not* propagated upstream
--   here.</li>
--   <li>the resulting <a>InputStream</a> may hold an unbounded amount of
--   the bytestring in memory waiting for the function to return true, so
--   this function should not be used in unsafe contexts.</li>
--   <li>the delimiter is NOT included in the output.</li>
--   <li>consecutive delimiters are not merged.</li>
--   <li>if the input ends in the delimiter, a final empty string is
--   <i>not</i> emitted. (/Since: 1.5.0.0. Previous versions had the
--   opposite behaviour, which was changed to match <a>lines</a>./)</li>
--   </ul>
--   
--   Example:
--   
--   <pre>
--   ghci&gt; Streams.<a>fromList</a> ["the quick br", "own  fox"::<a>ByteString</a>] &gt;&gt;=
--         Streams.<a>splitOn</a> (== ' ') &gt;&gt;= Streams.<a>toList</a>
--   ["the","quick","brown","","fox"]
--   </pre>
splitOn :: (Char -> Bool) -> InputStream ByteString -> IO (InputStream ByteString)

-- | Splits a bytestring <a>InputStream</a> into lines. See <a>splitOn</a>
--   and <a>lines</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["Hello,\n world!"] &gt;&gt;= Streams.<a>lines</a>
--   ghci&gt; replicateM 3 (Streams.<a>read</a> is)
--   [Just "Hello", Just ", world!", Nothing]
--   </pre>
--   
--   Note that this may increase the chunk size if the input contains
--   extremely long lines.
lines :: InputStream ByteString -> IO (InputStream ByteString)

-- | Intersperses string chunks sent to the given <a>OutputStream</a> with
--   newlines. See <a>intersperse</a> and <a>unlines</a>.
--   
--   <pre>
--   ghci&gt; os &lt;- Streams.<a>unlines</a> Streams.<a>stdout</a>
--   ghci&gt; Streams.<a>write</a> (Just "Hello,") os
--   Hello
--   ghci&gt; Streams.<a>write</a> Nothing os
--   ghci&gt; Streams.<a>write</a> (Just "world!") os
--   world!
--   </pre>
unlines :: OutputStream ByteString -> IO (OutputStream ByteString)

-- | Splits a bytestring <a>InputStream</a> into words. See <a>splitOn</a>
--   and <a>words</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["Hello, world!"] &gt;&gt;= Streams.<a>words</a>
--   ghci&gt; replicateM 3 (Streams.<a>read</a> is)
--   [Just "Hello,", Just "world!", Nothing]
--   </pre>
--   
--   Note that this may increase the chunk size if the input contains
--   extremely long words.
words :: InputStream ByteString -> IO (InputStream ByteString)

-- | Intersperses string chunks sent to the given <a>OutputStream</a> with
--   spaces. See <a>intersperse</a> and <a>unwords</a>.
--   
--   <pre>
--   ghci&gt; os &lt;- Streams.<a>unwords</a> Streams.<a>stdout</a>
--   ghci&gt; forM_ [Just "Hello,", Nothing, Just "world!\n"] $ w -&gt; Streams.<a>write</a> w os
--   Hello, world!
--   </pre>
unwords :: OutputStream ByteString -> IO (OutputStream ByteString)

-- | Wraps an <a>OutputStream</a>, producing a new stream that will pass
--   along at most <tt>n</tt> bytes to the wrapped stream, throwing any
--   subsequent input away.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; (os :: OutputStream ByteString, getList) &lt;- Streams.<a>listOutputStream</a>
--   ghci&gt; os' &lt;- Streams.<a>giveBytes</a> 6 os
--   ghci&gt; Streams.<a>fromList</a> ["long ", "string"] &gt;&gt;= Streams.<a>connectTo</a> os'
--   ghci&gt; getList
--   ["long ","s"]
--   </pre>
giveBytes :: Int64 -> OutputStream ByteString -> IO (OutputStream ByteString)

-- | Wraps an <a>OutputStream</a>, producing a new stream that will pass
--   along exactly <tt>n</tt> bytes to the wrapped stream. If the stream is
--   sent more or fewer than the given number of bytes, the resulting
--   stream will throw an exception (either
--   <a>TooFewBytesWrittenException</a> or
--   <a>TooManyBytesWrittenException</a>) during a call to <a>write</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["ok"]
--   ghci&gt; Streams.<a>outputToList</a> (Streams.<a>giveExactly</a> 2 &gt;=&gt; Streams.<a>connect</a> is)
--   ["ok"]
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["ok"]
--   ghci&gt; Streams.<a>outputToList</a> (Streams.<a>giveExactly</a> 1 &gt;=&gt; Streams.<a>connect</a> is)
--   *** Exception: Too many bytes written
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["ok"]
--   ghci&gt; Streams.<a>outputToList</a> (Streams.<a>giveExactly</a> 3 &gt;=&gt; Streams.<a>connect</a> is)
--   *** Exception: Too few bytes written
--   </pre>
giveExactly :: Int64 -> OutputStream ByteString -> IO (OutputStream ByteString)

-- | Wraps an <a>InputStream</a>, producing a new <a>InputStream</a> that
--   will produce at most <tt>n</tt> bytes, subsequently yielding
--   end-of-stream forever.
--   
--   Strings pushed back to the returned <a>InputStream</a> will be
--   propagated upstream, modifying the count of taken bytes accordingly.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["truncated", " string"::ByteString]
--   ghci&gt; is' &lt;- Streams.<a>takeBytes</a> 9 is
--   ghci&gt; Streams.<a>read</a> is'
--   Just "truncated"
--   ghci&gt; Streams.<a>read</a> is'
--   Nothing
--   ghci&gt; Streams.<a>peek</a> is
--   Just " string"
--   ghci&gt; Streams.<a>unRead</a> "cated" is'
--   ghci&gt; Streams.<a>peek</a> is
--   Just "cated"
--   ghci&gt; Streams.<a>peek</a> is'
--   Just "cated"
--   ghci&gt; Streams.<a>read</a> is'
--   Just "cated"
--   ghci&gt; Streams.<a>read</a> is'
--   Nothing
--   ghci&gt; Streams.<a>read</a> is
--   Just " string"
--   </pre>
takeBytes :: Int64 -> InputStream ByteString -> IO (InputStream ByteString)

-- | Like <tt>Streams.<a>takeBytes</a></tt>, but throws
--   <a>ReadTooShortException</a> when there aren't enough bytes present on
--   the source.
takeExactly :: Int64 -> InputStream ByteString -> IO (InputStream ByteString)

-- | Wraps an <a>OutputStream</a>, producing a new stream that will pass
--   along at most <tt>n</tt> bytes to the wrapped stream. If more than
--   <tt>n</tt> bytes are sent to the outer stream, a
--   <a>TooManyBytesWrittenException</a> will be thrown.
--   
--   <i>Note</i>: if more than <tt>n</tt> bytes are sent to the outer
--   stream, <a>throwIfConsumesMoreThan</a> will not necessarily send the
--   first <tt>n</tt> bytes through to the wrapped stream before throwing
--   the exception.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; (os :: OutputStream ByteString, getList) &lt;- Streams.<a>listOutputStream</a>
--   ghci&gt; os' &lt;- Streams.<a>throwIfConsumesMoreThan</a> 5 os
--   ghci&gt; Streams.<a>fromList</a> ["short"] &gt;&gt;= Streams.<a>connectTo</a> os'
--   ghci&gt; getList
--   ["short"]
--   ghci&gt; os'' &lt;- Streams.<a>throwIfConsumesMoreThan</a> 5 os
--   ghci&gt; Streams.<a>fromList</a> ["long", "string"] &gt;&gt;= Streams.<a>connectTo</a> os''
--   *** Exception: Too many bytes written
--   </pre>
throwIfConsumesMoreThan :: Int64 -> OutputStream ByteString -> IO (OutputStream ByteString)

-- | Wraps an <a>InputStream</a>. If more than <tt>n</tt> bytes are
--   produced by this stream, <a>read</a> will throw a
--   <a>TooManyBytesReadException</a>.
--   
--   If a chunk yielded by the input stream would result in more than
--   <tt>n</tt> bytes being produced, <a>throwIfProducesMoreThan</a> will
--   cut the generated string such that exactly <tt>n</tt> bytes are
--   yielded by the returned stream, and the <i>subsequent</i> read will
--   throw an exception. Example:
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> ["abc", "def", "ghi"] &gt;&gt;=
--               Streams.<a>throwIfProducesMoreThan</a> 5
--   ghci&gt; <a>replicateM</a> 2 (<a>read</a> is)
--   [Just "abc",Just "de"]
--   ghci&gt; Streams.<a>read</a> is
--   *** Exception: Too many bytes read
--   </pre>
--   
--   Strings pushed back to the returned <a>InputStream</a> will be
--   propagated upstream, modifying the count of taken bytes accordingly.
--   Example:
--   
--   <pre>
--   ghci&gt; is  &lt;- Streams.<a>fromList</a> ["abc", "def", "ghi"]
--   ghci&gt; is' &lt;- Streams.<a>throwIfProducesMoreThan</a> 5 is
--   ghci&gt; Streams.<a>read</a> is'
--   Just "abc"
--   ghci&gt; Streams.<a>unRead</a> "xyz" is'
--   ghci&gt; Streams.<a>peek</a> is
--   Just "xyz"
--   ghci&gt; Streams.<a>read</a> is
--   Just "xyz"
--   ghci&gt; Streams.<a>read</a> is
--   Just "de"
--   ghci&gt; Streams.<a>read</a> is
--   *** Exception: Too many bytes read
--   </pre>
throwIfProducesMoreThan :: Int64 -> InputStream ByteString -> IO (InputStream ByteString)

-- | Rate-limits an input stream. If the input stream is not read from
--   faster than the given rate, reading from the wrapped stream will throw
--   a <a>RateTooSlowException</a>.
--   
--   Strings pushed back to the returned <a>InputStream</a> will be
--   propagated up to the original stream.
throwIfTooSlow :: IO () -> Double -> Int -> InputStream ByteString -> IO (InputStream ByteString)

-- | <a>MatchInfo</a> provides match information when performing string
--   search.
data MatchInfo
Match :: {-# UNPACK #-} !ByteString -> MatchInfo
NoMatch :: {-# UNPACK #-} !ByteString -> MatchInfo

-- | Given a <a>ByteString</a> to look for (the "needle") and an
--   <a>InputStream</a>, produces a new <a>InputStream</a> which yields
--   data of type <a>MatchInfo</a>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; <a>fromList</a> ["food", "oof", "oodles", "ok"] &gt;&gt;=
--         <a>search</a> "foo" &gt;&gt;= <a>toList</a>
--   [<a>Match</a> "foo",<a>NoMatch</a> "d",<a>NoMatch</a> "oo",<a>Match</a> "foo",<a>NoMatch</a> "dlesok"]
--   </pre>
--   
--   Uses the Boyer-Moore-Horspool algorithm
--   (<a>http://en.wikipedia.org/wiki/Boyer%E2%80%93Moore%E2%80%93Horspool_algorithm</a>).
search :: ByteString -> InputStream ByteString -> IO (InputStream MatchInfo)

-- | Thrown by <a>throwIfTooSlow</a> if input is not being produced fast
--   enough by the given <a>InputStream</a>.
data RateTooSlowException

-- | Thrown by <a>readExactly</a> and <a>takeExactly</a> when not enough
--   bytes were available on the input.
data ReadTooShortException

-- | Thrown by <a>throwIfProducesMoreThan</a> when too many bytes were read
--   from the original <a>InputStream</a>.
data TooManyBytesReadException

-- | Thrown by <a>throwIfConsumesMoreThan</a> when too many bytes were sent
--   to the produced <a>OutputStream</a>.
data TooManyBytesWrittenException

-- | Thrown by <a>giveExactly</a> when too few bytes were written to the
--   produced <a>OutputStream</a>.
data TooFewBytesWrittenException
instance GHC.Internal.Exception.Type.Exception System.IO.Streams.ByteString.RateTooSlowException
instance GHC.Internal.Exception.Type.Exception System.IO.Streams.ByteString.ReadTooShortException
instance GHC.Internal.Exception.Type.Exception System.IO.Streams.ByteString.TooFewBytesWrittenException
instance GHC.Internal.Exception.Type.Exception System.IO.Streams.ByteString.TooManyBytesReadException
instance GHC.Internal.Exception.Type.Exception System.IO.Streams.ByteString.TooManyBytesWrittenException
instance GHC.Internal.Show.Show System.IO.Streams.ByteString.RateTooSlowException
instance GHC.Internal.Show.Show System.IO.Streams.ByteString.ReadTooShortException
instance GHC.Internal.Show.Show System.IO.Streams.ByteString.TooFewBytesWrittenException
instance GHC.Internal.Show.Show System.IO.Streams.ByteString.TooManyBytesReadException
instance GHC.Internal.Show.Show System.IO.Streams.ByteString.TooManyBytesWrittenException


-- | Converting network <tt>Socket</tt>s to streams.
module System.IO.Streams.Network

-- | Converts a <a>Socket</a> to an <a>InputStream</a> /
--   <a>OutputStream</a> pair. Note that, as is usually the case in
--   <tt>io-streams</tt>, writing a <a>Nothing</a> to the generated
--   <a>OutputStream</a> does not cause the underlying <a>Socket</a> to be
--   closed.
socketToStreams :: Socket -> IO (InputStream ByteString, OutputStream ByteString)

-- | Converts a <a>Socket</a> to an <a>InputStream</a> /
--   <a>OutputStream</a> pair, with control over the size of the receive
--   buffers. Note that, as is usually the case in <tt>io-streams</tt>,
--   writing a <a>Nothing</a> to the generated <a>OutputStream</a> does not
--   cause the underlying <a>Socket</a> to be closed.
socketToStreamsWithBufferSize :: Int -> Socket -> IO (InputStream ByteString, OutputStream ByteString)


-- | A module adapting the functions from <a>System.Process</a> to work
--   with <tt>io-streams</tt>.
module System.IO.Streams.Process
proc :: FilePath -> [String] -> CreateProcess
data CmdSpec
ShellCommand :: String -> CmdSpec
RawCommand :: FilePath -> [String] -> CmdSpec
data CreateProcess
CreateProcess :: CmdSpec -> Maybe FilePath -> Maybe [(String, String)] -> StdStream -> StdStream -> StdStream -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Maybe GroupID -> Maybe UserID -> Bool -> CreateProcess
data ProcessHandle
data StdStream
Inherit :: StdStream
UseHandle :: Handle -> StdStream
CreatePipe :: StdStream
NoStream :: StdStream
createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)
interruptProcessGroupOf :: ProcessHandle -> IO ()
rawSystem :: String -> [String] -> IO ExitCode
readProcess :: FilePath -> [String] -> String -> IO String
readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String)
runCommand :: String -> IO ProcessHandle
shell :: String -> CreateProcess
showCommandForUser :: FilePath -> [String] -> String
system :: String -> IO ExitCode
terminateProcess :: ProcessHandle -> IO ()
waitForProcess :: ProcessHandle -> IO ExitCode

-- | Runs a command using the shell, and returns streams that may be used
--   to communicate with the process via its stdin, stdout, and stderr
--   respectively.
--   
--   The streams returned by this command are guarded by locks and are
--   therefore safe to use in multithreaded code.
--   
--   <i>Since: 1.0.2.0</i>
runInteractiveCommand :: String -> IO (OutputStream ByteString, InputStream ByteString, InputStream ByteString, ProcessHandle)

-- | Runs a raw command, and returns streams that may be used to
--   communicate with the process via its <tt>stdin</tt>, <tt>stdout</tt>
--   and <tt>stderr</tt> respectively.
--   
--   For example, to start a process and feed a string to its stdin:
--   
--   <pre>
--   (inp,out,err,pid) &lt;- runInteractiveProcess "..."
--   forkIO (Streams.write (Just str) inp)
--   </pre>
--   
--   The streams returned by this command are guarded by locks and are
--   therefore safe to use in multithreaded code.
--   
--   <i>Since: 1.0.2.0</i>
runInteractiveProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> IO (OutputStream ByteString, InputStream ByteString, InputStream ByteString, ProcessHandle)


-- | Stream primitives for decoding and encoding <a>Text</a> values in
--   UTF-8 format.
module System.IO.Streams.Text

-- | Decode an <a>InputStream</a> of <a>ByteString</a>s in UTF-8 format
--   into an <a>InputStream</a> of <a>Text</a> values. If decoding fails,
--   will throw an exception. See
--   <tt>Data.Text.Encoding.<a>decodeUtf8</a></tt>.
decodeUtf8 :: InputStream ByteString -> IO (InputStream Text)

-- | Decode an <a>InputStream</a> of <a>ByteString</a>s in UTF-8 format
--   into an <a>InputStream</a> of <a>Text</a> values. If decoding fails,
--   invokes the given <a>OnDecodeError</a> function to decide what to do.
--   See <tt>Data.Text.Encoding.<a>decodeUtf8With</a></tt>.
decodeUtf8With :: OnDecodeError -> InputStream ByteString -> IO (InputStream Text)

-- | Convert an <a>OutputStream</a> taking <a>ByteString</a>s to an
--   <a>OutputStream</a> that takes <a>Text</a>, encoding the data as
--   UTF-8. See <tt>Data.Text.Encoding.<a>encodeUtf8</a></tt>.
encodeUtf8 :: OutputStream ByteString -> IO (OutputStream Text)

module System.IO.Streams.Tutorial


-- | Vector conversions and utilities.
module System.IO.Streams.Vector

-- | Transforms a vector into an <a>InputStream</a> that yields each of the
--   values in the vector in turn.
--   
--   <pre>
--   ghci&gt; import <a>Control.Monad</a>
--   ghci&gt; import qualified <a>System.IO.Streams</a> as Streams
--   ghci&gt; import qualified <a>Data.Vector</a> as V
--   ghci&gt; let v = V.<a>fromList</a> [1, 2]
--   ghci&gt; is &lt;- Streams.<a>fromVector</a> v
--   ghci&gt; <a>replicateM</a> 3 (Streams.<a>read</a> is)
--   [<a>Just</a> 1,<a>Just</a> 2,<a>Nothing</a>]
--   </pre>
fromVector :: Vector v a => v a -> IO (InputStream a)

-- | Drains an <a>InputStream</a>, converting it to a vector. Note that
--   this function reads the entire <a>InputStream</a> strictly into memory
--   and as such is not recommended for streaming applications or where the
--   size of the input is not bounded or known.
--   
--   <pre>
--   ghci&gt; is &lt;- Streams.<a>fromList</a> [(1::Int)..4]
--   ghci&gt; Streams.<a>toVector</a> is :: <a>IO</a> (V.<a>Vector</a> Int)
--   fromList [1,2,3,4]
--   </pre>
toVector :: Vector v a => InputStream a -> IO (v a)

-- | Like <a>toVector</a>, but allows control over how large the vector
--   buffer is to start with.
toVectorSized :: Vector v a => Int -> InputStream a -> IO (v a)

-- | Given an IO action that requires an <a>OutputStream</a>, creates one
--   and captures all the output the action sends to it as a vector.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; ((<tt>connect</tt> <a>$</a> <a>fromList</a> [1, 2, 3]) &gt;&gt;= <a>outputToVector</a>)
--             :: IO (<a>Vector</a> Int)
--   fromList [1,2,3]
--   </pre>
outputToVector :: Vector v a => (OutputStream a -> IO b) -> IO (v a)

-- | Like <a>outputToVector</a>, but allows control over how large the
--   vector buffer is to start with.
outputToVectorSized :: Vector v a => Int -> (OutputStream a -> IO b) -> IO (v a)

-- | Drains an <a>InputStream</a>, converting it to a mutable vector. Note
--   that this function reads the entire <a>InputStream</a> strictly into
--   memory and as such is not recommended for streaming applications or
--   where the size of the input is not bounded or known.
toMutableVector :: MVector v a => InputStream a -> IO (v (PrimState IO) a)

-- | Like <a>toMutableVector</a>, but allows control over how large the
--   vector buffer is to start with.
toMutableVectorSized :: MVector v a => Int -> InputStream a -> IO (v (PrimState IO) a)

-- | Given an IO action that requires an <a>OutputStream</a>, creates one
--   and captures all the output the action sends to it as a mutable
--   vector.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; import <a>Control.Applicative</a>
--   ghci&gt; (<tt>connect</tt> &lt;$&gt; <a>fromList</a> [1, 2, 3::<a>Int</a>])
--          &gt;&gt;= <a>outputToMutableVector</a>
--          &gt;&gt;= V.<a>freeze</a>
--   fromList [1,2,3]
--   </pre>
outputToMutableVector :: MVector v a => (OutputStream a -> IO b) -> IO (v (PrimState IO) a)

-- | Like <a>outputToMutableVector</a>, but allows control over how large
--   the vector buffer is to start with.
outputToMutableVectorSized :: MVector v a => Int -> (OutputStream a -> IO b) -> IO (v (PrimState IO) a)

-- | Feeds a vector to an <a>OutputStream</a>. Does <i>not</i> write an
--   end-of-stream to the stream.
--   
--   <pre>
--   ghci&gt; let v = V.<tt>fromList</tt> [1..4] :: V.<a>Vector</a> Int
--   ghci&gt; os &lt;- Streams.<a>unlines</a> Streams.<tt>stdout</tt> &gt;&gt;= Streams.<a>contramap</a> (S.pack . show) :: IO (<a>OutputStream</a> Int)
--   ghci&gt; Streams.<a>writeVector</a> v os
--   1
--   2
--   3
--   4
--   </pre>
writeVector :: Vector v a => v a -> OutputStream a -> IO ()

-- | Splits an input stream into chunks of at most size <tt>n</tt>.
--   
--   Example:
--   
--   <pre>
--   ghci&gt; (<a>fromList</a> [1..14::Int] &gt;&gt;= <a>chunkVector</a> 4 &gt;&gt;= <a>toList</a>)
--            :: IO [<a>Vector</a> Int]
--   [fromList [1,2,3,4],fromList [5,6,7,8],fromList [9,10,11,12],fromList [13,14]]
--   </pre>
chunkVector :: Vector v a => Int -> InputStream a -> IO (InputStream (v a))

-- | <a>vectorOutputStream</a> returns an <a>OutputStream</a> which stores
--   values fed into it and an action which flushes all stored values to a
--   vector.
--   
--   The flush action resets the store.
--   
--   Note that this function <i>will</i> buffer any input sent to it on the
--   heap. Please don't use this unless you're sure that the amount of
--   input provided is bounded and will fit in memory without issues.
--   
--   <pre>
--   ghci&gt; (os, flush) &lt;- Streams.<a>vectorOutputStream</a> :: IO (<a>OutputStream</a> Int, IO (V.<a>Vector</a> Int))
--   ghci&gt; Streams.<a>write</a> (Just 1) os
--   ghci&gt; Streams.<a>write</a> (Just 2) os
--   ghci&gt; flush
--   fromList [1,2]
--   ghci&gt; Streams.<a>write</a> (Just 3) os
--   ghci&gt; Streams.<a>write</a> Nothing  os
--   ghci&gt; Streams.<a>write</a> (Just 4) os
--   ghci&gt; flush
--   fromList [3]
--   </pre>
vectorOutputStream :: Vector v c => IO (OutputStream c, IO (v c))

-- | Like <a>vectorOutputStream</a>, but allows control over how large the
--   vector buffer is to start with.
vectorOutputStreamSized :: Vector v c => Int -> IO (OutputStream c, IO (v c))

-- | <a>mutableVectorOutputStream</a> returns an <a>OutputStream</a> which
--   stores values fed into it and an action which flushes all stored
--   values to a vector.
--   
--   The flush action resets the store.
--   
--   Note that this function <i>will</i> buffer any input sent to it on the
--   heap. Please don't use this unless you're sure that the amount of
--   input provided is bounded and will fit in memory without issues.
mutableVectorOutputStream :: MVector v c => IO (OutputStream c, IO (v (PrimState IO) c))

-- | Like <a>mutableVectorOutputStream</a>, but allows control over how
--   large the vector buffer is to start with.
mutableVectorOutputStreamSized :: MVector v c => Int -> IO (OutputStream c, IO (v (PrimState IO) c))


-- | Interface to <tt>zlib</tt> and <tt>gzip</tt> compression for
--   <tt>Bytestring</tt>s and <a>Builder</a>s
module System.IO.Streams.Zlib

-- | Decompress an <a>InputStream</a> of strict <a>ByteString</a>s from the
--   <tt>gzip</tt> format
gunzip :: InputStream ByteString -> IO (InputStream ByteString)

-- | Decompress an <a>InputStream</a> of strict <a>ByteString</a>s from the
--   <tt>zlib</tt> format
decompress :: InputStream ByteString -> IO (InputStream ByteString)

-- | Convert an <a>OutputStream</a> that consumes compressed
--   <a>ByteString</a>s into an <a>OutputStream</a> that consumes
--   uncompressed <a>ByteString</a>s in the <tt>gzip</tt> format
gzip :: CompressionLevel -> OutputStream ByteString -> IO (OutputStream ByteString)

-- | Convert an <a>OutputStream</a> that consumes compressed
--   <a>ByteString</a>s into an <a>OutputStream</a> that consumes
--   uncompressed <a>ByteString</a>s in the <tt>zlib</tt> format
compress :: CompressionLevel -> OutputStream ByteString -> IO (OutputStream ByteString)

-- | Convert an <a>OutputStream</a> that consumes compressed
--   <a>Builder</a>s into an <a>OutputStream</a> that consumes uncompressed
--   <a>Builder</a>s in the <tt>gzip</tt> format
gzipBuilder :: CompressionLevel -> OutputStream Builder -> IO (OutputStream Builder)

-- | Convert an <a>OutputStream</a> that consumes compressed
--   <a>Builder</a>s into an <a>OutputStream</a> that consumes uncompressed
--   <a>Builder</a>s in the <tt>zlib</tt> format
compressBuilder :: CompressionLevel -> OutputStream Builder -> IO (OutputStream Builder)

-- | Parameter that defines the tradeoff between speed and compression
--   ratio
newtype CompressionLevel
CompressionLevel :: Int -> CompressionLevel

-- | A compression level that balances speed with compression ratio
defaultCompressionLevel :: CompressionLevel
instance GHC.Classes.Eq System.IO.Streams.Zlib.CompressionLevel
instance GHC.Internal.Num.Num System.IO.Streams.Zlib.CompressionLevel
instance GHC.Internal.Read.Read System.IO.Streams.Zlib.CompressionLevel
instance GHC.Internal.Show.Show System.IO.Streams.Zlib.CompressionLevel


-- | This module is a top-level convenience module which re-exports most of
--   the <tt>io-streams</tt> library.
--   
--   It is recommended to import this module qualified, as follows:
--   
--   <pre>
--   import           <a>System.IO.Streams</a> (<a>Generator</a>, <a>InputStream</a>, <a>OutputStream</a>)
--   import qualified <a>System.IO.Streams</a> as Streams
--   </pre>
--   
--   For an in-depth tutorial on how to use <tt>io-streams</tt>, please see
--   the <a>System.IO.Streams.Tutorial</a> module.
--   
--   Is there a function missing from this library? Interested in
--   contributing? Send a pull request to
--   <a>http://github.com/snapframework/io-streams</a>.
module System.IO.Streams

-- | An <a>InputStream</a> generates values of type <tt>c</tt> in the
--   <a>IO</a> monad.
--   
--   Two primitive operations are defined on <a>InputStream</a>:
--   
--   <ul>
--   <li><tt><a>read</a> :: <a>InputStream</a> c -&gt; <a>IO</a>
--   (<a>Maybe</a> c)</tt> reads a value from the stream, where "end of
--   stream" is signaled by <a>read</a> returning <a>Nothing</a>.</li>
--   <li><tt><a>unRead</a> :: c -&gt; <a>InputStream</a> c -&gt; <a>IO</a>
--   ()</tt> "pushes back" a value to the stream.</li>
--   </ul>
--   
--   It is intended that <a>InputStream</a>s obey the following law:
--   
--   <pre>
--   <a>unRead</a> c stream &gt;&gt; <a>read</a> stream === <a>return</a> (<a>Just</a> c)
--   </pre>
data InputStream a

-- | An <a>OutputStream</a> consumes values of type <tt>c</tt> in the
--   <a>IO</a> monad. The only primitive operation defined on
--   <a>OutputStream</a> is:
--   
--   <ul>
--   <li><pre><a>write</a> :: <a>Maybe</a> c -&gt; <a>OutputStream</a> c
--   -&gt; <a>IO</a> ()</pre></li>
--   </ul>
--   
--   Values of type <tt>c</tt> are written in an <a>OutputStream</a> by
--   wrapping them in <a>Just</a>, and the end of the stream is indicated
--   by supplying <a>Nothing</a>.
--   
--   If you supply a value after a <a>Nothing</a>, the behavior is defined
--   by the implementer of the given <a>OutputStream</a>. (All
--   <a>OutputStream</a> definitions in this library will simply discard
--   the extra input.)
data OutputStream a

-- | Creates an <a>InputStream</a> from a value-producing action.
--   
--   (<tt>makeInputStream m</tt>) calls the action <tt>m</tt> each time you
--   request a value from the <a>InputStream</a>. The given action is
--   extended with the default pushback mechanism (see
--   <a>System.IO.Streams.Internal#pushback</a>).
makeInputStream :: IO (Maybe a) -> IO (InputStream a)

-- | Creates an <a>OutputStream</a> from a value-consuming action.
--   
--   (<tt>makeOutputStream f</tt>) runs the computation <tt>f</tt> on each
--   value fed to it.
--   
--   Since version 1.2.0.0, <a>makeOutputStream</a> also ensures that
--   output streams no longer receive data once EOF is received (i.e. you
--   can now assume that makeOutputStream will feed your function
--   <tt>Nothing</tt> at most once.)
makeOutputStream :: (Maybe a -> IO ()) -> IO (OutputStream a)

-- | Reads one value from an <a>InputStream</a>.
--   
--   Returns either a value wrapped in a <a>Just</a>, or <a>Nothing</a> if
--   the end of the stream is reached.
read :: InputStream a -> IO (Maybe a)

-- | Pushes a value back onto an input stream. <a>read</a> and
--   <a>unRead</a> should satisfy the following law, with the possible
--   exception of side effects:
--   
--   <pre>
--   Streams.<a>unRead</a> c stream &gt;&gt; Streams.<a>read</a> stream === <a>return</a> (<a>Just</a> c)
--   </pre>
--   
--   Note that this could be used to add values back to the stream that
--   were not originally drawn from the stream.
unRead :: a -> InputStream a -> IO ()

-- | Observes the first value from an <a>InputStream</a> without consuming
--   it.
--   
--   Returns <a>Nothing</a> if the <a>InputStream</a> is empty. <a>peek</a>
--   satisfies the following law:
--   
--   <pre>
--   Streams.<a>peek</a> stream &gt;&gt; Streams.<a>read</a> stream === Streams.<a>read</a> stream
--   </pre>
peek :: InputStream a -> IO (Maybe a)

-- | Feeds a value to an <a>OutputStream</a>. Values of type <tt>c</tt> are
--   written in an <a>OutputStream</a> by wrapping them in <a>Just</a>, and
--   the end of the stream is indicated by supplying <a>Nothing</a>.
write :: Maybe a -> OutputStream a -> IO ()

-- | Flipped version of <a>write</a>.
--   
--   <i>Since: 1.3.0.0.</i>
writeTo :: OutputStream a -> Maybe a -> IO ()

-- | Checks if an <a>InputStream</a> is at end-of-stream.
atEOF :: InputStream a -> IO Bool

-- | Connects an <a>InputStream</a> and <a>OutputStream</a>, supplying
--   values from the <a>InputStream</a> to the <a>OutputStream</a>, and
--   propagating the end-of-stream message from the <a>InputStream</a>
--   through to the <a>OutputStream</a>.
--   
--   The connection ends when the <a>InputStream</a> yields a
--   <a>Nothing</a>.
connect :: InputStream a -> OutputStream a -> IO ()

-- | The <a>connectTo</a> function is just <tt><a>flip</a>
--   <a>connect</a></tt>.
--   
--   Useful for writing expressions like <tt>fromList [1,2,3] &gt;&gt;=
--   connectTo foo</tt>.
connectTo :: OutputStream a -> InputStream a -> IO ()

-- | Connects an <a>InputStream</a> to an <a>OutputStream</a> without
--   passing the end-of-stream notification through to the
--   <a>OutputStream</a>.
--   
--   Use this to supply an <a>OutputStream</a> with multiple
--   <a>InputStream</a>s and use <a>connect</a> for the final
--   <a>InputStream</a> to finalize the <a>OutputStream</a>, like so:
--   
--   <pre>
--   do Streams.<a>supply</a>  input1 output
--      Streams.<a>supply</a>  input2 output
--      Streams.<a>connect</a> input3 output
--   </pre>
supply :: InputStream a -> OutputStream a -> IO ()

-- | <a>supply</a> with the arguments flipped.
supplyTo :: OutputStream a -> InputStream a -> IO ()

-- | <a>appendInputStream</a> concatenates two <a>InputStream</a>s,
--   analogous to (<a>++</a>) for lists.
--   
--   The second <a>InputStream</a> continues where the first
--   <a>InputStream</a> ends.
--   
--   Note: values pushed back to <a>appendInputStream</a> are not
--   propagated to either wrapped <a>InputStream</a>.
appendInputStream :: InputStream a -> InputStream a -> IO (InputStream a)

-- | <a>concatInputStreams</a> concatenates a list of <a>InputStream</a>s,
--   analogous to (<a>++</a>) for lists.
--   
--   Subsequent <a>InputStream</a>s continue where the previous one
--   <a>InputStream</a> ends.
--   
--   Note: values pushed back to the <a>InputStream</a> returned by
--   <a>concatInputStreams</a> are not propagated to any of the source
--   <a>InputStream</a>s.
concatInputStreams :: [InputStream a] -> IO (InputStream a)

-- | Converts an <a>InputStream</a> into a thread-safe <a>InputStream</a>,
--   at a slight performance penalty.
--   
--   For performance reasons, this library provides non-thread-safe streams
--   by default. Use the <tt>locking</tt> functions to convert these
--   streams into slightly slower, but thread-safe, equivalents.
lockingInputStream :: InputStream a -> IO (InputStream a)

-- | Converts an <a>OutputStream</a> into a thread-safe
--   <a>OutputStream</a>, at a slight performance penalty.
--   
--   For performance reasons, this library provides non-thread-safe streams
--   by default. Use the <tt>locking</tt> functions to convert these
--   streams into slightly slower, but thread-safe, equivalents.
lockingOutputStream :: OutputStream a -> IO (OutputStream a)

-- | An empty <a>InputStream</a> that yields <a>Nothing</a> immediately.
nullInput :: IO (InputStream a)

-- | An empty <a>OutputStream</a> that discards any input fed to it.
nullOutput :: IO (OutputStream a)

-- | A <a>Generator</a> is a coroutine monad that can be used to define
--   complex <a>InputStream</a>s. You can cause a value of type <tt>Just
--   r</tt> to appear when the <a>InputStream</a> is read by calling
--   <a>yield</a>:
--   
--   <pre>
--   g :: <a>Generator</a> Int ()
--   g = do
--       Streams.<a>yield</a> 1
--       Streams.<a>yield</a> 2
--       Streams.<a>yield</a> 3
--   </pre>
--   
--   A <a>Generator</a> can be turned into an <a>InputStream</a> by calling
--   <a>fromGenerator</a>:
--   
--   <pre>
--   m :: <a>IO</a> [<a>Int</a>]
--   m = Streams.<a>fromGenerator</a> g &gt;&gt;= Streams.<a>toList</a>     -- value returned is [1,2,3]
--   </pre>
--   
--   You can perform IO by calling <a>liftIO</a>, and turn a
--   <a>Generator</a> into an <a>InputStream</a> with <a>fromGenerator</a>.
--   
--   As a general rule, you should not acquire resources that need to be
--   freed from a <a>Generator</a>, because there is no guarantee the
--   coroutine continuation will ever be called, nor can you catch an
--   exception from within a <a>Generator</a>.
data Generator r a

-- | Turns a <a>Generator</a> into an <a>InputStream</a>.
fromGenerator :: Generator r a -> IO (InputStream r)

-- | Calling <tt><a>yield</a> x</tt> causes the value <tt><a>Just</a>
--   x</tt> to appear on the input when this generator is converted to an
--   <a>InputStream</a>. The rest of the computation after the call to
--   <a>yield</a> is resumed later when the <a>InputStream</a> is
--   <a>read</a> again.
yield :: r -> Generator r ()
