Safe Haskell | Safe |
---|---|

Language | Haskell98 |

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.Trans.Tardis
- module Control.Monad.Tardis.Class

# Re-exports

module Control.Monad.Trans.Tardis

module Control.Monad.Tardis.Class

# What is a Tardis?

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''`

.

# How do you use a Tardis?

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)