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


-- | Predict the future, backtrack on failure
--   
--   This is a library for predictive scans. Its aim is to improve user
--   experience in cases when user interactions have to be acknowledged by
--   a remote host. It closes the gap between requesting the interaction
--   and the remote end acknowledging it by predicting what the remote end
--   will decide based on local information. If the prediction is wrong, it
--   automatically backtracks to the last state known to be consistent.
--   
--   Simple example: Your application displays a client-side text box, but
--   each edit made to it has to be acknowledged by a server. However, most
--   of the time the server will acknowledge, so your application can use
--   this library to proceed under this assumption and only backtrack, if
--   the server disagrees.
@package predictive
@version 0.1.0


module Data.Predictive

-- | A predictor tracks information on the current state of type <tt>s</tt>
--   and deltas of type <tt>d</tt>. It records a sequence of pending local
--   deltas and the last state known to be consistent on both sides. As
--   remote deltas arrive they are reconciled with the pending local
--   deltas.
data Predictor d s

-- | Warning: If you use the constructor directly, keep in mind that for
--   efficiency reasons this library operates under the assumption that the
--   second tuple components of the <a>_predPending</a> field are the
--   predicted states as produced by the corresponding delta.
Predictor :: (d -> d -> Bool) -> (d -> s -> s) -> s -> Seq (d, s) -> Predictor d s

-- | Do the deltas agree?
[_predAgree] :: Predictor d s -> d -> d -> Bool

-- | Effect of a delta on the state.
[_predApply] :: Predictor d s -> d -> s -> s

-- | Last consistent state.
[_predLast] :: Predictor d s -> s

-- | Pending local deltas and their resulting states.
[_predPending] :: Predictor d s -> Seq (d, s)

-- | Construct a predictor from the given functions and initial state.
predictor :: (d -> d -> Bool) -> (d -> s -> s) -> s -> Predictor d s

-- | A simplified variant of <a>predictor</a> for cases when deltas agree
--   when they are equal.
predictor_ :: (Eq d) => (d -> s -> s) -> s -> Predictor d s

-- | Is the given predictor currently consistent? Equivalently: Have all
--   local deltas so far been acknowledged by agreeing remote deltas?
consistent :: Predictor d s -> Bool

-- | The current predicted state. If the predictor is <a>consistent</a>,
--   this will agree with <a>lastConsistent</a>.
current :: Predictor d s -> s

-- | The last consistent state. If the predictor is <a>consistent</a>, this
--   will agree with <a>current</a>.
lastConsistent :: Predictor d s -> s

-- | Sequence of pending deltas ordered chronologically with the oldest one
--   left together with the effect that delta is predicted to have on the
--   state. If the predictor is consistent, this function returns the empty
--   sequence.
pending :: Predictor d s -> Seq (d, s)

-- | Apply the given local delta. This adds it to the sequence of pending
--   deltas.
applyLocal :: d -> Predictor d s -> Predictor d s

-- | Apply the given remote delta.
--   
--   If the given delta agrees with the oldest pending local delta, this
--   function removes the latter from the pending sequence and marks the
--   new state as the last consistent state. If it disagrees, all pending
--   local deltas are removed and the state is reset to the last consistent
--   state before applying the given delta.
applyRemote :: d -> Predictor d s -> Predictor d s