-- 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

-- | Waits for the specified process to terminate, and returns its exit
--   code. On Unix systems, may throw <tt>UserInterrupt</tt> when using
--   <a>delegate_ctlc</a>.
--   
--   GHC Note: in order to call <tt>waitForProcess</tt> without blocking
--   all the other threads in the system, you must compile the program with
--   <tt>-threaded</tt>.
--   
--   Note that it is safe to call <tt>waitForProcess</tt> for the same
--   process in multiple threads. When the process ends, threads blocking
--   on this call will wake in FIFO order. When using <a>delegate_ctlc</a>
--   and the process is interrupted, only the first waiting thread will
--   throw <tt>UserInterrupt</tt>.
--   
--   (<i>Since: 1.2.0.0</i>) On Unix systems, a negative value
--   <tt><a>ExitFailure</a> -<i>signum</i></tt> indicates that the child
--   was terminated by signal <tt><i>signum</i></tt>. The signal numbers
--   are platform-specific, so to test for a specific signal use the
--   constants provided by <a>System.Posix.Signals</a> in the <tt>unix</tt>
--   package. Note: core dumps are not reported, use
--   <a>System.Posix.Process</a> if you need this detail.
waitForProcess :: ProcessHandle -> IO ExitCode

-- | This is the most general way to spawn an external process. The process
--   can be a command line to be executed by a shell or a raw command with
--   a list of arguments. The stdin, stdout, and stderr streams of the new
--   process may individually be attached to new pipes, to existing
--   <a>Handle</a>s, or just inherited from the parent (the default.)
--   
--   The details of how to create the process are passed in the
--   <a>CreateProcess</a> record. To make it easier to construct a
--   <a>CreateProcess</a>, the functions <a>proc</a> and <a>shell</a> are
--   supplied that fill in the fields with default values which can be
--   overriden as needed.
--   
--   <a>createProcess</a> returns <tt>(<i>mb_stdin_hdl</i>,
--   <i>mb_stdout_hdl</i>, <i>mb_stderr_hdl</i>, <i>ph</i>)</tt>, where
--   
--   <ul>
--   <li>if <tt><a>std_in</a> == <a>CreatePipe</a></tt>, then
--   <tt><i>mb_stdin_hdl</i></tt> will be <tt>Just <i>h</i></tt>, where
--   <tt><i>h</i></tt> is the write end of the pipe connected to the child
--   process's <tt>stdin</tt>.</li>
--   <li>otherwise, <tt><i>mb_stdin_hdl</i> == Nothing</tt></li>
--   </ul>
--   
--   Similarly for <tt><i>mb_stdout_hdl</i></tt> and
--   <tt><i>mb_stderr_hdl</i></tt>.
--   
--   For example, to execute a simple <tt>ls</tt> command:
--   
--   <pre>
--   r &lt;- createProcess (proc "ls" [])
--   </pre>
--   
--   To create a pipe from which to read the output of <tt>ls</tt>:
--   
--   <pre>
--   (_, Just hout, _, _) &lt;-
--       createProcess (proc "ls" []){ std_out = CreatePipe }
--   </pre>
--   
--   To also set the directory in which to run <tt>ls</tt>:
--   
--   <pre>
--   (_, Just hout, _, _) &lt;-
--       createProcess (proc "ls" []){ cwd = Just "/home/bob",
--                                     std_out = CreatePipe }
--   </pre>
--   
--   Note that <tt>Handle</tt>s provided for <tt>std_in</tt>,
--   <tt>std_out</tt>, or <tt>std_err</tt> via the <tt>UseHandle</tt>
--   constructor will be closed by calling this function. This is not
--   always the desired behavior. In cases where you would like to leave
--   the <tt>Handle</tt> open after spawning the child process, please use
--   <a>createProcess_</a> instead. All created <tt>Handle</tt>s are
--   initially in text mode; if you need them to be in binary mode then use
--   <a>hSetBinaryMode</a>.
--   
--   <tt><i>ph</i></tt> contains a handle to the running process. On
--   Windows <a>use_process_jobs</a> can be set in CreateProcess in order
--   to create a Win32 Job object to monitor a process tree's progress. If
--   it is set then that job is also returned inside <tt><i>ph</i></tt>.
--   <tt><i>ph</i></tt> can be used to kill all running sub-processes. This
--   feature has been available since 1.5.0.0.
createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

-- | A handle to a process, which can be used to wait for termination of
--   the process using <a>waitForProcess</a>.
--   
--   None of the process-creation functions in this library wait for
--   termination: they all return a <a>ProcessHandle</a> which may be used
--   to wait for the process later.
--   
--   On Windows a second wait method can be used to block for event
--   completion. This requires two handles. A process job handle and a
--   events handle to monitor.
data ProcessHandle
data StdStream

-- | Inherit Handle from parent
Inherit :: StdStream

-- | Use the supplied Handle
UseHandle :: Handle -> StdStream

-- | Create a new pipe. The returned <tt>Handle</tt> will use the default
--   encoding and newline translation mode (just like <tt>Handle</tt>s
--   created by <tt>openFile</tt>).
CreatePipe :: StdStream

-- | Close the stream's file descriptor without passing a Handle. On POSIX
--   systems this may lead to strange behavior in the child process because
--   attempting to read or write after the file has been closed throws an
--   error. This should only be used with child processes that don't use
--   the file descriptor at all. If you wish to ignore the child process's
--   output you should either create a pipe and drain it manually or pass a
--   <tt>Handle</tt> that writes to <tt>/dev/null</tt>.
NoStream :: StdStream
data CmdSpec

-- | A command line to execute using the shell
ShellCommand :: String -> CmdSpec

-- | The name of an executable with a list of arguments
--   
--   The <a>FilePath</a> argument names the executable, and is interpreted
--   according to the platform's standard policy for searching for
--   executables. Specifically:
--   
--   <ul>
--   <li>on Unix systems the <a>execvp(3)</a> semantics is used, where if
--   the executable filename does not contain a slash (<tt>/</tt>) then the
--   <tt>PATH</tt> environment variable is searched for the
--   executable.</li>
--   <li>on Windows systems the Win32 <tt>CreateProcess</tt> semantics is
--   used. Briefly: if the filename does not contain a path, then the
--   directory containing the parent executable is searched, followed by
--   the current directory, then some standard locations, and finally the
--   current <tt>PATH</tt>. An <tt>.exe</tt> extension is added if the
--   filename does not already have an extension. For full details see the
--   <a>documentation</a> for the Windows <tt>SearchPath</tt> API.</li>
--   </ul>
--   
--   Windows does not have a mechanism for passing multiple arguments. When
--   using <tt>RawCommand</tt> on Windows, the command line is serialised
--   into a string, with arguments quoted separately. Command line parsing
--   is up individual programs, so the default behaviour may not work for
--   some programs. If you are not getting the desired results, construct
--   the command line yourself and use <a>ShellCommand</a>.
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

-- | Sends an interrupt signal to the process group of the given process.
--   
--   On Unix systems, it sends the group the SIGINT signal.
--   
--   On Windows systems, it generates a CTRL_BREAK_EVENT and will only work
--   for processes created using <tt>createProcess</tt> and setting the
--   <a>create_group</a> flag
interruptProcessGroupOf :: ProcessHandle -> IO ()

-- | Construct a <a>CreateProcess</a> record for passing to
--   <a>createProcess</a>, representing a raw command with arguments.
--   
--   See <a>RawCommand</a> for precise semantics of the specified
--   <tt>FilePath</tt>.
proc :: FilePath -> [String] -> CreateProcess

-- | Construct a <a>CreateProcess</a> record for passing to
--   <a>createProcess</a>, representing a command to be passed to the
--   shell.
shell :: String -> CreateProcess

-- | <tt>readProcess</tt> forks an external process, reads its standard
--   output strictly, blocking until the process terminates, and returns
--   the output string. The external process inherits the standard error.
--   
--   If an asynchronous exception is thrown to the thread executing
--   <tt>readProcess</tt>, the forked process will be terminated and
--   <tt>readProcess</tt> will wait (block) until the process has been
--   terminated.
--   
--   Output is returned strictly, so this is not suitable for launching
--   processes that require interaction over the standard file streams.
--   
--   This function throws an <a>IOError</a> if the process <a>ExitCode</a>
--   is anything other than <a>ExitSuccess</a>. If instead you want to get
--   the <a>ExitCode</a> then use <a>readProcessWithExitCode</a>.
--   
--   Users of this function should compile with <tt>-threaded</tt> if they
--   want other Haskell threads to keep running while waiting on the result
--   of readProcess.
--   
--   <pre>
--   &gt; readProcess "date" [] []
--   "Thu Feb  7 10:03:39 PST 2008\n"
--   </pre>
--   
--   The arguments are:
--   
--   <ul>
--   <li>The command to run, which must be in the $PATH, or an absolute or
--   relative path</li>
--   <li>A list of separate command line arguments to the program. See
--   <a>RawCommand</a> for further discussion of Windows semantics.</li>
--   <li>A string to pass on standard input to the forked process.</li>
--   </ul>
readProcess :: FilePath -> [String] -> String -> IO String

-- | <tt>readProcessWithExitCode</tt> is like <a>readProcess</a> but with
--   two differences:
--   
--   <ul>
--   <li>it returns the <a>ExitCode</a> of the process, and does not throw
--   any exception if the code is not <a>ExitSuccess</a>.</li>
--   <li>it reads and returns the output from process' standard error
--   handle, rather than the process inheriting the standard error
--   handle.</li>
--   </ul>
--   
--   On Unix systems, see <a>waitForProcess</a> for the meaning of exit
--   codes when the process died as the result of a signal.
readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String)

-- | Given a program <tt><i>p</i></tt> and arguments <tt><i>args</i></tt>,
--   <tt>showCommandForUser <i>p</i> <i>args</i></tt> returns a string
--   suitable for pasting into <tt>/bin/sh</tt> (on Unix systems) or
--   <tt>CMD.EXE</tt> (on Windows).
showCommandForUser :: FilePath -> [String] -> String

-- | This is a non-blocking version of <a>waitForProcess</a>. If the
--   process is still running, <a>Nothing</a> is returned. If the process
--   has exited, then <tt><a>Just</a> e</tt> is returned where <tt>e</tt>
--   is the exit code of the process.
--   
--   On Unix systems, see <a>waitForProcess</a> for the meaning of exit
--   codes when the process died as the result of a signal. May throw
--   <tt>UserInterrupt</tt> when using <a>delegate_ctlc</a>.
getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)

-- | Attempts to terminate the specified process. This function should not
--   be used under normal circumstances - no guarantees are given regarding
--   how cleanly the process is terminated. To check whether the process
--   has indeed terminated, use <a>getProcessExitCode</a>.
--   
--   On Unix systems, <a>terminateProcess</a> sends the process the SIGTERM
--   signal. On Windows systems, if <a>use_process_jobs</a> is <a>True</a>
--   then the Win32 <tt>TerminateJobObject</tt> function is called to kill
--   all processes associated with the job and passing the exit code of 1
--   to each of them. Otherwise if <a>use_process_jobs</a> is <a>False</a>
--   then the Win32 <tt>TerminateProcess</tt> function is called, passing
--   an exit code of 1.
--   
--   Note: on Windows, if the process was a shell command created by
--   <a>createProcess</a> with <a>shell</a>, or created by
--   <a>runCommand</a> or <a>runInteractiveCommand</a>, then
--   <a>terminateProcess</a> will only terminate the shell, not the command
--   itself. On Unix systems, both processes are in a process group and
--   will be terminated together.
terminateProcess :: ProcessHandle -> IO ()

-- | Runs a command using the shell.
runCommand :: String -> IO ProcessHandle

-- | Computation <tt>system cmd</tt> returns the exit code produced when
--   the operating system runs the shell command <tt>cmd</tt>.
--   
--   This computation may fail with one of the following <a>IOErrorType</a>
--   exceptions:
--   
--   <ul>
--   <li><i><tt>PermissionDenied</tt></i> The process has insufficient
--   privileges to perform the operation.</li>
--   <li><i><tt>ResourceExhausted</tt></i> Insufficient resources are
--   available to perform the operation.</li>
--   <li><i><tt>UnsupportedOperation</tt></i> The implementation does not
--   support system calls.</li>
--   </ul>
--   
--   On Windows, <a>system</a> passes the command to the Windows command
--   interpreter (<tt>CMD.EXE</tt> or <tt>COMMAND.COM</tt>), hence Unixy
--   shell tricks will not work.
--   
--   On Unix systems, see <a>waitForProcess</a> for the meaning of exit
--   codes when the process died as the result of a signal.
system :: String -> IO ExitCode

-- | The computation <tt><a>rawSystem</a> <i>cmd</i> <i>args</i></tt> runs
--   the operating system command <tt><i>cmd</i></tt> in such a way that it
--   receives as arguments the <tt><i>args</i></tt> strings exactly as
--   given, with no funny escaping or shell meta-syntax expansion. It will
--   therefore behave more portably between operating systems than
--   <a>system</a>.
--   
--   The return codes and possible failures are the same as for
--   <a>system</a>.
rawSystem :: String -> [String] -> 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 ()
