io-streams: Simple, composable, and easy-to-use stream I/O

Overview

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.

Features

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.read :: InputStream a -> IO (Maybe a)

-- push an item back to an input stream
Streams.unRead :: a -> InputStream a -> IO ()

-- write to an output stream
Streams.write :: Maybe a -> 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
[10,20,30]

Stream composition leaves the original stream accessible:

ghci> input <- Streams.fromByteString "long string"
ghci> wrapped <- Streams.takeBytes 4 input
ghci> Streams.read wrapped
Just "long"
ghci> Streams.read wrapped
Nothing
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.

• System
  • IO
    • System.IO.Streams
      • System.IO.Streams.Attoparsec
        • System.IO.Streams.Attoparsec.ByteString
        • System.IO.Streams.Attoparsec.Text
      • System.IO.Streams.Builder
      • System.IO.Streams.ByteString
      • System.IO.Streams.Combinators
      • System.IO.Streams.Concurrent
      • System.IO.Streams.Core
      • System.IO.Streams.Debug
      • System.IO.Streams.File
      • System.IO.Streams.Handle
      • System.IO.Streams.Internal
      • System.IO.Streams.List
      • System.IO.Streams.Network
      • System.IO.Streams.Process
      • System.IO.Streams.Text
      • System.IO.Streams.Tutorial
      • System.IO.Streams.Vector
      • System.IO.Streams.Zlib