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 ¶
- Variables
- type Mgr
- func (um *Mgr) HasRedoAvail() bool
- func (um *Mgr) HasUndoAvail() bool
- func (um *Mgr) MemStats(details bool) string
- func (um *Mgr) MustSaveUndoStart() bool
- func (um *Mgr) RecState(idx int) []string
- func (um *Mgr) Redo() (action, data string, state []string)
- func (um *Mgr) RedoList() []string
- func (um *Mgr) RedoTo(idx int) (action, data string, state []string)
- func (um *Mgr) Reset()
- func (um *Mgr) Save(action, data string, state []string)
- func (um *Mgr) SaveReplace(action, data string, state []string)
- func (um *Mgr) SaveState(nr *Rec, idx int, state []string)
- func (um *Mgr) SaveUndoStart(state []string)
- func (um *Mgr) Undo() (action, data string, state []string)
- func (um *Mgr) UndoList() []string
- func (um *Mgr) UndoTo(idx int) (action, data string, state []string)
- type Rec
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
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
MemStats reports the memory usage statistics. if details is true, each record is reported.
func (*Mgr) MustSaveUndoStart ¶
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 ¶
RecState returns the state for given index, reconstructing from diffs as needed. Must be called under lock.
func (*Mgr) Redo ¶
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 ¶
RedoList returns the list actions in order from the current forward to end suitable for a menu of actions to redo
func (*Mgr) RedoTo ¶
RedoTo returns the action, action data, and state at the given index, returning nil if already at end of saved records.
func (*Mgr) Save ¶
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
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) SaveUndoStart ¶
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 ¶
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!
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.
Source Files