Edit on GitHub

Trailer: backtrack easily and efficiently

The trailer is the object that keeps track of anything you want to keep track of. Some objects will take a trailer as a parameter in their constructor. When it does, it means that their state can be saved and restored on demand using the functions described below.

State manipulation

Those functions are used to change the current state, save and or restore it.

Note that during your "state exploration", you can only restore higher. It is not possible to restore some deeper state, or state that could be in the same level. For example, if you have a state A at some point, you call SeaPearl.saveState! to store it. You edit some SeaPearl.StateObject, making you at some state B. Then you call SeaPearl.restoreState! that will restore every SeaPearl.StateObject to the state A. At that point, there is no way to go back to the state B using the trailer.

SeaPearl.StateObject — Type
StateObject{T}(value::T, trailer::Trailer)

A reversible object of value value that has a type T, storing its modification into trailer.

source
SeaPearl.StateEntry — Type
StateEntry{T}(value::T, object::StateObject{T})

An entry that can be stacked in the trailer, containing the former value of the object, and a reference to theobject` so that it can be restored by the trailer.

source
SeaPearl.trail! — Function
trail!(var::StateObject{T})

Store the current value of var into its trailer.

source
SeaPearl.setValue! — Function
setValue!(var::StateObject{T}, value::T) where {T}

Change the value of var, replacing it with value, and if needed, store the former value into var's trailer.

source
SeaPearl.saveState! — Function
saveState!(trailer::Trailer)

Store the current state into the trailer, replacing the current stack with an empty one.

source
SeaPearl.restoreState! — Function
restoreState!(trailer::Trailer)

Iterate over the last state to restore every former value, used to backtrack every change made after the last call to saveState!.

source
SeaPearl.withNewState! — Function
withNewState!(func, trailer::Trailer)

Call the func function with a new state, restoring it after. Aimed to be used with the do block syntax.

Examples

using SeaPearl
trailer = SeaPearl.Trailer()
reversibleInt = SeaPearl.StateObject{Int}(3, trailer)
SeaPearl.withNewState!(trailer) do
    SeaPearl.setValue!(reversibleInt, 5)
end
reversibleInt.value # 3
source