{-# OPTIONS_GHC -Wall #-}

-- | This module re-exports both 'MonadTardis' and 'TardisT'
-- (Wherever there is overlap, the 'MonadTardis' version is preferred.)
-- 
-- The recommended usage of a Tardis is to import this module.
module Control.Monad.Tardis
  ( -- * Re-exports
    module Control.Monad.Trans.Tardis
  , module Control.Monad.Tardis.Class

    -- * What is a Tardis?
    -- $whatis
    
    -- * How do you use a Tardis?
    -- $howuse
  ) where


import Control.Monad.Tardis.Class
import Control.Monad.Trans.Tardis
  ( TardisT
  , runTardisT
  , evalTardisT
  , execTardisT

  , Tardis
  , runTardis
  , evalTardis
  , execTardis
  
  , noState
  )


{- $whatis
    A Tardis is the combination of the State monad transformer
    and the Reverse State monad transformer.
    
    The State monad transformer features a forwards-traveling state.
    You can retrieve the current value of the state,
    and you can set its value, affecting any future attempts
    to retrieve it.

    The Reverse State monad transformer is just the opposite:
    it features a backwards-traveling state.
    You can retrieve the current value of the state,
    and you can set its value, affecting any /past/ attempts
    to retrieve it. This is a bit weirder than its
    forwards-traveling counterpart, so its Monad instance
    additionally requires that the underlying Monad it transforms
    must be an instance of MonadFix.

    A Tardis is nothing more than mashing these two things together.
    A Tardis gives you /two/ states: one which travels /backwards/
    (or /upwards/) through your code (referred to as @bw@),
    and one which travels /forwards/ (or /downwards/) through your code
    (referred to as @fw@). You can retrieve the current
    value of either state, and you can set the value of either state.
    Setting the forwards-traveling state will affect the /future/,
    while setting the backwards-traveling state will affect the /past/.
    Take a look at how Monadic bind is implemented for 'TardisT':

> m >>= f  = TardisT $ \ ~(bw, fw) -> do
>   rec (x,  ~(bw'', fw' )) <- runTardisT m (bw', fw)
>       (x', ~(bw' , fw'')) <- runTardisT (f x) (bw, fw')
>   return (x', (bw'', fw''))

    Like the Reverse State monad transformer, TardisT's Monad instance
    requires that the monad it transforms is an instance of MonadFix,
    as is evidenced by the use of @rec@.
    Notice how the forwards-traveling state travels /normally/:
    first it is fed to @m@, producing @fw'@, and then it is fed to @f x@,
    producing @fw''@. The backwards-traveling state travels in the opposite
    direction: first it is fed to @f x@, producing @bw'@, and then
    it is fed to @m@, producing @bw''@.

-}

{- $howuse
    A Tardis provides four primitive operations,
    corresponding to the /get/ and /put/ for each of its two states.
    The most concise way to explain it is this:
    'getPast' retrieves the value from the latest 'sendFuture',
    while 'getFuture' retrieves the value from the next 'sendPast'.
    Beware the pitfall of performing send and get in the wrong order.
    Let's consider forwards-traveling state:

> do sendFuture "foo"
>    x <- getPast

    In this code snippet, @x@ will be @\"foo\"@, because 'getPast'
    grabs the value from the latest 'sendFuture'. If you wanted
    to observe that state /before/ overwriting it with @\"foo\"@,
    then re-arrange the code so that 'getPast' happens earlier
    than 'sendFuture'. Now let's consider backwards-traveling state:

> do x <- getFuture
>    sendPast "bar"

    In this code snippet, @x@ will be @\"bar\"@, because 'getFuture'
    grabs the value from the next 'sendPast'. If you wanted
    to observe that state /before/ overwriting it with @\"bar\"@,
    then re-arrange the code so that 'getFuture' happens later
    than 'sendPast'.

    TardisT is an instance of MonadFix. This is especially important
    when attempting to write backwards-traveling code, because
    the name binding occurs later than its usage.
    The result of the following code will be @(11, \"Dan Burton\")@.

> flip execTardis (10, "Dan") $ do
>   name <- getPast
>   sendFuture (name ++ " Burton")
>   rec
>     sendPast (score + 1)
>     score <- getFuture
>   return ()

    To avoid using @rec@, you may find 'modifyBackwards' to be useful.
    This code is equivalent to the previous example:

> flip execTardis (10, "Dan") $ do
>   modifyForwards (++ " Burton")
>   modifyBackwards (+ 1)

-}