Crate gur

Expand description

Wrapper types to provide undo-redo functionality.

Sample code

use gur::prelude::*;
use gur::cur::{Cur, CurBuilder};

// Appication state
#[derive(Clone)]
struct MyState {
    data: String
}

fn main() {
    // Initialize
    let mut state: Cur<MyState> = CurBuilder::new().build(MyState{ data: "My".to_string() });
    assert_eq!("My", state.data);

    // Change state
    state.edit(|mut state: MyState| { state.data += "State"; state });
    assert_eq!("MyState", state.data);

    // Undo
    state.undo();
    assert_eq!("My", state.data);

    // Redo
    state.redo();
    assert_eq!("MyState", state.data);
}

Where Cur<T> is a type providing undo-redo functionality. The MyState is a type of user’s application state. MyState implements the Clone trait required by Cur<T>. Then the variable state as type Cur<MyState> is created to get the ability to undo-redo.

The edit takes a closure to change the variable. The closure is a function that consumes a current state as internal type MyState and returns a new state. undo can restore the previous state. The redo is reverse operation of the undo.

The Cur<T> implements Deref. So the variable can be used as like smart pointers.

`Ur` family

Ur is a most basic type in this crate. Some variants are provided in this crate. The variants and their features are listed below.

Type	Requirements	Thread safety	Description
Ur<T>	`T`: Snapshot	No	A basic wrapper for types implementing Snapshot.
Cur<T>	`T`: Clone	No	Another simple wrapper for types implementing Clone.
Aur<T>	`T`: Snapshot	Yes	Ur<T> + Send + Sync
Acur<T>	`T`: Clone	Yes	Cur<T> + Send + Sync

Requirements

For example, Ur<T> requires T implementing Snapshot. On the other hand, Cur<T> requires Clone instead of Snapshot for simplicity.

Thread safety

Some types of them can be Send and Sync and some not. See interface for more details about thread safety.

Generative approach

This section describes a basic concept of this crate. The concept is that “Undoing is regenerating (recomputing) the old state.”

For explanation, a sample history of changes is shown as follows,

t: state
c: command
s: snapshot

old <----------------------> new
     c1        c2        c3
t0 -----> t1 -----> t2 -----> t3
|  +-------------->           |
|  |                          |
s0 +--------------------------+
           undo t3 -> t2

Where tx is an application state at time point x, cx is a command to change a state tx-1 to next tx, and sx is a snapshot of a state tx.

The application state have changed in order of t0, t1, t2, and t3. Now, the current state is t3.

Let us consider undoing the current state t3 to its previous state t2. First, the system restores an old state from its snapshot at any point in the history. In this case, We would have to restore the state t0 from s0 because there is only one snapshot s0. Then the system reruns the commands (c1 and c2) in order. Finally, the target state t2 will be obtained.

Data structure

A history is managed as chain of commands and snapshots to perform the process described above. No intermediate states are stored.

c: command
s: snapshot

old <----------------------------------------------> new
/--\  +--+  +--+       +--+  /----\  +----+  +----+
|s0|--|c1|--|c2|--...--|cn|--|sn+1|--|cn+2|--|cn+3|--...
\--/  +--+  +--+       +--+  \----/  +----+  +----+

The frequency of snapshots can be customized by “trigger functions.” See crate::triggers for more details.

Pros and Cons

Pros

The advantages of this approach are usability and robustness. There are no backward opeartions in the undoing process. So users almost never have to write additional codes for the process. If there are tests for the application state object, the correctness of undo-redo process is also guaranteed.