Data.IterIO.ListLike

This module contains basic iteratees and enumerators for working with strings, ListLike objects, file handles, and stream and datagram sockets.

Iteratees

putI :: (ChunkData t, Monad m) => (t -> Iter t m a) -> Iter t m b -> Iter t m ()

An Iteratee that puts data to a consumer function, then calls an eof function. For instance, handleI could be defined as:

 handleI :: (MonadIO m) => Handle -> Iter ByteString m ()
 handleI h = putI (liftIO . hPut h) (liftIO $ hShutdown h 1)

sendI :: (Show t, Monad m) => (t -> Iter [t] m a) -> Iter [t] m ()

Send datagrams using a supplied function. The datagrams are fed as a list of packets, where each element of the list should be a separate datagram. For example, to create an Iter from a connected UDP socket:

 udpI :: (SendRecvString s, MonadIO m) => Socket -> Iter s m ()
 udpI sock = sendI $ liftIO . genSend sock

headLI :: (Show a, Monad m) => Iter [a] m a

Return the first element when the Iteratee data type is a list.

safeHeadLI :: (Show a, Monad m) => Iter [a] m (Maybe a)

Return Just the first element when the Iteratee data type is a list, or Nothing on EOF.

headI :: (ChunkData t, ListLike t e, Monad m) => Iter t m e

Like headLI, but works for any ListLike data type.

safeHeadI :: (ChunkData t, ListLike t e, Monad m) => Iter t m (Maybe e)

Like safeHeadLI, but works for any ListLike data type.

lineI :: (Monad m, ChunkData t, ListLike t e, Eq t, Enum e, Eq e) => Iter t m t

Return a line delimited by \r, \n, or \r\n.

safeLineI :: (ChunkData t, Monad m, ListLike t e, Eq t, Enum e, Eq e) => Iter t m (Maybe t)

Like lineI, but returns Nothing on EOF.

dataMaxI :: (ChunkData t, ListLike t e, Monad m) => Int -> Iter t m t

Return ListLike data that is at most the number of elements specified by the first argument, and at least one element (as long as a positive number is requested). Throws an exception if a positive number of items is requested and an EOF is encountered.

data0MaxI :: (ChunkData t, ListLike t e, Monad m) => Int -> Iter t m t

Return ListLike data that is at most the number of elements specified by the first argument, and at least one element unless EOF is encountered or 0 elements are requested, in which case mempty is returned.

takeI :: (ChunkData t, ListLike t e, Monad m) => Int -> Iter t m t

Return the next len elements of a ListLike data stream, unless an EOF is encountered, in which case fewer may be returned. Note the difference from data0MaxI: takeI n will keep reading input until it has accumulated n elements or seen an EOF, then return the data; data0MaxI n will keep reading only until it has received any non-empty amount of data, even if the amount received is less than n elements and there is no EOF.

handleI :: (MonadIO m, ChunkData t, ListLikeIO t e) => Handle -> Iter t m ()

Puts strings (or ListLikeIO data) to a file Handle, then writes an EOF to the handle.

Note that this does not put the handle into binary mode. To do this, you may need to call hSetBinaryMode h True on the handle before using it with handleI. Otherwise, Haskell by default will treat the data as UTF-8. (On the other hand, if the Handle corresponds to a socket and the socket is being read in another thread, calling hSetBinaryMode can cause deadlock, so in this case it is better to have the thread handling reads call hSetBinaryMode.)

Also note that Haskell by default buffers data written to Handles. For many network protocols this is a problem. Don't forget to call hSetBuffering h NoBuffering before passing a handle to handleI.

sockDgramI :: (MonadIO m, SendRecvString t) => Socket -> Maybe SockAddr -> Iter [t] m ()

Sends a list of packets to a datagram socket.

sockStreamI :: (ChunkData t, SendRecvString t, MonadIO m) => Socket -> Iter t m ()

Sends output to a stream socket. Calls shutdown (e.g., to send a TCP FIN packet) upon receiving EOF.

stdoutI :: (ListLikeIO t e, ChunkData t, MonadIO m) => Iter t m ()

An Iter that uses hPutStr to write all output to stdout.

Control requests

data SeekMode

A mode that determines the effect of hSeek hdl mode i.

Constructors

AbsoluteSeek

the position of hdl is set to i.

RelativeSeek

the position of hdl is set to offset i from the current position.

SeekFromEnd

the position of hdl is set to offset i from the end of the file.

Instances

Enum SeekMode

Eq SeekMode

Ord SeekMode

Read SeekMode

Show SeekMode

Ix SeekMode

data SizeC

A control command (issued with ctlI SizeC) requesting the size of the current file being enumerated.

Constructors

SizeC

Instances

Typeable SizeC

CtlCmd SizeC Integer

data SeekC

A control command for seeking within a file, when a file is being enumerated. Flushes the residual input data.

Constructors

SeekC !SeekMode !Integer

Instances

Typeable SeekC

CtlCmd SeekC ()

data TellC

A control command for determining the current offset within a file. Note that this subtracts the size of the residual input data from the offset in the file. Thus, it will only be accurate when all left-over input data is from the current file.

Constructors

TellC

Instances

Typeable TellC

CtlCmd TellC Integer

fileCtl :: (ChunkData t, ListLike t e, MonadIO m) => Handle -> CtlHandler (Iter () m) t m a

A handler function for the SizeC, SeekC, and TellC control requests. fileCtl is used internally by enumFile and enumHandle, and is exposed for similar enumerators to use.

data GetSocketC

A control request that returns the Socket from an enclosing socket enumerator.

Constructors

GetSocketC

Instances

Typeable GetSocketC

CtlCmd GetSocketC Socket

socketCtl :: (ChunkData t, MonadIO m) => Socket -> CtlHandler (Iter () m) t m a

A handler for the GetSocketC control request.

Onums

enumDgram :: (MonadIO m, SendRecvString t) => Socket -> Onum [t] m a

Read datagrams (of up to 64KiB in size) from a socket and feed a list of strings (one for each datagram) into an Iteratee.

enumDgramFrom :: (MonadIO m, SendRecvString t) => Socket -> Onum [(t, SockAddr)] m a

Read datagrams from a socket and feed a list of (Bytestring, SockAddr) pairs (one for each datagram) into an Iteratee.

enumStream :: (MonadIO m, ChunkData t, SendRecvString t) => Socket -> Onum t m a

Read data from a stream (e.g., TCP) socket.

enumHandle :: (MonadIO m, ChunkData t, ListLikeIO t e) => Handle -> Onum t m a

Puts a handle into binary mode with hSetBinaryMode, then enumerates data read from the handle to feed an Iter with any ListLikeIO input type.

enumHandle' :: MonadIO m => Handle -> Onum ByteString m a

A variant of enumHandle type restricted to input in the Lazy ByteString format.

enumNonBinHandle :: (MonadIO m, ChunkData t, ListLikeIO t e) => Handle -> Onum t m a

Feeds an Iter with data from a file handle, using any input type in the ListLikeIO class. Note that enumNonBinHandle uses the handle as is, unlike enumHandle, and so can be used if you want to read the data in non-binary form.

enumFile :: (MonadIO m, ChunkData t, ListLikeIO t e) => FilePath -> Onum t m a

Enumerate the contents of a file for an Iter taking input in any ListLikeIO type. Note that the file is opened with openBinaryFile to ensure binary mode.

enumFile' :: MonadIO m => FilePath -> Onum ByteString m a

Enumerate the contents of a file as a series of lazy ByteStrings. (This is a type-restricted version of enumFile.)

enumStdin :: (MonadIO m, ChunkData t, ListLikeIO t e) => Onum t m a

Enumerate standard input.

Inums

inumMax :: (ChunkData t, ListLike t e, Monad m) => Int -> Inum t t m a

Feed up to some number of list elements (bytes in the case of ByteStrings) to an Iter, or feed fewer if the Iter returns or an EOF is encountered. The formulation inumMax n .| iter can be used to prevent iter from consuming unbounded amounts of input.

inumTakeExact :: (ChunkData t, ListLike t e, Monad m) => Int -> Inum t t m a

Feed exactly some number of bytes to an Iter. Throws an error if that many bytes are not available.

inumLog

Arguments

:: (MonadIO m, ChunkData t, ListLikeIO t e)

=> FilePath

Path to log to

-> Bool

True to truncate file

-> Inum t t m a

This inner enumerator is like inumNop in that it passes unmodified Chunks straight through to an iteratee. However, it also logs the Chunks to a file (which can optionally be truncated or appended to, based on the second argument).

inumhLog :: (MonadIO m, ChunkData t, ListLikeIO t e) => Handle -> Inum t t m a

Like inumLog, but takes a writeable file handle rather than a file name. Does not close the handle when done.

inumStderr :: (MonadIO m, ChunkData t, ListLikeIO t e) => Inum t t m a

Log a copy of everything to standard error. (inumStderr = inumhLog stderr)

inumLtoS :: Monad m => Inum ByteString ByteString m a

An Inum that converts input in the lazy ByteString format to strict ByteStrings.

inumStoL :: Monad m => Inum ByteString ByteString m a

The dual of inumLtoS--converts input from strict ByteStrings to lazy ByteStrings.

Functions for Iter-Inum pairs

pairFinalizer

Arguments

:: (ChunkData t, ChunkData t1, ChunkData t2, MonadIO m, MonadIO m1)

=> Iter t m a

-> Inum t1 t2 m1 b

-> IO ()

Cleanup action

-> IO (Iter t m a, Inum t1 t2 m1 b)

Cleanup action will run when these two are both done

Add a finalizer to run when an Iter has received an EOF and an Inum has finished. This works regardless of the order in which the two events happen.

iterHandle :: (ListLikeIO t e, ChunkData t, MonadIO m) => Handle -> IO (Iter t m (), Onum t m a)

"Iterizes" a file Handle by turning into an Onum (for reading) and an Iter (for writing). Uses pairFinalizer to hClose the Handle when both the Iter and Onum are finished. Puts the handle into binary mode, but does not change the buffering. As mentioned for handleI, Haskell's default buffering can cause problems for many network protocols. Hence, you may wish to call hSetBuffering h NoBuffering before iterHandle h.

iterStream :: (SendRecvString t, ChunkData t, MonadIO m) => Socket -> IO (Iter t m (), Onum t m a)

"Iterizes" a stream Socket by turning into an Onum (for reading) and an Iter (for writing). Uses pairFinalizer to sClose the Socket when both the Iter and Onum are finished.