undo

package
v1.3.25 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2023 License: BSD-3-Clause Imports: 6 Imported by: 4

README

undo

The undo package provides a generic undo / redo functionality based on []string representations of any kind of state representation (typically JSON dump of the 'document' state). It stores the compact diffs from one state change to the next, with raw copies saved at infrequent intervals to tradeoff cost of computing diffs.

In addition state (which is optional on any given step), a description of the action and arbitrary string-encoded data can be saved with each record. Thus, for cases where the state doesn't change, you can just save some data about the action sufficient to undo / redo it.

A new record must be saved of the state just before an action takes place and the nature of the action taken.

Thus, undoing the action restores the state to that prior state.

Redoing the action means restoring the state after the action.

This means that the first Undo action must save the current state before doing the undo.

The Idx is always on the last state saved, which will then be the one that would be undone for an undo action.

Documentation

Overview

Package undo supports generic undo / redo functionality, using an efficient diff of string-valued state representation of a 'document' being edited which can be JSON or XML or actual text -- whatever.

A new record must be saved of the state just *before* an action takes place and the nature of the action taken.

Thus, undoing the action restores the state to that prior state.

Redoing the action means restoring the state *after* the action.

This means that the first Undo action must save the current state before doing the undo.

The Idx is always on the last state saved, which will then be the one that would be undone for an undo action.

Index

Constants

This section is empty.

Variables

View Source
var DefaultRawInterval = 50

DefaultRawInterval is interval for saving raw state -- need to do this at some interval to prevent having it take too long to compute patches from all the diffs.

Functions

This section is empty.

Types

type Mgr

type Mgr struct {
	Idx         int        `desc:"current index in the undo records -- this is the record that will be undone if user hits undo"`
	Recs        []*Rec     `desc:"the list of saved state / action records"`
	RawInterval int        `` /* 145-byte string literal not displayed */
	Mu          sync.Mutex `desc:"mutex that protects updates -- we do diff computation as a separate goroutine so it is instant from perspective of UI"`
}

Mgr is the undo manager, managing the undo / redo process

func (*Mgr) HasRedoAvail

func (um *Mgr) HasRedoAvail() bool

HasRedoAvail returns true if there is at least one redo record available. This does NOT get the lock -- may rarely be inaccurate but is used for gui enabling so not such a big deal.

func (*Mgr) HasUndoAvail

func (um *Mgr) HasUndoAvail() bool

HasUndoAvail returns true if there is at least one undo record available. This does NOT get the lock -- may rarely be inaccurate but is used for gui enabling so not such a big deal.

func (*Mgr) MemStats added in v1.2.3

func (um *Mgr) MemStats(details bool) string

MemStats reports the memory usage statistics. if details is true, each record is reported.

func (*Mgr) MustSaveUndoStart

func (um *Mgr) MustSaveUndoStart() bool

MustSaveUndoStart returns true if the current state must be saved as the start of the first Undo action when at the end of the stack. If this returns true, then call SaveUndoStart. It sets a special flag on the record.

func (*Mgr) RecState

func (um *Mgr) RecState(idx int) []string

RecState returns the state for given index, reconstructing from diffs as needed. Must be called under lock.

func (*Mgr) Redo

func (um *Mgr) Redo() (action, data string, state []string)

Redo returns the action, data at the *next* index, and the state at the index *after that*. returning nil if already at end of saved records.

func (*Mgr) RedoList

func (um *Mgr) RedoList() []string

RedoList returns the list actions in order from the current forward to end suitable for a menu of actions to redo

func (*Mgr) RedoTo

func (um *Mgr) RedoTo(idx int) (action, data string, state []string)

RedoTo returns the action, action data, and state at the given index, returning nil if already at end of saved records.

func (*Mgr) Reset

func (um *Mgr) Reset()

Reset resets the undo state

func (*Mgr) Save

func (um *Mgr) Save(action, data string, state []string)

Save saves a new action as next action to be undone, with given action data and current full state of the system (either of which are optional). The state must be available for saving -- we do not copy in case we save the full raw copy.

func (*Mgr) SaveReplace added in v1.2.3

func (um *Mgr) SaveReplace(action, data string, state []string)

SaveReplace replaces the current Undo record with new state, instead of creating a new record. This is useful for when you have a stream of the same type of manipulations and just want to save the last (it is better to handle that case up front as saving the state can be relatively expensive, but in some cases it is not possible).

func (*Mgr) SaveState

func (um *Mgr) SaveState(nr *Rec, idx int, state []string)

SaveState saves given record of state at given index

func (*Mgr) SaveUndoStart

func (um *Mgr) SaveUndoStart(state []string)

SaveUndoStart saves the current state -- call if MustSaveUndoStart is true. Sets a special flag for this record, and action, data are empty. Does NOT increment the index, so next undo is still as expected.

func (*Mgr) Undo

func (um *Mgr) Undo() (action, data string, state []string)

Undo returns the action, action data, and state at the current index and decrements the index to the previous record. This state is the state just prior to the action. If already at the start (Idx = -1) then returns empty everything Before calling, first check MustSaveUndoStart() -- if false, then you need to call SaveUndoStart() so that the state just before Undoing can be redone!

func (*Mgr) UndoList

func (um *Mgr) UndoList() []string

UndoList returns the list actions in order from the most recent back in time suitable for a menu of actions to undo.

func (*Mgr) UndoTo

func (um *Mgr) UndoTo(idx int) (action, data string, state []string)

UndoTo returns the action, action data, and state at the given index and decrements the index to the previous record. If idx is out of range then returns empty everything

type Rec

type Rec struct {
	Action   string        `desc:"description of this action, for user to see"`
	Data     string        `` /* 166-byte string literal not displayed */
	Raw      []string      `desc:"if present, then direct save of full state -- do this at intervals to speed up computing prior states"`
	Patch    textbuf.Patch `desc:"patch to get from previous record to this one"`
	UndoSave bool          `desc:"this record is an UndoSave, when Undo first called from end of stack"`
}

Rec is one undo record, associated with one action that changed state from one to next. The state saved in this record is the state *before* the action took place. The state is either saved as a Raw value or as a diff Patch to the previous state.

func (*Rec) Init added in v1.2.3

func (rc *Rec) Init(action, data string)

Init sets the action and data in a record -- overwriting any prior values

func (*Rec) MemUsed added in v1.2.3

func (rc *Rec) MemUsed() int

MemUsed reports the amount of memory used for record

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL