vtf txb _buffercomponents localhistory

↑ vtf-txb-_buffercomponents

localhistory

class localhistory._LocalHistory ¶

Optional Buffer Component to support features around chronological progress of edits in the TextBuffer.

If active, all edits to the TextBuffer's data via its main methods are registered and held for an extension or direckt written to an SQL database, as well as the related markings or edits to markings via TextBuffer's or _Marker's main methods. In addition, the special cursor movements are registered via TextBuffer's methods with goto_ prefix and the movement by the backjumpmode of the _Marker. Internally, the chronological steps of the editing are processed with HistoryItem's.

When undo is executed later, opposite entries for redo are generated. For a more comprehensive nature of the ordinary undo and redo properties of a text editing program, this object provides two additional ways to specify or manage the undo/redo actions.

First, the use of a lock on undo actions can be specified at initialization. An execution of undo will then lock subsequent edits of the buffer via raising an AssertionError; only when the lock is released the buffer can be further edited. This property is intended to prevent the accidental deletion of redo entries after undo actions.

On the other hand, the creation of a branch_fork in sequence of an edit after undo/redo actions can be set. This allows jumping between two edit branches until the next creation of a branch. Like the lock, this feature provides the possibility to handle the accidental deletion of redo entries, only with an extended functionality:

o - o - o - | - u - u - u

History entries were registered (`o') and a few edits were undone (`u') (`|' marks the current position in the timeline).

              o - o - o - o - o - o - |
             /
o - o - o - o
             \
              o - u - u - u

After the undo, the buffer was edited next.

              o - u - u - u - u - u - u
             /
o - o - o - o
             \
              o - o - o - o - | - u - u

The editing branch was changed, then the buffer was edited further and then entries were undone again.

                                  o - o - |
                                 /
o - o - o - o - o - o - o - o - o
                                 \
                                  o - u - u

The buffer was edited some more.

The component can also set a "chronological progress clamp", which can then be used as a comparison to the current "chronological progress identification number" to detect a changed buffer.

WARNING: the connection of the SQL Database is NOT threadsave, but the cursor (_sql.SQLTSCursor).

_¶

__commit_quotient__: int

db_attached: bool

db_in_mem: bool

db_path: str | Literal[":memory:", ":swap:", "file:...<uri>"]

sql_connection: SQLConnection

sql_cursor: _sql.SQLTSCursor

@property

lock() -> bool ¶

Whether the lock is engaged.

@lock.setter

lock(__val) -> None ¶

Set the undo lock. Flush the redo memory when releasing the lock.

__init__(**kwargs) ¶

Create a new LocalHistory object.

Keyword parameter:

• __buffer__

  The TextBuffer object for which LocalHistory is created.

• db_path

  The location of the database can be specified as a filepath using an ordinal or "Uniform Resource Identifier" (URI) string; to create the database temporarily in RAM, the expression ":memory:" can be used; another special expression is ":swap:" to create the database in the same location of the database in _Swap.

• from_db

  To build the database and the object from an existing database, the origin can be passed as an ordinal path, a URI, or an existing SQL connection. The connection will be closed automatically afterwards, unless an SQL connection was passed.

• unlink_atexit

  Registers the deletion of the database when exiting the Python interpreter.

  The process is performed depending on the location of the database:

  • If the database was created as simple files, the connection is closed and the files are deleted from disk (including journals);
  • If an existing connection was passed (internal usage) or the database was created in RAM, the connection will be closed;
  • If the expression ":swap:" was used during creation, all LocalHistory entries in the database are deleted (unless the database was closed before).

• undo_lock

  Enables the undo lock feature. Blocks processing of the buffer immediately after an undo action until the lock is released.

• branch_forks

  Enables the chronological forks feature. Allows to switch between the last undo branch.

• maximal_items

  Sets an upper limit for chronological items. None corresponds to no limit. The final value is composed of maximum_items + items_chunk_size.

• items_chunk_size

  Defines the amount of chronological items that will be removed when the upper limit is reached. The final value of the upper limit is composed of maximum_items + items_chunk_size.

• maximal_items_action

  Executed before chronological items are removed when the upper limit is reached. Does not receive any parameters.

raises:	ConfigurationError: if ":swap:" is used and there is no connection to a database in __swap__. DatabaseFilesError: db_path already exists. DatabaseTableError: if the database tables already exist in the destination.

__new_db__(**kwargs) -> _LocalHistory ¶

Create a new _LocalHistory with the same parameters, except from_db is set to None by default. Parameters can be overwritten via kwargs.

raises:	ConfigurationError: if ":swap:" is used and there is no connection to a database in __swap__. DatabaseFilesError: db_path already exists. DatabaseTableError: if the database tables already exist in the destination.

auto_commit() -> None ¶

Commit the connection if the chronological number of the last entry can be divided restless by __commit_quotient__ (default = 10).

backup(dst) -> None ¶

Dump the currently held item, then clone all items and metadata into dst. Close the connection to the backup-db if dst is defined as path or URI.

raises:	ValueError: if ":swap:" or ":memory:" is used as dst. DatabaseFilesError: dst already exists. DatabaseTableError: if the database tables already exist in the destination.

branch_fork(__redo_hint=0) -> ChunkLoad | None ¶

Switch the branch fork. Execute redo n times or as many times as possible if the parameterization is "all". Set the clamp to -1,so that future execution of clamp_is_diff returns True until a new clamp is set or the branch is changed back.

[+] __swap__.adjust [+] __swap__.fill [+] __swap__.suit [+] __trimmer__.sizing [+] __trimmer__.trim [+] __highlighter__.prep_by_bypass [+] __marker__.adjust [+] __glob_cursor__.adjust

raises:	ConfigurationError: branch forks not configured. DatabaseCorruptedError: Programming Error | Corrupted Data

clamp_diff() -> int ¶

Returns the difference between the set id clamp and the chronological progress as an absolute integer.

clamp_in_past() -> bool ¶

Returns whether the set id clamp is less than the chronological progress.

clamp_is_diff() -> bool ¶

Returns whether the set id clamp is different from the chronological progress.

clamp_is_reachable() -> Literal[0, 1, 2] ¶

Returns whether the chronological id clamp is reachable.

returns:

• 0: not reachable (the clamp was lost during -- trimming after the maximum number of items was reached; branching after the branch was changed; flushing redo items after undo and branch forks are not supported).
• 1: reachable by undo/redo or the current id is equal to the clamp.
• 2: reachable by branch_fork [+ redo].

clamp_set(*, dump_current=True) -> None ¶

Sets the current chronological process id, for the comparison in clamp_is_diff. Dumps the current history item if present and dump_current is True (default).

clone(to_db, unlink_origin=False, **kwargs) -> _LocalHistory ¶

Clone the database and metadata into a new _LocalHistory object. The standard parameterization is the same as the original and can be overridden via keyword arguments. If unlink_origin is set to True, the existing database is deleted depending on its location:

db origin	unlink
Filepath	- > Connection.close ; os.unlink
:memory:	- > Connection.close
:swap:	- > dropall
SQL-Connection	- > Connection.close

• Returns the new _LocalHistory object.

raises:	ConfigurationError: if ":swap:" is used and there is no connection to a database in __swap__. DatabaseFilesError: db_path already exists. DatabaseTableError: if the database tables already exist in the destination.

dropall() -> None ¶

Delete all entries in the tables of the database and discard the indexes.

dump_current_item() -> bool ¶

Dump the currently held item if present and return whether an item was dumped.

dump_metas() -> None ¶

Dump the metadata into the database and do commit.

flush_redo() -> None ¶

Flush the redo memory [ and create a branch fork if configured ].

lock_release() -> None ¶

Set the undo lock. Flush the redo memory when releasing the lock.

redo() -> tuple[list[HistoryItem], ChunkLoad] | None ¶

Redo the last undone action in the buffer and create counterparts to the redo action for undo. Can be executed in sequence.

[+] __swap__.adjust [+] __swap__.fill [+] __swap__.suit [+] __trimmer__.sizing [+] __trimmer__.trim [+] __highlighter__.prep_by_undoredo [+] __marker__.adjust [+] __glob_cursor__.adjust

Returns: ( [<HistoryItem per action>, ...], <final ChunkLoad> ) or None when nothing has been processed.

suit(mode="unite", leave_active=False) -> _Suit[_LocalHistory] ¶

Dump a held history item if available. Then return a suit depending on mode.

(when entering, __local_history__ is returned)

>>> with __local_history__.suit(<mode>)[ as local_history]:
>>>     ...

Modes:

• "unite" :

  Unite the actions inside the suit into one chronological action.

• "_ignore" :

  Disable the following dump of history items, but not the creation of held items. WARNING: May disturb the stability of local history and the buffer when edits to the data is skipped.

If a suit is active and leave_active is True, __exit__ of the active suit is executed and a new one is created, otherwise a dummy is returned.

undo() -> tuple[list[HistoryItem], ChunkLoad] | None ¶

Undo the last edit in the buffer and create counterparts to the undo action for redo. Can be executed in sequence.

[+] __swap__.adjust [+] __swap__.fill [+] __swap__.suit [+] __trimmer__.sizing [+] __trimmer__.trim [+] __highlighter__.prep_by_undoredo [+] __marker__.adjust [+] __glob_cursor__.adjust

Returns: ( [<HistoryItem per action>, ...], <final ChunkLoad> ) or None when nothing has been processed.

unlink() -> None ¶

Execute the unlink function, depending on where the database is located, and remove the execution entry when exiting the Python interpreter. It can be assumed that the database will no longer exist and will be deleted (even if the database is on the disk as files).

db origin	unlink
Filepath	- > Connection.close ; os.unlink
:memory:	- > Connection.close
:swap:	- > dropall
SQL-Connection	- > Connection.close

---

Date:	20 Dec 2022
Version:	0.1
Author:	Adrian Hoefflin [srccircumflex]
Doc-Generator:	"pyiStructure-RSTGenerator" <prototype>