Struct add_ed::History

pub struct History<T>
where
    T: Default + Debug + Snapshot + PartialEq,
{
    pub dont_snapshot: bool,
    /* private fields */
}

A history abstraction over generic objects used by add-ed.

Handles snapshotting and moving over the history of snapshots. Currently uses a revert style of undo inspired by this reasoning.

Automatically manages snapshot creation upon mutable access to the current point in history. Further allows pausing snapshot creation via [History.dont_snapshot] as well as manual snapshot creation via [History.snapshot] (for use during script/macro execution, to make each snapshot correspond to a user action).

Fields

dont_snapshot: bool

If true all calls to History::snapshot are ignored (including the automatic call upon running .current_mut()).

Intended for macro execution, when it would be confusing to create multiple snapshots for what the user sees as a single action.

(If a point in history is viewed a snapshot reverting to that point in history will be created before mutable access no matter if this variable is set to true.)

Implementations

impl<T> History<T>

where T: Default + Debug + Snapshot + PartialEq,

pub fn new() -> Self

Create new History instance

• Only an empty present state exists.
• Considered saved at initial empty state.

pub fn saved(&self) -> bool

Get if the buffer is saved

It aims to be true when the viewed buffer matches the data last saved. If it is uncertain or difficult to track it will return false.

pub fn set_saved(&mut self)

Mark the currently viewed buffer state as saved

If dont_snapshot is set this instead behaves as set_unsaved(), as we cannot be sure a snapshot will exist corresponding to the state in which the buffer was saved.

pub fn set_unsaved(&mut self)

Declare that no known buffer state is saved

Mainly useful for testing, but may be relevant when knowing that file was changed on disk.

pub fn current(&self) -> &T

Get an immutable view into the currently viewed point in history

pub fn current_mut(&mut self, modification_cause: String) -> &mut T

Get a mutable state to make new changes

• Takes a string describing what is causing this new snapshot. (Should generally be the full command, if not be as clear as possible.)
• If currently viewing history, will create a revert snapshot at end of history.
• Unless self.dont_snapshot, will create a new snapshot tagged with the given cause for modification.
• Returns mutable access to the snapshot at the end of history.

pub fn snapshot(&mut self, modification_cause: String)

Manually add a snapshot

Takes a String as an argument that should describe what causes the change seen in the created snapshot relative to the preceding snapshot.

The only case this should be needed is before setting dont_snapshot for a script execution. If dont_snapshot isn’t set snapshots are created automatically whenever [Self.current_mut] is executed.

pub fn dedup_present(&mut self)

Checks if the last two snapshots in history are identical. If yes deletes one of them.

Intended for use by macros and scripts, as they have to add a snapshot even for non-mutating scripts since they don’t know if a script will modify the buffer. By running this after macro execution the snapshot will be deleted if extraneous and left if relevant.

pub fn snapshots(&self) -> &Vec<(String, T)>

Accessor to view the full list of snapshots

• Entries are in order of creation, the first operation is first in the list.
• The string beside the snapshot describes what caused the state in the snapshot (relative to the preceeding snapshot).

pub fn len(&self) -> usize

Shorthand for .snapshots().len()

pub fn saved_i(&self) -> Option<usize>

Getter for what index was last saved

Returns None if no index is believed to be saved.

Intended to be used to enrich when listing snapshots by marking the one considered saved.

pub fn viewed_i(&self) -> usize

Getter for currently viewed snapshot index

pub fn set_viewed_i(&mut self, new_i: usize) -> Result<&str>

Setter for currently viewed snapshot index

Returns the modification cause for the now viewed index.

Will return error if given index doesn’t hold a snapshot (aka. is too big).

Trait Implementations

impl<T> Clone for History<T>

where T: Default + Debug + Snapshot + PartialEq + Clone,

fn clone(&self) -> History<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for History<T>

where T: Default + Debug + Snapshot + PartialEq + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for History<T>

where T: Default + Debug + Snapshot + PartialEq,

fn default() -> Self

Returns the “default value” for a type.