vtf txb _buffercomponents marker

↑ vtf-txb-_buffercomponents

marker

Objects

class marker._Marker(Iterable[_Marking | list[int, int]]) ¶

Optional Buffer Component for creating, editing and processing data markings in the buffer. This also extends the functionality of cursor_move in TextBuffer.

Markings are stored in the _Marker in a list of _Marking objects (markings), in runtime they can also change to ordinary lists: [ <start position>, <stop position> ]

When a new _Marking is created by cursor_move or a method in _Marker, it is attached to the list markings and can be edited on index -1 via cursor_move or methods in _Marker until _Marker is notified that a marker is finished. Depending on the parametrization of multy_mode, the marker is then sorted into the list or removed. If the marking is terminated by cursor_move, the backjump_mode can be used to trigger the movement of the cursor to the relative beginning of the marking. If the multy_mode is set to True, all markings are kept even after they have been ended and are adjusted to inputs in the buffer and handled (sticky mode).

Currently implemented functions with markings:

• Remove all or targeted marked data areas.
• Remove or replace tab ranges in all or targeted marked ranges.
• Shift or backshift all or targeted marked rows.
• Read all or targeted marked data.
• Cursor navigation to marked areas.

_¶

markings: list[_Marking | list[int, int]]

@property

multy_mode() -> bool ¶

Whether the multiple-sticky-marks-mode is enabled.

@multy_mode.setter

multy_mode(__set) -> None ¶

Enable or disable the multiple-sticky-marks-mode.

@property

backjump_mode() -> bool ¶

Whether the backjump-mode is enabled.

@backjump_mode.setter

backjump_mode(__set) -> None ¶

Enable or disable the backjump-mode.

__init__(__buffer__, multy_mode, backjump_mode) ¶

Allow multiple sticky marks by multy_mode. Activate via backjump_mode the cursor back moving via cursor_move when a marker is finished and the movement is opposite.

add_marks(*ranges) -> None ¶

Add complete markings. Remove overlapping markings with prioritization of the new ones to be added and sort the markings.

[+] __local_history__ [+] __local_history__.lock

raises:	AssertionError: __local_history__ lock is engaged.

add_new(anchor=None) -> bool ¶

Add a new marking if the current one is not stopped. anchor is a data position can be specified optionally, by default the current cursor position is used.

Return whether a new mark has been added.

[+] __local_history__ [+] __local_history__.lock

raises:	AssertionError: __local_history__ lock is engaged.

coord_snap() -> list[list[int, int]] ¶

New sorted list from snapped (copied) coordinates.

get_aimed_mark(*, _pos=None, _get_index=False, _eq_start=True, _eq_end=False) -> _Marking | int | None ¶

Return the _Marking if the position is in its range.

By default, the current cursor position is used if _pos is not defined, then the currently active marking is also returned, even if it would normally not match; returns -1 in that case if _get_index is True.

The rules _eq_start and _eq_end indicate whether the position also applies to a marking if the position is at the edge of the marking.

If _get_index is True, the index number of the marker object in the list of markings is returned instead of the marking object.

mark_jump_point(trend) -> int | None ¶

Returns the nearest boundary position of a marker, based on the current cursor position in the direction of the trend (positive = forward, negative = backward).

marked_remove(*, aimed=False, rows=False) -> tuple[list[tuple[int, list[tuple[list[str], str | Literal[False] | None]]]], ChunkLoad] | None ¶

Remove and return marked data (records the markings in __local_history__ beforehand).

[+] __local_history__ [+] __local_history__.lock [+] __swap__.adjust [+] __swap__.fill [+] __trimmer__.trim [+] __marker__.adjust [+] __glob_cursor__.adjust [+] __highlighter__.prep_by_chunkload

Remove only the marked data of the current position instead of all when aimed is set. The parameterization via angle brackets defines the evaluation of the position of the cursor at the marking; if only the left angle bracket "<" is selected (default if True is set), the cursor hits the marking even if it is located at the beginning; if only the right angle bracket ">" is passed, the cursor hits the marking even if it is located adjacent to the end, at the beginning of the marking the cursor must be clearly inside; the rules can be combined via "<>".

Understand the marker coordinates as pointers to rows and remove entire rows if rows is True.

The return value

( [ ( coord start: int, removed rows: [ ( row raster: [str], row end: "" | "\n" | None | False ), ... ] ), ... ], final chunk load item)

is composed as follows:

• At index 1 of the tuple is the ChunkLoad.

• At index 0 of the tuple there is a list of items of the removed data:

  • An item is composed of the starting point of the coordinate at index 0 and a list of row data at index 1:

    Row data is a tuple of the remoted content data (tab-separated string of printable characters) at index 0 and the remoted row end (can be "\n" for a line break, "" for a non-breaking line break, None if the row has no line break, or False as a non-removed end) at index 1.

The total return value can be None if nothing was removed.

Relevant ChunkLoad Fields:

• edited_ran
• spec_position
• top_nload
• btm_nload
• top_cut
• btm_cut

raises:	AssertionError: __local_history__ lock is engaged.

marked_shift(*, aimed=False, backshift=False, unique_rows=True) -> tuple[list[tuple[int, list[tuple[list[str], str | Literal[False] | None]]]], ChunkLoad] | None ¶

Shift marked rows.

>>> \t foo bar
>>>     foo bar
origin
>>> \t\t foo bar
>>> \t   foo bar
shifted origin (`tab-to-blanks-mode` not configured)
>>>  foo bar
>>> foo bar
backshifted origin

[+] __local_history__ [+] __local_history__.lock [+] __swap__.adjust [+] __swap__.fill [+] __trimmer__.trim [+] __marker__.adjust [+] __glob_cursor__.adjust [+] __highlighter__.prep_by_chunkload

Shift only the marked rows of the current position instead of all when aimed is set. The parameterization via angle brackets defines the evaluation of the position of the cursor at the marking; if only the left angle bracket "<" is selected (default if True is set), the cursor hits the marking even if it is located at the beginning; if only the right angle bracket ">" is passed, the cursor hits the marking even if it is located adjacent to the end, at the beginning of the marking the cursor must be clearly inside; the rules can be combined via "<>".

If unique_rows is True (default), each row is processed only once, even if multiple coordinates apply to one.

The return value

( [ ( coordinates: list[int, int] | int, write items: [ WriteItem | None, ... ] ), ... ], ChunkLoad ) | None

is composed as follows:

• At index 1 of the tuple is the ChunkLoad.

• At index 0 of the tuple there is a reversed list of (coordinate to WriteItem's) pairs:

  • An pair is composed of the coordinate at index 0 and a list of WriteItem's | None at index 1:

    The list of WriteItem's corresponds to the rows in the coordinate, an entry is None if editing has not taken place in a row.

The total return value can be None if nothing was edited.

Relevant ChunkLoad Fields:

• edited_ran
• spec_position
• top_nload
• btm_nload
• top_cut
• btm_cut

[+] __local_history__ [+] __local_history__.lock [+] __swap__.adjust [+] __swap__.fill [+] __trimmer__.trim [+] __marker__.adjust [+] __glob_cursor__.adjust [+] __highlighter__.prep_by_chunkload

raises:	AssertionError: __local_history__ lock is engaged.

marked_tab_replace(*, aimed=False, row_pointing=True, to_chr=' ') -> tuple[list[tuple[int, list[tuple[list[str], str | Literal[False] | None]]]], ChunkLoad] | None ¶

Replace marked tab spaces to_chr (default is to blanks).

[+] __local_history__ [+] __local_history__.lock [+] __swap__.adjust [+] __swap__.fill [+] __trimmer__.trim [+] __marker__.adjust [+] __glob_cursor__.adjust [+] __highlighter__.prep_by_chunkload

Replace only the marked tab spaces of the current position instead of all when aimed is set. The parameterization via angle brackets defines the evaluation of the position of the cursor at the marking; if only the left angle bracket "<" is selected (default if True is set), the cursor hits the marking even if it is located at the beginning; if only the right angle bracket ">" is passed, the cursor hits the marking even if it is located adjacent to the end, at the beginning of the marking the cursor must be clearly inside; the rules can be combined via "<>".

Understand the marker coordinates as pointers to rows and replace tab spaces in entire rows if row_pointing is True.

The cursor position is adjusted and markers are shortened or extended accordingly, in row_pointing mode the end of a marker is adjusted to the end of the last edited row.

The return value

( [ ( coordinates: list[int, int] | int, write items: [ WriteItem | None, ... ] ), ... ], ChunkLoad ) | None

is composed as follows:

• At index 1 of the tuple is the ChunkLoad.

• At index 0 of the tuple there is a list of (coordinate to WriteItem's) pairs:

  • An pair is composed of the coordinate at index 0 and a list of WriteItem's | None at index 1:

    The list of WriteItem's corresponds to the rows in the coordinate, an entry is None if editing has not taken place in a row.

The total return value can be None if nothing was edited.

Relevant ChunkLoad Fields:

• edited_ran
• spec_position
• top_nload
• btm_nload
• top_cut
• btm_cut

[+] __local_history__ [+] __local_history__.lock [+] __swap__.adjust [+] __swap__.fill [+] __trimmer__.trim [+] __marker__.adjust [+] __glob_cursor__.adjust [+] __highlighter__.prep_by_chunkload

raises:	AssertionError: __local_history__ lock is engaged.

pop_aimed_mark(*, _pos=None, _eq_start=True, _eq_end=False) -> _Marking | None ¶

Remove and return the _Marking if the position is in its range.

[+] __local_history__ [+] __local_history__.lock

By default, the current cursor position is used if _pos is not defined, then the currently active marking is also returned, even if it would normally not match.

The rules _eq_start and _eq_end indicate whether the position also applies to a marking if the position is at the edge of the marking.

raises:	AssertionError: __local_history__ lock is engaged.

purge() -> list[list[int, int]] ¶

Delete all markings.

[+] __local_history__ [+] __local_history__.lock

raises:	AssertionError: __local_history__ lock is engaged.

reader(*, aimed=False, bin_mode=False, endings=None, tabs_to_blanks=False, replace_tabs=None) -> Reader | None ¶

Factory method for the Reader of the marked areas.

Read only the marked rows of the current position instead of all when aimed is set. The parameterization via angle brackets defines the evaluation of the position of the cursor at the marking; if only the left angle bracket "<" is selected (default if True is set), the cursor hits the marking even if it is located at the beginning; if only the right angle bracket ">" is passed, the cursor hits the marking even if it is located adjacent to the end, at the beginning of the marking the cursor must be clearly inside; the rules can be combined via "<>".

To read the data in bytes, bin_mode must be True (UTF-8 encoding) or an encoding.

The association of the row-ends can be defined as dict over endings, the keys must consist of None (no ending), "\n" (newline) and "" (unbroken newline), the parameter value is specified in bytes.

Tabs can be converted by tabs_to_blanks to blanks relative to space; if True is chosen, the size is taken from the buffer, otherwise a different size can be specified as an integer.

An ordinal replacement of tabs can be parameterized via replace_tabs with bytes.

ready(_do_mark, _stop_jump_trend=None) -> int | None ¶

Automation for the cursor movement.

Add a new or stop the current marking depending on _do_mark. Return the outermost position at stop if configured and the movement (_stop_jump_trend) is opposite.

[+] __local_history__ [+] __local_history__.lock

raises:	AssertionError: __local_history__ lock is engaged.

set(n) -> None ¶

Set the second anchor of the current active marking and remove overlapping markings.

[+] __local_history__ [+] __local_history__.lock

raises:	AssertionError: __local_history__ lock is engaged.

set_current(__do_mark=True) -> None ¶

Set the second anchor of the current active marking to the current cursor position if __do_mark is True.

[+] __local_history__ [+] __local_history__.lock

raises:	AssertionError: __local_history__ lock is engaged.

sorted_copy() -> list[_Marking | list[int, int]] ¶

Sorted copy of the main list.

stop() -> None ¶

Stop the current active marking; clean or sort the marker (depending on multy_mode).

[+] __local_history__ [+] __local_history__.lock

raises:	AssertionError: __local_history__ lock is engaged.

Components

class marker._Marking(list) ¶

The marking object implemented as a subclass of list: [ <start position>, <stop position> ]

_¶

anchor: int

trend: None | int

__bool__() -> bool ¶

Whether the anchors are unequal.

lapps(item) -> bool ¶

Whether the markings overlap.

classmethod make(range_) -> _Marking ¶

Create a new marker from the sequence range_.

set(pos) -> None ¶

Set the second anchor.

snap() -> list[int, int] ¶

Creates a new list from the current coordinates.

---

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