-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Iteratee-based I/O
--   
--   The IterateeGM monad provides strict, safe, and functional I/O. In
--   addition to pure Iteratee processors, file IO and combinator functions
--   are provided.
@package iteratee
@version 0.3.4

module Data.Iteratee.Base.LooseMap

-- | Enable map functions for containers that require class contexts on the
--   element types. There's really no reason to ever use this with types
--   that are fully polymorphic, such as Lists.
class LooseMap c el el'
looseMap :: (LooseMap c el el') => (el -> el') -> c el -> c el'


-- | Monadic and General Iteratees: incremental input parsers, processors
--   and transformers
module Data.Iteratee.Base.StreamChunk

-- | Class of types that can be used to hold chunks of data within Iteratee
--   streams.
class (ListLike (c el) el) => StreamChunk c el
length :: (StreamChunk c el) => c el -> Int
null :: (StreamChunk c el) => c el -> Bool
cons :: (StreamChunk c el) => el -> c el -> c el
head :: (StreamChunk c el) => c el -> el
tail :: (StreamChunk c el) => c el -> c el
findIndex :: (StreamChunk c el) => (el -> Bool) -> c el -> Maybe Int
splitAt :: (StreamChunk c el) => Int -> c el -> (c el, c el)
dropWhile :: (StreamChunk c el) => (el -> Bool) -> c el -> c el
fromList :: (StreamChunk c el) => [el] -> c el
toList :: (StreamChunk c el) => c el -> [el]
cMap :: (StreamChunk c el, StreamChunk c el') => (el -> el') -> c el -> c el'

-- | Class of streams which can be filled from a <a>Ptr</a>. Typically
--   these are streams which can be read from a file. The Int parameter is
--   the length of the data in bytes. N.B. The pointer must not be returned
--   or used after readFromPtr completes.
class (StreamChunk s el, Storable el) => ReadableChunk s el
readFromPtr :: (ReadableChunk s el) => Ptr (el) -> Int -> IO (s el)
instance ReadableChunk [] Word
instance ReadableChunk [] Word32
instance ReadableChunk [] Word16
instance ReadableChunk [] Word8
instance ReadableChunk [] Char
instance StreamChunk [] el

module Data.Iteratee.WrappedByteString

-- | Wrap a Data.ByteString ByteString
newtype WrappedByteString a
WrapBS :: ByteString -> WrappedByteString a
unWrap :: WrappedByteString a -> ByteString
instance StreamChunk WrappedByteString Char
instance StringLike (WrappedByteString Char)
instance ListLike (WrappedByteString Char) Char
instance FoldableLL (WrappedByteString Char) Char
instance Monoid (WrappedByteString Char)
instance StreamChunk WrappedByteString Word8
instance ListLike (WrappedByteString Word8) Word8
instance ReadableChunk WrappedByteString Char
instance ReadableChunk WrappedByteString Word8
instance FoldableLL (WrappedByteString Word8) Word8
instance Monoid (WrappedByteString Word8)

module Data.Iteratee.IO.Posix
type FileOffset = COff

-- | Alas, GHC provides no function to read from Fd to an allocated buffer.
--   The library function fdRead is not appropriate as it returns a string
--   already. I'd rather get data from a buffer. Furthermore, fdRead (at
--   least in GHC) allocates a new buffer each time it is called. This is a
--   waste. Yet another problem with fdRead is in raising an exception on
--   any IOError or even EOF. I'd rather avoid exceptions altogether.
myfdRead :: Fd -> Ptr CChar -> ByteCount -> IO (Either Errno ByteCount)

-- | The following fseek procedure throws no exceptions.
myfdSeek :: Fd -> SeekMode -> FileOffset -> IO (Either Errno FileOffset)

-- | Haskell representation for <tt>errno</tt> values. The implementation
--   is deliberately exposed, to allow users to add their own definitions
--   of <a>Errno</a> values.
newtype Errno :: *
Errno :: CInt -> Errno

-- | poll if file descriptors have something to read Return the list of
--   read-pending descriptors
select'read'pending :: [Fd] -> IO (Either Errno [Fd])


-- | Monadic and General Iteratees: incremental input parsers, processors
--   and transformers
module Data.Iteratee.Base
data ErrMsg
Err :: String -> ErrMsg
Seek :: FileOffset -> ErrMsg

-- | A stream is a (continuing) sequence of elements bundled in Chunks. The
--   first two variants indicate termination of the stream. Chunk a gives
--   the currently available part of the stream. The stream is not
--   terminated yet. The case (null Chunk) signifies a stream with no
--   currently available data but which is still continuing. A stream
--   processor should, informally speaking, ``suspend itself'' and wait for
--   more data to arrive.
data StreamG c el
EOF :: (Maybe ErrMsg) -> StreamG c el
Chunk :: (c el) -> StreamG c el

-- | Iteratee -- a generic stream processor, what is being folded over a
--   stream When Iteratee is in the <tt>done</tt> state, it contains the
--   computed result and the remaining part of the stream. In the
--   <tt>cont</tt> state, the iteratee has not finished the computation and
--   needs more input. We assume that all iteratees are <tt>good</tt> --
--   given bounded input, they do the bounded amount of computation and
--   take the bounded amount of resources. The monad m describes the sort
--   of computations done by the iteratee as it processes the stream. The
--   monad m could be the identity monad (for pure computations) or the IO
--   monad (to let the iteratee store the stream processing results as they
--   are computed). We also assume that given a terminated stream, an
--   iteratee moves to the done state, so the results computed so far could
--   be returned.
data IterGV c el m a
Done :: a -> (StreamG c el) -> IterGV c el m a
Cont :: (IterateeG c el m a) -> (Maybe ErrMsg) -> IterGV c el m a
newtype IterateeG c el m a
IterateeG :: (StreamG c el -> m (IterGV c el m a)) -> IterateeG c el m a
runIter :: IterateeG c el m a -> StreamG c el -> m (IterGV c el m a)

-- | The type of the converter from the stream with elements el_outer to
--   the stream with element el_inner. The result is the iteratee for the
--   outer stream that uses an `IterateeG el_inner m a' to process the
--   embedded, inner stream as it reads the outer stream.
type EnumeratorN s_outer el_outer s_inner el_inner m a = IterateeG s_inner el_inner m a -> IterateeG s_outer el_outer m (IterateeG s_inner el_inner m a)

-- | Each enumerator takes an iteratee and returns an iteratee an
--   Enumerator is an iteratee transformer. The enumerator normally stops
--   when the stream is terminated or when the iteratee moves to the done
--   state, whichever comes first. When to stop is of course up to the
--   enumerator...
type EnumeratorGM s el m a = IterateeG s el m a -> m (IterateeG s el m a)

-- | More general enumerator type: enumerator that maps streams (not
--   necessarily in lock-step). This is a flattened (`joinI-ed')
--   EnumeratorN sfrom elfrom sto elto m a
type EnumeratorGMM sfrom elfrom sto elto m a = IterateeG sto elto m a -> m (IterateeG sfrom elfrom m a)

-- | The following is a <tt>variant</tt> of join in the IterateeGM s el m
--   monad When el' is the same as el, the type of joinI is indeed that of
--   true monadic join. However, joinI is subtly different: since generally
--   el' is different from el, it makes no sense to continue using the
--   internal, IterateeG el' m a: we no longer have elements of the type
--   el' to feed to that iteratee. We thus send EOF to the internal
--   Iteratee and propagate its result. This join function is useful when
--   dealing with `derived iteratees' for embedded/nested streams. In
--   particular, joinI is useful to process the result of take, mapStream,
--   or convStream below.
joinI :: (StreamChunk s el, StreamChunk s' el', Monad m) => IterateeG s el m (IterateeG s' el' m a) -> IterateeG s el m a

-- | Lift an IterGV result into an <a>IterateeG</a>
liftI :: (Monad m, StreamChunk s el) => IterGV s el m a -> IterateeG s el m a

-- | Check if a stream has finished (<a>EOF</a>).
isFinished :: (StreamChunk s el, Monad m) => IterateeG s el m (Maybe ErrMsg)

-- | Run an <a>IterateeG</a> and get the result. An <a>EOF</a> is sent to
--   the iteratee as it is run.
run :: (Monad m, StreamChunk s el) => IterateeG s el m a -> m a

-- | A variant of join for Iteratees in a monad.
joinIM :: (Monad m) => m (IterateeG s el m a) -> IterateeG s el m a

-- | Read a stream to the end and return all of its elements as a list
stream2list :: (StreamChunk s el, Monad m) => IterateeG s el m [el]

-- | Read a stream to the end and return all of its elements as a stream
stream2stream :: (StreamChunk s el, Monad m) => IterateeG s el m (s el)

-- | If the iteratee (<a>IterGV</a>) has finished, return its value. If it
--   has not finished then apply it to the given <a>EnumeratorGM</a>. If in
--   error, throw the error.
checkIfDone :: (StreamChunk s el, Monad m) => (IterateeG s el m a -> m (IterateeG s el m a)) -> IterGV s el m a -> m (IterateeG s el m a)

-- | Layer a monad transformer over the inner monad.
liftInner :: (Monad m, MonadTrans t, Monad (t m)) => IterateeG s el m a -> IterateeG s el (t m) a

-- | Produce the EOF error message. If the stream was terminated because of
--   an error, keep the original error message.
setEOF :: StreamG c el -> ErrMsg

-- | Report and propagate an error. Disregard the input first and then
--   propagate the error.
throwErr :: (Monad m) => ErrMsg -> IterateeG s el m a

-- | Check if an iteratee produces an error. Returns 'Right a' if it
--   completes without errors, otherwise 'Left ErrMsg' checkErr is useful
--   for iteratees that may not terminate, such as <a>head</a> with an
--   empty stream. In particular, it enables them to be used with
--   <a>convStream</a>.
checkErr :: (Monad m, StreamChunk s el) => IterateeG s el m a -> IterateeG s el m (Either ErrMsg a)

-- | The analogue of List.break It takes an element predicate and returns
--   the (possibly empty) prefix of the stream. None of the characters in
--   the string satisfy the character predicate. If the stream is not
--   terminated, the first character on the stream satisfies the predicate.
break :: (StreamChunk s el, Monad m) => (el -> Bool) -> IterateeG s el m (s el)

-- | Skip all elements while the predicate is true. This is the analogue of
--   List.dropWhile
dropWhile :: (StreamChunk s el, Monad m) => (el -> Bool) -> IterateeG s el m ()

-- | Skip n elements of the stream, if there are that many This is the
--   analogue of List.drop
drop :: (StreamChunk s el, Monad m) => Int -> IterateeG s el m ()

-- | The identity iterator. Doesn't do anything.
identity :: (Monad m) => IterateeG s el m ()

-- | Attempt to read the next element of the stream and return it Raise a
--   (recoverable) error if the stream is terminated
head :: (StreamChunk s el, Monad m) => IterateeG s el m el

-- | Given a sequence of characters, attempt to match them against the
--   characters on the stream. Return the count of how many characters
--   matched. The matched characters are removed from the stream. For
--   example, if the stream contains <a>abd</a>, then (heads <a>abc</a>)
--   will remove the characters <a>ab</a> and return 2.
heads :: (StreamChunk s el, Monad m, Eq el) => s el -> IterateeG s el m Int

-- | Look ahead at the next element of the stream, without removing it from
--   the stream. Return (Just c) if successful, return Nothing if the
--   stream is terminated (by EOF or an error)
peek :: (StreamChunk s el, Monad m) => IterateeG s el m (Maybe el)

-- | Skip the rest of the stream
skipToEof :: (Monad m) => IterateeG s el m ()

-- | Return the total length of the stream
length :: (Num a, ListLike (s el) el, Monad m) => IterateeG s el m a

-- | Read n elements from a stream and apply the given iteratee to the
--   stream of the read elements. Unless the stream is terminated early, we
--   read exactly n elements (even if the iteratee has accepted fewer).
take :: (StreamChunk s el, Monad m) => Int -> EnumeratorN s el s el m a

-- | Read n elements from a stream and apply the given iteratee to the
--   stream of the read elements. If the given iteratee accepted fewer
--   elements, we stop. This is the variation of <a>take</a> with the early
--   termination of processing of the outer stream once the processing of
--   the inner stream finished early.
takeR :: (StreamChunk s el, Monad m) => Int -> EnumeratorN s el s el m a

-- | Map the stream: yet another iteratee transformer Given the stream of
--   elements of the type el and the function el-&gt;el', build a nested
--   stream of elements of the type el' and apply the given iteratee to it.
--   Note the contravariance
mapStream :: (StreamChunk s el, StreamChunk s el', Monad m) => (el -> el') -> EnumeratorN s el s el' m a

-- | Map a stream without changing the element type. For StreamChunks with
--   limited element types (e.g. bytestrings) this can be much more
--   efficient than regular mapStream
rigidMapStream :: (StreamChunk s el, Monad m) => (el -> el) -> EnumeratorN s el s el m a

-- | Yet another stream mapping function. For container instances with
--   class contexts, such as uvector or storablevector, this allows the
--   native map function to be used and is likely to be much more efficient
--   than the standard mapStream.
looseMapStream :: (StreamChunk s el, StreamChunk s el', LooseMap s el el', Monad m) => (el -> el') -> EnumeratorN s el s el' m a

-- | Convert one stream into another, not necessarily in <tt>lockstep</tt>
--   The transformer mapStream maps one element of the outer stream to one
--   element of the nested stream. The transformer below is more general:
--   it may take several elements of the outer stream to produce one
--   element of the inner stream, or the other way around. The
--   transformation from one stream to the other is specified as IterateeGM
--   s el m (Maybe (s' el')). The Maybe type is in case of errors (or end
--   of stream).
convStream :: (Monad m) => IterateeG s el m (Maybe (s' el')) -> EnumeratorN s el s' el' m a

-- | Creates an enumerator with only elements from the stream that satisfy
--   the predicate function.
filter :: (ListLike (s el) el, Monad m) => (el -> Bool) -> EnumeratorN s el s el m a

-- | Left-associative fold.
foldl :: (ListLike (s el) el, FoldableLL (s el) el, Monad m) => (a -> el -> a) -> a -> IterateeG s el m a

-- | Left-associative fold that is strict in the accumulator.
foldl' :: (ListLike (s el) el, FoldableLL (s el) el, Monad m) => (a -> el -> a) -> a -> IterateeG s el m a

-- | Variant of foldl with no base case. Requires at least one element in
--   the stream.
foldl1 :: (ListLike (s el) el, FoldableLL (s el) el, Monad m) => (el -> el -> el) -> IterateeG s el m el

-- | Sum of a stream.
sum :: (ListLike (s el) el, Num el, Monad m) => IterateeG s el m el

-- | Product of a stream
product :: (ListLike (s el) el, Num el, Monad m) => IterateeG s el m el

-- | The most primitive enumerator: applies the iteratee to the terminated
--   stream. The result is the iteratee usually in the done state.
enumEof :: (Monad m) => EnumeratorGM s el m a

-- | Another primitive enumerator: report an error
enumErr :: (StreamChunk s el, Monad m) => String -> EnumeratorGM s el m a

-- | The pure 1-chunk enumerator It passes a given list of elements to the
--   iteratee in one chunk This enumerator does no IO and is useful for
--   testing of base parsing
enumPure1Chunk :: (StreamChunk s el, Monad m) => s el -> EnumeratorGM s el m a

-- | The pure n-chunk enumerator It passes a given chunk of elements to the
--   iteratee in n chunks This enumerator does no IO and is useful for
--   testing of base parsing and handling of chunk boundaries
enumPureNChunk :: (StreamChunk s el, Monad m) => s el -> Int -> EnumeratorGM s el m a

-- | The composition of two enumerators: essentially the functional
--   composition It is convenient to flip the order of the arguments of the
--   composition though: in e1 &gt;. e2, e1 is executed first
(>.) :: (StreamChunk s el, Monad m) => EnumeratorGM s el m a -> EnumeratorGM s el m a -> EnumeratorGM s el m a

-- | Enumerate two iteratees over a single stream simultaneously.
enumPair :: (ListLike (s el) el, Monad m) => IterateeG s el m a -> IterateeG s el m b -> IterateeG s el m (a, b)

-- | Seek to a position in the stream
seek :: (Monad m) => FileOffset -> IterateeG s el m ()
type FileOffset = COff
instance Show ErrMsg
instance Eq ErrMsg
instance (MonadIO m) => MonadIO (IterateeG s el m)
instance MonadTrans (IterateeG s el)
instance (Monad m, Functor m) => Applicative (IterateeG s el m)
instance (Monad m, Functor m) => Functor (IterateeG s el m)
instance (Monad m) => Monad (IterateeG s el m)
instance (Show (c el), Show a) => Show (IterGV c el m a)
instance Monoid ErrMsg
instance (Monoid (c el)) => Monoid (StreamG c el)
instance (Functor c) => Functor (StreamG c)
instance (Show (c el)) => Show (StreamG c el)
instance (Eq (c el)) => Eq (StreamG c el)


-- | Iteratees for parsing binary data.
module Data.Iteratee.Binary

-- | Indicate endian-ness.
data Endian

-- | Most Significant Byte is first (big-endian)
MSB :: Endian

-- | Least Significan Byte is first (little-endian)
LSB :: Endian
endianRead2 :: (StreamChunk s Word8, Monad m) => Endian -> IterateeG s Word8 m Word16

-- | read 3 bytes in an endian manner. If the first bit is set (negative),
--   set the entire first byte so the Word32 can be properly set negative
--   as well.
endianRead3 :: (StreamChunk s Word8, Monad m) => Endian -> IterateeG s Word8 m Word32
endianRead4 :: (StreamChunk s Word8, Monad m) => Endian -> IterateeG s Word8 m Word32
instance Eq Endian
instance Ord Endian
instance Show Endian
instance Enum Endian


-- | Random and Binary IO with generic Iteratees, using File Descriptors
--   for IO. when available, these are the preferred functions for
--   performing IO as they run in constant space and function properly with
--   sockets, pipes, etc.
module Data.Iteratee.IO.Fd

-- | The enumerator of a POSIX File Descriptor. This version enumerates
--   over the entire contents of a file, in order, unless stopped by the
--   iteratee. In particular, seeking is not supported.
enumFd :: (ReadableChunk s el, MonadIO m) => Fd -> EnumeratorGM s el m a

-- | The enumerator of a POSIX File Descriptor: a variation of enumFd that
--   supports RandomIO (seek requests)
enumFdRandom :: (ReadableChunk s el, MonadIO m) => Fd -> EnumeratorGM s el m a

-- | Process a file using the given IterateeGM. This function wraps enumFd
--   as a convenience.
fileDriverFd :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a

-- | Process a file using the given IterateeGM. This function wraps
--   enumFdRandom as a convenience.
fileDriverRandomFd :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a


-- | Utilties for Char-based iteratee processing.
module Data.Iteratee.Char

-- | A particular instance of StreamG: the stream of characters. This
--   stream is used by many input parsers.
type Stream = StreamG [] Char
type Iteratee = IterateeG [] Char
type EnumeratorM m a = EnumeratorGM [] Char m a
type Line = String

-- | Read the line of text from the stream The line can be terminated by
--   CR, LF or CRLF. Return (Right Line) if successful. Return (Left Line)
--   if EOF or a stream error were encountered before the terminator is
--   seen. The returned line is the string read so far.
line :: (Monad m) => IterateeG [] Char m (Either Line Line)

-- | Print lines as they are received. This is the first <tt>impure</tt>
--   iteratee with non-trivial actions during chunk processing
printLines :: IterateeG [] Char IO ()

-- | Read a sequence of lines from the stream up to the empty lin The line
--   can be terminated by CR, LF, or CRLF -- or by EOF or stream error.
--   Return the read lines, in order, not including the terminating empty
--   line Upon EOF or stream error, return the complete, terminated lines
--   accumulated so far.
readLines :: (Monad m) => IterateeG [] Char m (Either [Line] [Line])

-- | Convert the stream of characters to the stream of lines, and apply the
--   given iteratee to enumerate the latter. The stream of lines is
--   normally terminated by the empty line. When the stream of characters
--   is terminated, the stream of lines is also terminated, abnormally.
--   This is the first proper iteratee-enumerator: it is the iteratee of
--   the character stream and the enumerator of the line stream.
enumLines :: (ListLike (s el) el, StringLike (s el), Functor m, Monad m) => IterateeG [] (s el) m a -> IterateeG s el m (IterateeG [] (s el) m a)

-- | Convert the stream of characters to the stream of words, and apply the
--   given iteratee to enumerate the latter. Words are delimited by white
--   space. This is the analogue of List.words One should keep in mind that
--   enumWords is a more general, monadic function.
enumWords :: (ListLike (s el) el, StringLike (s el), Functor m, Monad m) => IterateeG [] (s el) m a -> IterateeG s el m (IterateeG [] (s el) m a)


-- | Random and Binary IO with generic Iteratees. These functions use
--   Handles for IO operations, and are provided for compatibility. When
--   available, the File Descriptor based functions are preferred as these
--   wastefully allocate memory rather than running in constant space.
module Data.Iteratee.IO.Handle

-- | The enumerator of a file Handle. This version enumerates over the
--   entire contents of a file, in order, unless stopped by the iteratee.
--   In particular, seeking is not supported.
enumHandle :: (ReadableChunk s el, MonadIO m) => Handle -> EnumeratorGM s el m a

-- | The enumerator of a Handle: a variation of enumHandle that supports
--   RandomIO (seek requests)
enumHandleRandom :: (ReadableChunk s el, MonadIO m) => Handle -> EnumeratorGM s el m a

-- | Process a file using the given IterateeGM. This function wraps
--   enumHandle as a convenience.
fileDriverHandle :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a

-- | Process a file using the given IterateeGM. This function wraps
--   enumHandleRandom as a convenience.
fileDriverRandomHandle :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a


-- | Random and Binary IO with generic Iteratees.
module Data.Iteratee.IO

-- | The enumerator of a file Handle. This version enumerates over the
--   entire contents of a file, in order, unless stopped by the iteratee.
--   In particular, seeking is not supported.
enumHandle :: (ReadableChunk s el, MonadIO m) => Handle -> EnumeratorGM s el m a

-- | The enumerator of a Handle: a variation of enumHandle that supports
--   RandomIO (seek requests)
enumHandleRandom :: (ReadableChunk s el, MonadIO m) => Handle -> EnumeratorGM s el m a

-- | The enumerator of a POSIX File Descriptor. This version enumerates
--   over the entire contents of a file, in order, unless stopped by the
--   iteratee. In particular, seeking is not supported.
enumFd :: (ReadableChunk s el, MonadIO m) => Fd -> EnumeratorGM s el m a

-- | The enumerator of a POSIX File Descriptor: a variation of enumFd that
--   supports RandomIO (seek requests)
enumFdRandom :: (ReadableChunk s el, MonadIO m) => Fd -> EnumeratorGM s el m a

-- | Process a file using the given IterateeG. This function wraps enumFd
--   as a convenience.
fileDriver :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a

-- | Process a file using the given IterateeG. This function wraps
--   enumFdRandom as a convenience.
fileDriverRandom :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a


-- | Provide iteratee-based IO as described in Oleg Kiselyov's paper
--   http:<i></i>okmij.org<i>ftp</i>Haskell<i>Iteratee</i>.
--   
--   Oleg's original code uses lists to store buffers of data for reading
--   in the iteratee. This package allows the use of arbitrary types
--   through use of the StreamChunk type class. See
--   Data.Iteratee.WrappedByteString for implementation details.
module Data.Iteratee

-- | Process a file using the given IterateeG. This function wraps enumFd
--   as a convenience.
fileDriver :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a

-- | Process a file using the given IterateeG. This function wraps
--   enumFdRandom as a convenience.
fileDriverRandom :: (MonadIO m, ReadableChunk s el) => IterateeG s el m a -> FilePath -> m a