-- 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           <a>System.IO.Streams</a> (InputStream, OutputStream)
--   import qualified <a>System.IO.Streams</a> 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.<a>System.IO.Streams.read</a> :: <a>System.IO.Streams.InputStream</a> a -&gt; IO (Maybe a)
--   
--   -- push an item back to an input stream
--   Streams.<a>System.IO.Streams.unRead</a> :: a -&gt; <a>System.IO.Streams.InputStream</a> a -&gt; IO ()
--   
--   -- write to an output stream
--   Streams.<a>System.IO.Streams.write</a> :: Maybe a -&gt; <a>System.IO.Streams.OutputStream</a> 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>
--   
--   <i>ChangeLog</i>
--   
--   <ul>
--   <li><i><tt>1.1.2.2</tt></i> Allowed newest versions of the
--   <tt>process</tt>, <tt>test-framework</tt>, and <tt>text</tt>
--   libraries.</li>
--   <li><i><tt>1.1.2.1</tt></i> Fixed build error when compiled against
--   attoparsec-0.10.0.x.</li>
--   <li><i><tt>1.1.2.0</tt></i> Added
--   <tt>System.IO.Streams.Concurrent.makeChanPipe</tt>, to create a simple
--   concurrent pipe between an <tt>InputStream</tt>/<tt>OutputStream</tt>
--   pair.</li>
--   <li><i><tt>1.1.1.0</tt></i> Added
--   <tt>System.IO.Streams.Network.socketToStreamsWithBufferSize</tt>,
--   allowing control over the size of the receive buffers used when
--   reading from sockets.</li>
--   <li><i><tt>1.1.0.3</tt></i> Fixed an inconsistent version upper bound
--   in the test suite.</li>
--   <li><i><tt>1.1.0.2</tt></i> Fixed a typo in the tutorial.</li>
--   <li><i><tt>1.1.0.1</tt></i> A couple of Haddock markup fixes.</li>
--   <li><i><tt>1.1.0.0</tt></i> Reworked, simplified, and streamlined the
--   internals of the library. Exports from
--   <a>System.IO.Streams.Internal</a> relying on Sources and Sinks were
--   deleted because they are no longer necessary: Source(..), Sink(..),
--   defaultPushback, withDefaultPushback, nullSource, nullSink,
--   singletonSource, simpleSource, sourceToStream, sinkToStream,
--   generatorToSource, and consumerToSink.</li>
--   <li><i><tt>1.0.2.2</tt></i> Fixed a bug in which "takeBytes 0" was
--   erroneously requesting input from the wrapped stream.</li>
--   <li><i><tt>1.0.2.1</tt></i> Fixed a compile error on GHC 7.0.x.</li>
--   <li><i><tt>1.0.2.0</tt></i> Added <a>System.IO.Streams.Process</a>
--   (support for communicating with system processes using streams), added
--   new functions to <a>System.IO.Streams.Handle</a> for converting
--   <tt>io-streams</tt> types to <a>System.IO.Handle</a>s. (Now you can
--   pass streams from this library to places that expect Handles and
--   everything will work.)</li>
--   <li><i><tt>1.0.1.0</tt></i> Added
--   <a>System.IO.Streams.Combinators.ignoreEof</a>.</li>
--   <li><i><tt>1.0.0.1</tt></i> Fixed some haddock markup.</li>
--   </ul>
@package io-streams
@version 1.1.2.2

module System.IO.Streams.Tutorial


-- | 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 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 by supplying <a>Nothing</a>.
write :: Maybe a -> OutputStream 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.
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 Typeable2 SP
instance Typeable1 InputStream
instance Typeable1 OutputStream
instance Typeable2 Generator
instance Typeable2 Consumer
instance Applicative (Consumer r)
instance Functor (Consumer r)
instance MonadIO (Consumer c)
instance Monad (Consumer c)
instance Applicative (Generator r)
instance Functor (Generator r)
instance MonadIO (Generator r)
instance Monad (Generator r)
instance IODevice (StreamPair ByteString)
instance IODevice (InputStream ByteString)
instance IODevice (OutputStream ByteString)
instance BufferedIO (StreamPair ByteString)
instance BufferedIO (InputStream ByteString)
instance BufferedIO (OutputStream ByteString)
instance RawIO (StreamPair ByteString)
instance RawIO (OutputStream ByteString)
instance RawIO (InputStream ByteString)


-- | This module provides support for parsing values from
--   <tt>InputStream</tt>s using <tt>attoparsec</tt>.
module System.IO.Streams.Attoparsec

-- | Supplies an <tt>attoparsec</tt> <a>Parser</a> with an
--   <a>InputStream</a>, returning the final parsed value or a
--   <a>ParseException</a> if parsing fails.
--   
--   <a>parseFromStream</a> consumes only as much input as necessary to
--   satisfy the <a>Parser</a> and unconsumed input is pushed back onto the
--   <a>InputStream</a>.
--   
--   If the <a>Parser</a> exhausts the <a>InputStream</a>, it receives an
--   <tt>EOF</tt>.
--   
--   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; <tt>read</tt> is'
--   Just 1
--   ghci&gt; <tt>read</tt> is'
--   Just 2
--   ghci&gt; <tt>read</tt> 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


-- | 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.
--   
--   This traps exceptions in each concurrent thread and re-raises them in
--   the current thread.
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)


-- | 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 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.
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 by supplying <a>Nothing</a>.
write :: Maybe a -> OutputStream 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 ()

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


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


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


-- | Converting network <a>Socket</a>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)


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

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


-- | 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.
handleToOutputStream :: Handle -> IO (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, an empty string is written to the output, as is
--   conventional throughout the <tt>io-streams</tt> library for
--   <a>ByteString</a> output buffers.
--   
--   Note: 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


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

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

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

-- | 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 (<a>Allow </a> ++ show a ++ <a>?</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)

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


-- | A module adapting the functions from <a>System.Process</a> to work
--   with <tt>io-streams</tt>.
module System.IO.Streams.Process

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


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

-- | 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> 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 Typeable TooManyBytesReadException
instance Typeable TooFewBytesWrittenException
instance Typeable TooManyBytesWrittenException
instance Typeable ReadTooShortException
instance Typeable RateTooSlowException
instance Exception RateTooSlowException
instance Show RateTooSlowException
instance Exception ReadTooShortException
instance Show ReadTooShortException
instance Exception TooManyBytesWrittenException
instance Show TooManyBytesWrittenException
instance Exception TooFewBytesWrittenException
instance Show TooFewBytesWrittenException
instance Exception TooManyBytesReadException
instance Show TooManyBytesReadException


-- | 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>blaze-builder</tt> package provides an efficient set of primitives
--   for serializing values directly to an output buffer.
--   
--   (<i>N.B.</i>: most of the <tt>blaze-builder</tt> package has been
--   moved into <tt>bytestring</tt> in versions &gt;= 0.10; once two or
--   three Haskell Platform editions have been released that contain
--   <tt>bytestring</tt> 0.10 or higher, the dependency on
--   <tt>blaze-builder</tt> will be dropped in favor of the native support
--   for <a>Builder</a> contained in the <tt>bytestring</tt> package.)
--   
--   <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>fromByteString</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
--   <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>fromByteString</a> l1 ++ [<a>flush</a>] ++ map <a>fromByteString</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)

-- | 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>allocBuffer</a>.
unsafeBuilderStream :: IO Buffer -> OutputStream ByteString -> IO (OutputStream Builder)

-- | A customized version of <a>builderStream</a>, using the specified
--   <a>BufferAllocStrategy</a>.
builderStreamWith :: BufferAllocStrategy -> OutputStream ByteString -> IO (OutputStream Builder)


-- | 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 Read CompressionLevel
instance Eq CompressionLevel
instance Show CompressionLevel
instance Num 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 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.
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 by supplying <a>Nothing</a>.
write :: Maybe a -> OutputStream 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 ()
