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 "System.IO.Streams", which re-exports most of the library:
import "System.IO.Streams" (InputStream, OutputStream)
import qualified "System.IO.Streams" as Streams
For first-time users, @io-streams@ comes with an included tutorial, which can
be found in the "System.IO.Streams.Tutorial" module.
The @io-streams@ user API has two basic types: @InputStream a@ and
@OutputStream a@, and three fundamental I/O primitives:
\-\- read an item from an input stream
Streams.'System.IO.Streams.read' :: 'System.IO.Streams.InputStream' a -> IO (Maybe a)
\-\- push an item back to an input stream
Streams.'System.IO.Streams.unRead' :: a -> 'System.IO.Streams.InputStream' a -> IO ()
\-\- write to an output stream
Streams.'System.IO.Streams.write' :: Maybe a -> 'System.IO.Streams.OutputStream' a -> IO ()
Streams can be transformed by composition and hooked together with provided combinators:
ghci> Streams.fromList [1,2,3::Int] >>= Streams.map (*10) >>= Streams.toList
Stream composition leaves the original stream accessible:
ghci> input \<- Streams.fromByteString \"long string\"
ghci> wrapped \<- Streams.takeBytes 4 input
ghci> Streams.read wrapped
ghci> Streams.read wrapped
ghci> Streams.read input
Just \" string\"
Simple types and operations in the IO monad mean straightforward and simple
exception handling and resource cleanup using Haskell standard library
facilities like 'Control.Exception.bracket'.
@io-streams@ comes with:
* functions to use files, handles, concurrent channels, sockets, lists,
vectors, and more as streams.
* 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.
* support for parsing from streams using @attoparsec@.
* support for spawning processes and communicating with them using streams.
[@18.104.22.168@] Fixed a build error with network versions older than 2.4.
[@22.214.171.124@] @System.IO.Streams.Network@: scalability improvement: buffers
for socket reads are now allocated by system malloc rather than
by pinned pointers in GHC (currently pinned pointer allocation
takes a global lock).
[@126.96.36.199@] Widened @attoparsec@ and @text@ library dependencies to allow
the latest versions.
[@188.8.131.52@] Added @System.IO.Streams.ByteString.takeExactly@. Widened
@network@ dependency to include 2.3. Added a
@NoInteractiveTests@ flag to selectively disable some tests for
environments where spawning interactive processes is
[@184.108.40.206@] Allowed newest versions of the @process@, @test-framework@,
and @text@ libraries.
[@220.127.116.11@] Fixed build error when compiled against attoparsec-0.10.0.x.
[@18.104.22.168@] Added @System.IO.Streams.Concurrent.makeChanPipe@, to create a
simple concurrent pipe between an @InputStream@/@OutputStream@
[@22.214.171.124@] Added @System.IO.Streams.Network.socketToStreamsWithBufferSize@,
allowing control over the size of the receive buffers used when
reading from sockets.
[@126.96.36.199@] Fixed an inconsistent version upper bound in the test suite.
[@188.8.131.52@] Fixed a typo in the tutorial.
[@184.108.40.206@] A couple of Haddock markup fixes.
[@220.127.116.11@] Reworked, simplified, and streamlined the internals of the
library. Exports from "System.IO.Streams.Internal" relying on
Sources and Sinks were deleted because they are no longer
necessary: Source(..), Sink(..), defaultPushback,
withDefaultPushback, nullSource, nullSink, singletonSource,
simpleSource, sourceToStream, sinkToStream, generatorToSource,
[@18.104.22.168@] Fixed a bug in which \"takeBytes 0\" was erroneously requesting
input from the wrapped stream.
[@22.214.171.124@] Fixed a compile error on GHC 7.0.x.
[@126.96.36.199@] Added "System.IO.Streams.Process" (support for communicating
with system processes using streams), added new functions to
"System.IO.Streams.Handle" for converting @io-streams@ types to
'System.IO.Handle's. (Now you can pass streams from this
library to places that expect Handles and everything will
[@188.8.131.52@] Added 'System.IO.Streams.Combinators.ignoreEof'.
[@184.108.40.206@] Fixed some haddock markup.