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


-- | Source/Sink/Transform: An alternative to lazy IO and iteratees.
--   
--   Haskell library for Sources, Sinks and Transformers. The data is
--   pushed from the source through the transfomers into the sink. The sink
--   or a transfomer can decide at any time to end the transfer (see
--   Iteratees). The transformers are very reusable since they can not
--   depend on side effects, so they can be used with files as well as with
--   simple lists.
--   
--   Allows you to build pipelines such as:
--   
--   <pre>
--   &gt;&gt;&gt; listSource [1..10] $$ T.map(+1) =$= T.buffer 3 0 (+) =$ listSink
--   [9,18,27,11]
--   </pre>
--   
--   its possible to mix various type of sources and sinks, such as in:
--   
--   <pre>
--   &gt;&gt;&gt; fileSourceLine \"myfile.txt\" $$ T.drop 1 =$= T.map (++ "!") =$ listSink
--   [\"Hello Mario!\", \"How're you doing?!\"]
--   </pre>
--   
--   For more documentation see
--   <a>https://github.com/msiegenthaler/SouSiT</a>.
@package sousit
@version 0.3

module Data.SouSiT.Sink
data Sink i m r
Sink :: m (SinkStatus i m r) -> Sink i m r
sinkStatus :: Sink i m r -> m (SinkStatus i m r)
data SinkStatus i m r
Cont :: (i -> Sink i m r) -> (m r) -> SinkStatus i m r
Done :: (m r) -> SinkStatus i m r

-- | Closes the sink and returns its result.
closeSink :: Monad m => Sink i m r -> m r

-- | Reads the next element. If the sink is closed while waiting for the
--   input, then the parameter is returned as the sinks result.
inputOr :: Monad m => m a -> Sink a m a

-- | Reads the next element. The sink returns a fail if it is closed before
--   the input is received.
input :: Monad m => Sink a m a

-- | Skips n input elements. If the sink is closed before then the result
--   will also be ().
skip :: (Eq n, Num n, Monad m) => n -> Sink a m ()

-- | Concatenates two sinks that produce a monoid.
appendSink :: (Monad m, Monoid r) => Sink a m r -> Sink a m r -> Sink a m r

-- | Concatenates two sinks that produce a monoid.
(=||=) :: (Monad m, Monoid r) => Sink a m r -> Sink a m r -> Sink a m r

-- | Feed a list of inputs to a sink.
feedList :: Monad m => [i] -> Sink i m r -> Sink i m r

-- | Changes the monad of a sink based upon a conversion function that maps
--   the original monad to the new one.
liftSink :: (Monad m, Monad m') => (forall x. m x -> m' x) -> Sink i m r -> Sink i m' r
contSink :: Monad m => (i -> Sink i m r) -> m r -> Sink i m r
doneSink :: Monad m => m r -> Sink i m r
doneSink' :: Monad m => r -> Sink i m r

-- | Sink that executes a monadic action per input received. Does not
--   terminate.
actionSink :: Monad m => (i -> m ()) -> Sink i m ()

-- | First calls open, then processes every input with process and when the
--   sink is closed close is called. Does not terminate.
openCloseActionSink :: Monad m => m a -> (a -> m ()) -> (a -> i -> m ()) -> Sink i m ()

-- | Sink that executes f for every input. The sink continues as long as
--   the action returns Nothing, when the action returns Just, then that
--   value is the result of the sink (and the sink is <tt>full</tt>).
maybeSink :: Monad m => (i -> m (Maybe r)) -> Sink i m (Maybe r)
instance Monad m => Applicative (Sink i m)
instance Monad m => Monad (Sink i m)
instance Monad m => Functor (Sink i m)

module Data.SouSiT.Source

-- | Something that produces data to be processed by a sink
class Source src
transfer :: (Source src, Monad m) => src m a -> Sink a m r -> m r

-- | A basic instance of Source
data SimpleSource m a
SimpleSource :: (forall r. Sink a m r -> m r) -> SimpleSource m a

-- | A basic instance of FeedSource (and Source)
data FeedSource m a
FeedSource :: (forall r. Sink a m r -> m (Sink a m r)) -> FeedSource m a
feedToSink :: FeedSource m a -> forall r. Sink a m r -> m (Sink a m r)

-- | Transfer the data from the source into the sink
($$) :: (Source src, Monad m) => src m a -> Sink a m r -> m r

-- | Concatenates two sources.
concatSources :: (Source src2, Monad m) => FeedSource m a -> src2 m a -> SimpleSource m a

-- | Concatenates two sources yielding a FeedSource.
concatSources' :: Monad m => FeedSource m a -> FeedSource m a -> FeedSource m a

-- | Concatenates two sources.
(=+=) :: Monad m => FeedSource m a -> FeedSource m a -> FeedSource m a

-- | Concatenates two sources.
(=+|=) :: (Source src2, Monad m) => FeedSource m a -> src2 m a -> SimpleSource m a

-- | Source that executes a monadic action to get its inputs. Terminates
--   when the sink terminates or the action returns Nothing.
actionSource :: Monad m => m (Maybe i) -> FeedSource m i

-- | Source that first opens a resource, then transfers itself to the sink
--   and the closes the resource again (in a bracket).
bracketActionSource :: IO a -> (a -> IO ()) -> (a -> IO (Maybe i)) -> FeedSource IO i
instance Source FeedSource
instance Source SimpleSource

module Data.SouSiT.Transform
type Transform a b = forall m r. Monad m => Sink b m r -> Sink a m r

-- | Merges two transforms into one.
mergeTransform :: Monad m => (Sink b m r -> Sink a m r) -> (Sink c m r -> Sink b m r) -> Sink c m r -> Sink a m r

-- | Apply a transform to a sink.
transformSink :: Monad m => (Sink b m r -> Sink a m r) -> Sink b m r -> Sink a m r

-- | Apply a transform to a Source.
transformSource :: (Source src, Monad m) => (forall r. Sink b m r -> Sink a m r) -> src m a -> SimpleSource m b

-- | Merges two transforms into one.
(=$=) :: Monad m => (Sink b m r -> Sink a m r) -> (Sink c m r -> Sink b m r) -> Sink c m r -> Sink a m r

-- | Apply a transform to a sink.
(=$) :: Monad m => (Sink b m r -> Sink a m r) -> Sink b m r -> Sink a m r

-- | Apply a transform to a source.
($=) :: (Source src, Monad m) => src m a -> (forall r. Sink b m r -> Sink a m r) -> SimpleSource m b

module Data.SouSiT.Trans

-- | Transforms each input individually by applying the function.
map :: (a -> b) -> Transform a b

-- | Transforms each input individually by applying the monadic function.
--   Warning: This is not really a Transform, since it isn't pure.
mapM :: Monad m => (b -> m a) -> Sink a m r -> Sink b m r

-- | Transforms each input and carry a state between the inputs.
mapWithState :: (s -> a -> (b, s)) -> s -> Transform a b

-- | Transforms each input to a tuple (input, index of input). I.e. for
--   <a>Mario</a>: (M, 0), (a, 1), (r, 2), (i, 3), (o, 4)
zipWithIndex :: Transform a (a, Int)

-- | Takes only the first n inputs, then returns done.
take :: (Num n, Ord n) => n -> Transform a a

-- | Takes inputs until the input fullfils the predicate. The matching
--   input is not passed on.
takeUntil :: (a -> Bool) -> Transform a a

-- | Takes inputs until the input matches the argument. The matching input
--   is not passed on.
takeUntilEq :: Eq a => a -> Transform a a

-- | Take inputs while the input fullfils the predicate. As soon as the
--   first non-matching input is encountered no more inputs will be passed
--   on.
takeWhile :: (a -> Bool) -> Transform a a

-- | Drops the first n inputs then passes through all inputs unchanged
drop :: (Num n, Ord n) => n -> Transform a a

-- | Drops inputs until the predicate is matched. The matching input and
--   all subsequent inputs are passed on unchanged.
dropUntil :: (a -> Bool) -> Transform a a

-- | Drops inputs as long as they match the predicate. The first
--   non-matching input and all following inputs are passed on unchanged.
dropWhile :: (a -> Bool) -> Transform a a

-- | Only retains elements that match the filter function
filter :: (a -> Bool) -> Transform a a

-- | Map that allows to filter out elements.
filterMap :: (a -> Maybe b) -> Transform a b

-- | Applies a function to each element and passes on every element of the
--   result list seperatly.
flatMap :: (a -> [b]) -> Transform a b

-- | Accumulates all elements with the accumulator function.
accumulate :: b -> (b -> a -> b) -> Transform a b

-- | Accumulates up to n elements with the accumulator function and then
--   releases it.
buffer :: Int -> b -> (b -> a -> b) -> Transform a b

-- | Counts the received elements.
count :: Num n => Transform a n

-- | Yield all elements of the array as seperate outputs.
disperse :: Transform [a] a

-- | Executes with t1 and when t1 ends, then the next input is fed to
--   through t2.
andThen :: Transform a b -> Transform a b -> Transform a b

-- | Loops the given transform forever.
loop :: Transform a b -> Transform a b

-- | Loops the given transform n times
loopN :: Int -> Transform a b -> Transform a b

-- | Executes the given transforms in a sequence, as soon as one ends the
--   next input is passed to the next transform.
sequence :: [Transform a b] -> Transform a b

-- | Only lets the <tt>rights</tt> of Either pass.
eitherRight :: Transform (Either a b) b

-- | Only lets the <tt>lefts</tt> of Either pass.
eitherLeft :: Transform (Either a b) a

-- | Serialize the elements into ByteString using cereal. For every input
--   there is exactly one output.
serialize :: Serialize a => Transform a ByteString

-- | Deserializes ByteString elements. The ByteStrings may be chunked, but
--   the beginnings of values must be aligned to the chunks. If this is not
--   the case then consider splitting the ByteStrings by the appropriate
--   start delimiter (if available) or split them up into singletons.
deserialize :: Serialize b => Transform ByteString b
mapSinkStatus :: Monad m => (SinkStatus a m r -> SinkStatus b m r) -> Sink a m r -> Sink b m r
type TransFun a b m r = (a -> Sink a m r) -> m r -> b -> Sink b m r
applyTransFun :: Monad m => TransFun a b m r -> SinkStatus a m r -> SinkStatus b m r
mapSinkTransFun :: Monad m => TransFun a b m r -> Sink a m r -> Sink b m r
applyMapping :: Monad m => (Sink a m r -> Sink b m r) -> (b -> a) -> SinkStatus a m r -> SinkStatus b m r
mapSinkMapping :: Monad m => (Sink a m r -> Sink b m r) -> (b -> a) -> Sink a m r -> Sink b m r
toDoneTrans :: Monad m => Sink a m r -> Sink a m r

-- | Outputs every element received and the result to the System-out (using
--   putStrLn). Format: <a>label</a>: <a>element</a> <a>label</a> is
--   <a>result</a>
debug :: (Show a, Show r, MonadIO m) => String -> Sink a m r -> Sink a m r

module Data.SouSiT.List

-- | A source containing the elements of the list
listSource :: Monad m => [a] -> FeedSource m a

-- | A sink that collects all input into a list. Does never say SinkDone.
listSink :: Monad m => Sink a m [a]

module Data.SouSiT.Handle

-- | Source from a handle. The handle will not be closed and is read till
--   hIsEOF.
hSource :: MonadIO m => (Handle -> m a) -> Handle -> FeedSource m a

-- | Same as hSource, but opens the handle when transfer is called and
--   closes it when transfer/feedToSink completes. Uses <tt>bracket</tt> to
--   ensure safe release of the allocated resources.
hSource' :: (Handle -> IO a) -> IO Handle -> FeedSource IO a

-- | Same as hSource, but opens the handle when transfer is called and
--   closes it when transfer/feedToSink completes.
hSourceRes :: (MonadIO m, MonadResource m) => (Handle -> m a) -> IO Handle -> FeedSource m a

-- | Same as hSource, but does not check for hIsEOF and therefore never
--   terminates.
hSourceNoEOF :: MonadIO m => (Handle -> m a) -> Handle -> FeedSource m a

-- | Same as hSource', but does not check for hIsEOF and therefore never
--   terminates.
hSourceNoEOF' :: (Handle -> IO a) -> IO Handle -> FeedSource IO a

-- | Same as hSourceRes', but does not check for hIsEOF and therefore never
--   terminates.
hSourceResNoEOF :: (MonadIO m, MonadResource m) => (Handle -> m a) -> IO Handle -> FeedSource m a

-- | Sink backed by a handle. The data will be written by the provided
--   function. The sink will never change to the SinkDone state (if the
--   device is full then the operation will simply fail). The handle is not
--   closed and exceptions are not catched.
hSink :: MonadIO m => (Handle -> a -> m ()) -> Handle -> Sink a m ()

-- | Same as hSink, but does opens the handle when the first item is
--   written. The handle will be closed when the sink is closed.
hSinkRes :: (MonadIO m, MonadResource m) => (Handle -> a -> m ()) -> IO Handle -> Sink a m ()

module Data.SouSiT.STM

-- | A sink that executes (atomically) a STM action for every input
--   received. The sink continues as long as the action returns Nothing.
--   When the action returns Just, then that value is the result of the
--   sink.
stmSink :: MonadIO m => (a -> STM (Maybe r)) -> Sink a m (Maybe r)

-- | A sink that executes (atomically) a STM action for every input
--   received. The sink never terminates.
stmSink' :: MonadIO m => (a -> STM ()) -> Sink a m ()

-- | Sink that writes all items into a TChan.
tchanSink :: MonadIO m => TChan a -> Sink a m ()

-- | Source that executes a STM action to get a new item. When the action
--   returns <a>Nothing</a> then the source is depleted.
stmSource :: MonadIO m => STM (Maybe a) -> FeedSource m a

-- | Source that executes a STM action to get a new item. Does never run
--   out of items.
stmSource' :: MonadIO m => STM a -> FeedSource m a

-- | Source that reads from a TChan. Does never run out of items (just
--   waits for new ones written to the TChan).
tchanSource :: MonadIO m => TChan a -> FeedSource m a

module Data.SouSiT
data Sink i m r
type Fetch i a = Sink i Identity a

-- | Reads the next element. The sink returns a fail if it is closed before
--   the input is received.
input :: Monad m => Sink a m a

-- | Reads the next element. If the sink is closed while waiting for the
--   input, then the parameter is returned as the sinks result.
inputOr :: Monad m => m a -> Sink a m a

-- | Skips n input elements. If the sink is closed before then the result
--   will also be ().
skip :: (Eq n, Num n, Monad m) => n -> Sink a m ()

-- | Changes the monad of a sink based upon a conversion function that maps
--   the original monad to the new one.
liftSink :: (Monad m, Monad m') => (forall x. m x -> m' x) -> Sink i m r -> Sink i m' r

-- | Lift the (pure) fetch sink into any monad.
liftFetch :: Monad m => Fetch i a -> Sink i m a

-- | Something that produces data to be processed by a sink
class Source src
transfer :: (Source src, Monad m) => src m a -> Sink a m r -> m r

-- | A basic instance of FeedSource (and Source)
data FeedSource m a

-- | A basic instance of Source
data SimpleSource m a
SimpleSource :: (forall r. Sink a m r -> m r) -> SimpleSource m a
feedToSink :: FeedSource m a -> forall r. Sink a m r -> m (Sink a m r)

-- | Transfer the data from the source into the sink
($$) :: (Source src, Monad m) => src m a -> Sink a m r -> m r

-- | Concatenates two sources.
(=+=) :: Monad m => FeedSource m a -> FeedSource m a -> FeedSource m a

-- | Concatenates two sources.
(=+|=) :: (Source src2, Monad m) => FeedSource m a -> src2 m a -> SimpleSource m a
type Transform a b = forall m r. Monad m => Sink b m r -> Sink a m r

-- | Merges two transforms into one.
(=$=) :: Monad m => (Sink b m r -> Sink a m r) -> (Sink c m r -> Sink b m r) -> Sink c m r -> Sink a m r

-- | Apply a transform to a sink.
(=$) :: Monad m => (Sink b m r -> Sink a m r) -> Sink b m r -> Sink a m r

-- | Apply a transform to a source.
($=) :: (Source src, Monad m) => src m a -> (forall r. Sink b m r -> Sink a m r) -> SimpleSource m b

module Data.SouSiT.File

-- | Creates a Source2 for the file read as characters.
fileSourceChar :: (MonadIO m, MonadResource m) => FilePath -> FeedSource m Char

-- | Creates a Source2 for the file read linewise as string
fileSourceLine :: (MonadIO m, MonadResource m) => FilePath -> FeedSource m String

-- | Creates a Source2 for file read as ByteStrings (hGetSome).
fileSourceByteString :: (MonadIO m, MonadResource m) => Int -> FilePath -> FeedSource m ByteString

-- | Creates a Source2 for file read as single bytes (buffered).
fileSourceWord8 :: (MonadIO m, MonadResource m) => FilePath -> SimpleSource m Word8

-- | Creates a sink that writes the Chars into the specified file.
fileSinkChar :: (MonadIO m, MonadResource m) => FilePath -> Sink Char m ()

-- | Creates a sink that writes the input into the file (without adding
--   newlines).
fileSinkString :: (MonadIO m, MonadResource m) => FilePath -> Sink String m ()

-- | Creates a sink that writes each input as a line into the file.
fileSinkLine :: (MonadIO m, MonadResource m) => FilePath -> Sink String m ()

-- | Creates a sink that writes the ByteStrings into the file.
fileSinkByteString :: (MonadIO m, MonadResource m) => FilePath -> Sink ByteString m ()

-- | Creates a sink for writing bytes into a file. The first parameter is
--   the size of the buffer.
fileSinkWord8 :: (MonadIO m, MonadResource m) => Int -> FilePath -> Sink Word8 m ()

-- | Creates an unbuffered sink for writing bytes into a file.
fileSinkWord8Unbuffered :: (MonadIO m, MonadResource m) => FilePath -> Sink Word8 m ()