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


-- | Effectful, iteratee-inspired stream processing based on a
free monad.
--   
@package tubes
@version 0.2.1.0

module Tubes.Core

-- | A <a>Tube</a> is a computation which can
--   
--   <ul>
--   <li><a>yield</a> an intermediate value downstream and suspend
--   execution; and</li>
--   <li><a>await</a> a value from upstream, deferring execution until it
--   is received.</li>
--   </ul>
--   
--   Moreover, individual <a>Tube</a>s may be freely composed into larger
--   ones, so long as their types match. Thus, one may write small,
--   reusable building blocks and construct efficient stream process
--   pipelines.
--   
--   Since a much better engineered, more popular, and decidedly more
--   mature library already uses the term "pipes" I have opted instead to
--   think of my work as a series of tubes.
type Tube a b = FreeT (TubeF a b)

-- | <a>TubeF</a> is the union of unary functions and binary products into
--   a single type, here defined with a Boehm-Berarducci encoding.
--   
--   This type is equivalent to the following:
--   
--   <pre>
--   data TubeF a b k
--       = Await (a -&gt; k) -- :: (a -&gt; k) -&gt; TubeF a b k
--       | Yield (b  , k) -- :: (b  , k) -&gt; TubeF a b k
--   
--   </pre>
--   
--   The type signatures for the two value constructors should bear a
--   strong resemblance to the actual type signature of <a>runT</a>.
--   Instead of encoding tubes as structures which build up when composed,
--   a <a>TubeF</a> is a control flow mechanism which picks one of two
--   provided continuations.
--   
--   People using this library should never have to contend with these
--   details but it is worth mentioning.
newtype TubeF a b k
TubeF :: (forall r. ((a -> k) -> r) -> ((b, k) -> r) -> r) -> TubeF a b k
runT :: TubeF a b k -> forall r. ((a -> k) -> r) -> ((b, k) -> r) -> r

-- | A computation which only <a>yield</a>s and never <a>await</a>s
type Source b m r = forall x. Tube x b m r

-- | A computation which only <a>await</a>s and never <a>yield</a>s.
type Sink a m r = forall x. Tube a x m r

-- | A computation which neither <a>yield</a>s nor <a>await</a>s
type Action m r = forall x. Tube x x m r

-- | <a>run</a> is shorter than <a>runFreeT</a> and who knows, maybe it'll
--   change some day
run :: FreeT f m a -> m (FreeF f a (FreeT f m a))

-- | Command to wait for a new value upstream
await :: Monad m => Tube a b m a

-- | Command to send a value downstream
yield :: Monad m => b -> Tube a b m ()

-- | Convert a list to a <a>Source</a>
each :: (Monad m, Foldable t) => t b -> Tube a b m ()

-- | Enumerate <a>yield</a>ed values into a continuation, creating a new
--   <a>Source</a>
for :: Monad m => Tube a b m r -> (b -> Tube a c m s) -> Tube a c m r

-- | Compose two tubes into a new tube.
(><) :: Monad m => Tube a b m r -> Tube b c m r -> Tube a c m r

-- | Connect a task to a continuation yielding another task; see
--   <a>&gt;&lt;</a>
(>-) :: Monad m => Tube a b m r -> (b -> Tube b c m r) -> Tube a c m r

-- | Infix version of <a>for</a>
(~>) :: Monad m => Tube a b m r -> (b -> Tube a c m s) -> Tube a c m r

-- | Constructor for source computations
yieldF :: b -> k -> TubeF a b k

-- | Constructor for sink computations
awaitF :: (a -> k) -> TubeF a b k

-- | This performs a neat trick: a <a>Tube</a> with a return type
--   <tt>a</tt> will be turned into a new <a>Tube</a> containing the
--   underlying <a>TubeF</a> value.
--   
--   In this way the <a>&gt;&lt;</a> and <a>&gt;-</a> functions can replace
--   the <tt>()</tt> return value with a continuation and recursively
--   traverse the computation until a final result is reached.
liftT :: (MonadTrans t, Monad m) => FreeT f m a -> t m (FreeF f a (FreeT f m a))
instance Functor (TubeF a b)

module Tubes.Util

-- | Continuously relays any values it receives. Iteratee identity.
cat :: Monad m => Tube a a m r

-- | Transforms all incoming values according to some function.
map :: Monad m => (a -> b) -> Tube a b m r

-- | Refuses to yield the first <tt>n</tt> values it receives.
drop :: Monad m => Int -> Tube a a m r

-- | Relay only the first <tt>n</tt> elements of a stream.
take :: Monad m => Int -> Tube a a m ()

-- | Terminates the stream upon receiving a value violating the predicate
takeWhile :: Monad m => (a -> Bool) -> Tube a a m ()

-- | Yields only values satisfying some predicate.
filter :: Monad m => (a -> Bool) -> Tube a a m r

-- | Strict left-fold of a stream. Note that the actual return type of the
--   source is not relevant, only the intermediate yield type.
reduce :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Source a m () -> m b

-- | Similar to <a>each</a> except it explicitly marks the stream as
--   exhausted
every :: (Foldable t, Monad m) => t b -> Tube a (Maybe b) m ()

-- | Source of <a>String</a>s from stdin. This is mostly for debugging /
--   ghci example purposes.
prompt :: Source String IO ()

-- | Sink for <a>String</a>s to stdout. This is mostly for debugging / ghci
--   example purposes.
display :: Sink String IO ()

-- | Taps the next value from a source, maybe.
unyield :: Monad m => FreeT (TubeF x b) m () -> m (Maybe (b, FreeT (TubeF x b) m ()))

module Tubes.Pump

-- | A <a>Pump</a> is the dual to a <a>Tube</a>: where a <a>Tube</a> is a
--   computation manipulating a stream of values, a <a>Pump</a> can be
--   situated on either end of a tube to both insert values when requested
--   and handle any yielded results.
--   
--   This module is subject to change before I upload `0.2.0.0` to Hackage.
type Pump a b = CofreeT (PumpF a b)
data PumpF a b k
PumpF :: (a, k) -> (b -> k) -> PumpF a b k
recvF :: PumpF a b k -> (a, k)
sendF :: PumpF a b k -> (b -> k)

-- | Creates a <a>Pump</a> for a <a>Tube</a> using a comonadic seed value,
--   a function to give it more data upon request, and a function to handle
--   any yielded results. . Values received from the <a>Tube</a> may be
--   altered and sent back into the tube, hence this mechanism does act
--   like something of a pump.
pump :: Comonad w => w a -> (w a -> (b, w a)) -> (w a -> c -> w a) -> Pump b c w a

-- | Pull a value from a <a>Pump</a>, along with the rest of the
--   <a>Pump</a>.
recv :: Comonad w => Pump a b w r -> (a, Pump a b w r)

-- | Send a value into a <a>Pump</a>, effectively re-seeding the stream.
send :: Comonad w => Pump a b w r -> b -> Pump a b w r

-- | Given a suitably matching <a>Tube</a> and <a>Pump</a>, you can use the
--   latter to execute the former.
runPump :: (Comonad w, Monad m) => (x -> y -> r) -> Pump a b w x -> Tube a b m y -> m r
instance Functor (PumpF a b)
instance Pairing (PumpF a b) (TubeF a b)
instance Pairing ((,) a) ((->) a)
instance Pairing ((->) a) ((,) a)
instance Pairing Identity Identity


-- | Write effect-ful stream processing functions and compose them into a
--   series of tubes.
--   
--   This exists primarily for my own education. It is updated often as I
--   try things and is probably, at this moment, wrong.
--   
--   If you want to know more about efficient stream processing:
--   
--   <a>http://okmij.org/ftp/Streams.html</a>
--   
--   My goals were to
--   
--   <ul>
--   <li>learn more about iteratees and</li>
--   <li>explore the relationships between functions, pairs, sum types, and
--   products.</li>
--   </ul>
module Tubes

-- | A <a>Tube</a> is a computation which can
--   
--   <ul>
--   <li><a>yield</a> an intermediate value downstream and suspend
--   execution; and</li>
--   <li><a>await</a> a value from upstream, deferring execution until it
--   is received.</li>
--   </ul>
--   
--   Moreover, individual <a>Tube</a>s may be freely composed into larger
--   ones, so long as their types match. Thus, one may write small,
--   reusable building blocks and construct efficient stream process
--   pipelines.
--   
--   Since a much better engineered, more popular, and decidedly more
--   mature library already uses the term "pipes" I have opted instead to
--   think of my work as a series of tubes.
type Tube a b = FreeT (TubeF a b)

-- | <a>TubeF</a> is the union of unary functions and binary products into
--   a single type, here defined with a Boehm-Berarducci encoding.
--   
--   This type is equivalent to the following:
--   
--   <pre>
--   data TubeF a b k
--       = Await (a -&gt; k) -- :: (a -&gt; k) -&gt; TubeF a b k
--       | Yield (b  , k) -- :: (b  , k) -&gt; TubeF a b k
--   
--   </pre>
--   
--   The type signatures for the two value constructors should bear a
--   strong resemblance to the actual type signature of <a>runT</a>.
--   Instead of encoding tubes as structures which build up when composed,
--   a <a>TubeF</a> is a control flow mechanism which picks one of two
--   provided continuations.
--   
--   People using this library should never have to contend with these
--   details but it is worth mentioning.
newtype TubeF a b k
TubeF :: (forall r. ((a -> k) -> r) -> ((b, k) -> r) -> r) -> TubeF a b k
runT :: TubeF a b k -> forall r. ((a -> k) -> r) -> ((b, k) -> r) -> r

-- | A computation which only <a>yield</a>s and never <a>await</a>s
type Source b m r = forall x. Tube x b m r

-- | A computation which only <a>await</a>s and never <a>yield</a>s.
type Sink a m r = forall x. Tube a x m r

-- | A computation which neither <a>yield</a>s nor <a>await</a>s
type Action m r = forall x. Tube x x m r

-- | <a>run</a> is shorter than <a>runFreeT</a> and who knows, maybe it'll
--   change some day
run :: FreeT f m a -> m (FreeF f a (FreeT f m a))

-- | Command to wait for a new value upstream
await :: Monad m => Tube a b m a

-- | Command to send a value downstream
yield :: Monad m => b -> Tube a b m ()

-- | Convert a list to a <a>Source</a>
each :: (Monad m, Foldable t) => t b -> Tube a b m ()

-- | Enumerate <a>yield</a>ed values into a continuation, creating a new
--   <a>Source</a>
for :: Monad m => Tube a b m r -> (b -> Tube a c m s) -> Tube a c m r

-- | Infix version of <a>for</a>
(~>) :: Monad m => Tube a b m r -> (b -> Tube a c m s) -> Tube a c m r

-- | Connect a task to a continuation yielding another task; see
--   <a>&gt;&lt;</a>
(>-) :: Monad m => Tube a b m r -> (b -> Tube b c m r) -> Tube a c m r

-- | Compose two tubes into a new tube.
(><) :: Monad m => Tube a b m r -> Tube b c m r -> Tube a c m r

-- | This performs a neat trick: a <a>Tube</a> with a return type
--   <tt>a</tt> will be turned into a new <a>Tube</a> containing the
--   underlying <a>TubeF</a> value.
--   
--   In this way the <a>&gt;&lt;</a> and <a>&gt;-</a> functions can replace
--   the <tt>()</tt> return value with a continuation and recursively
--   traverse the computation until a final result is reached.
liftT :: (MonadTrans t, Monad m) => FreeT f m a -> t m (FreeF f a (FreeT f m a))

-- | Continuously relays any values it receives. Iteratee identity.
cat :: Monad m => Tube a a m r

-- | Transforms all incoming values according to some function.
map :: Monad m => (a -> b) -> Tube a b m r

-- | Refuses to yield the first <tt>n</tt> values it receives.
drop :: Monad m => Int -> Tube a a m r

-- | Relay only the first <tt>n</tt> elements of a stream.
take :: Monad m => Int -> Tube a a m ()

-- | Terminates the stream upon receiving a value violating the predicate
takeWhile :: Monad m => (a -> Bool) -> Tube a a m ()

-- | Yields only values satisfying some predicate.
filter :: Monad m => (a -> Bool) -> Tube a a m r

-- | Strict left-fold of a stream. Note that the actual return type of the
--   source is not relevant, only the intermediate yield type.
reduce :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Source a m () -> m b

-- | Similar to <a>each</a> except it explicitly marks the stream as
--   exhausted
every :: (Foldable t, Monad m) => t b -> Tube a (Maybe b) m ()

-- | Taps the next value from a source, maybe.
unyield :: Monad m => FreeT (TubeF x b) m () -> m (Maybe (b, FreeT (TubeF x b) m ()))

-- | Source of <a>String</a>s from stdin. This is mostly for debugging /
--   ghci example purposes.
prompt :: Source String IO ()

-- | Sink for <a>String</a>s to stdout. This is mostly for debugging / ghci
--   example purposes.
display :: Sink String IO ()

-- | A <a>Pump</a> is the dual to a <a>Tube</a>: where a <a>Tube</a> is a
--   computation manipulating a stream of values, a <a>Pump</a> can be
--   situated on either end of a tube to both insert values when requested
--   and handle any yielded results.
--   
--   This module is subject to change before I upload `0.2.0.0` to Hackage.
type Pump a b = CofreeT (PumpF a b)
data PumpF a b k
PumpF :: (a, k) -> (b -> k) -> PumpF a b k
recvF :: PumpF a b k -> (a, k)
sendF :: PumpF a b k -> (b -> k)

-- | Creates a <a>Pump</a> for a <a>Tube</a> using a comonadic seed value,
--   a function to give it more data upon request, and a function to handle
--   any yielded results. . Values received from the <a>Tube</a> may be
--   altered and sent back into the tube, hence this mechanism does act
--   like something of a pump.
pump :: Comonad w => w a -> (w a -> (b, w a)) -> (w a -> c -> w a) -> Pump b c w a

-- | Send a value into a <a>Pump</a>, effectively re-seeding the stream.
send :: Comonad w => Pump a b w r -> b -> Pump a b w r

-- | Pull a value from a <a>Pump</a>, along with the rest of the
--   <a>Pump</a>.
recv :: Comonad w => Pump a b w r -> (a, Pump a b w r)

-- | Given a suitably matching <a>Tube</a> and <a>Pump</a>, you can use the
--   latter to execute the former.
runPump :: (Comonad w, Monad m) => (x -> y -> r) -> Pump a b w x -> Tube a b m y -> m r

-- | Lift a computation from the argument monad to the constructed monad.
lift :: MonadTrans t => forall (m :: * -> *) a. Monad m => m a -> t m a
runFreeT :: FreeT f m a -> m (FreeF f a (FreeT f m a))