Struct r3bl_rs_utils::EditorBuffer

pub struct EditorBuffer { /* private fields */ }

Stores the data for a single editor buffer. Please do not construct this struct directly and use new_empty instead.

1. This struct is stored in the r3bl_redux::Store’s state field.
2. And it is paired w/ EditorEngine at runtime; which is responsible for rendering it to TUI, and handling user input.

Modifying the buffer

InputEvent is converted into an EditorEvent (by EditorEngineApi::apply_event), which is then used to modify the EditorBuffer via:

1. EditorEvent::apply_editor_event
2. EditorEvent::apply_editor_events

In order for the commands to be executed, the functions in EditorEngineInternalApi are used.

These functions take any one of the following args:

1. EditorArgsMut
2. EditorArgs
3. EditorBuffer and EditorEngine

Accessing and mutating the fields (w/ validation)

All the fields in this struct are private. In order to access them you have to use the accessor associated functions. To mutate them, you have to use the get_mut method, which returns a tuple w/ mutable references to the fields. This rather strange design allows for all mutations to be tracked easily and allows for validation operations to be applied post mutation (by validate_editor_buffer_change::apply_change).

Different kinds of caret positions

There are two variants for the caret position value:

1. CaretKind::Raw - this is the position of the caret (unadjusted for scroll_offset) and this represents the position of the caret in the viewport.
2. CaretKind::ScrollAdjusted - this is the position of the caret (adjusted for scroll_offset) and represents the position of the caret in the buffer (not the viewport).

Fields

Please don’t mutate these fields directly, they are not marked pub to guard from unintentional mutation. To mutate or access access it, use get_mut.

lines

A list of lines representing the document being edited.

caret_display_position

This is the “display” (or display_col_index) and not “logical” (or logical_index) position (both are defined in tui_core::graphemes). Please take a look at tui_core::graphemes::UnicodeString, specifically the methods in tui_core::graphemes::access for more details on how the conversion between “display” and “logical” indices is done.

1. It represents the current caret position (relative to the style_adjusted_origin_pos of the enclosing FlexBox).
2. It works w/ crate::RenderOp::MoveCursorPositionRelTo as well.

💡 For the diagrams below, the caret is where ▴ and ▸ intersects.

Start of line:

R ┌──────────┐
0 ▸abcab     │
  └▴─────────┘
  C0123456789

Middle of line:

R ┌──────────┐
0 ▸abcab     │
  └───▴──────┘
  C0123456789

End of line:

R ┌──────────┐
0 ▸abcab     │
  └─────▴────┘
  C0123456789

scroll_offset

The col and row offset for scrolling if active. This is not marked pub in order to guard mutation. In order to access it, use get_mut.

Vertical scrolling and viewport

                   +0--------------------+
                   0                     |
                   |        above        | <- caret_row_adj
                   |                     |
                   +--- scroll_offset ---+
             ->    |         ↑           |      ↑
             |     |                     |      |
  caret.row  |     |      within vp      |  vp height
             |     |                     |      |
             ->    |         ↓           |      ↓
                   +--- scroll_offset ---+
                   |    + vp height      |
                   |                     |
                   |        below        | <- caret_row_adj
                   |                     |
                   +---------------------+

Horizontal scrolling and viewport

          <-   vp width   ->
+0--------+----------------+---------->
0         |                |
| left of |<-  within vp ->| right of
|         |                |
+---------+----------------+---------->
      scroll_offset    scroll_offset
                       + vp width

file_extension

This is used for syntax highlighting. It is a 2 character string, eg: rs or md that is used to lookup the syntax highlighting rules for the language in [find_syntax_by_extensionsyntect::parsing::SyntaxSet::find_syntax_by_extension.

selection_map

The SelectionMap is used to keep track of the selections in the buffer. Each entry in the map represents a row of text in the buffer.

• The row index is the key.
• The value is the SelectionRange.

Implementations

impl EditorBuffer

pub fn new_empty(file_extension: Option<&str>) -> EditorBuffer

Marker method to make it easy to search for where an empty instance is created.

impl EditorBuffer

pub fn has_file_extension(&self) -> bool

pub fn get_maybe_file_extension(&self) -> Option<&str>

pub fn is_empty(&self) -> bool

pub fn len(&self) -> ChUnit

pub fn get_line_display_width(&self, row_index: ChUnit) -> ChUnit

pub fn get_lines(&self) -> &Vec<UnicodeString>

pub fn get_as_string(&self) -> String

pub fn set_lines(&mut self, lines: Vec<String>)

pub fn get_caret(&self, kind: CaretKind) -> Position

Returns the current caret position in two variants:

1. CaretKind::Raw -> The raw caret position not adjusted for scrolling.
2. CaretKind::ScrollAdjusted -> The caret position adjusted for scrolling using scroll_offset.

pub fn calc_scroll_adj_caret_row( caret: &Position, scroll_offset: &Position ) -> usize

Scroll adjusted caret row = caret.row + scroll_offset.row.

pub fn calc_scroll_adj_caret_col( caret: &Position, scroll_offset: &Position ) -> usize

Scroll adjusted caret col = caret.col + scroll_offset.col.

pub fn get_scroll_offset(&self) -> Position

pub fn get_mut( &mut self ) -> (&mut Vec<UnicodeString>, &mut Position, &mut Position, &mut SelectionMap)

Returns:

1. /* lines */ &mut Vec<UnicodeString>,
2. /* caret */ &mut Position,
3. /* scroll_offset */ &mut ScrollOffset,

Even though this struct is mutable by editor_ops.rs, this method is provided to mark when mutable access is made to this struct. This makes it easy to determine what code mutates this struct, since it is necessary to validate things after mutation quite a bit in editor_ops.rs.

pub fn has_selection(&self) -> bool

pub fn clear_selection(&mut self)

pub fn get_selection_map(&self) -> &SelectionMap

Trait Implementations

impl Clone for EditorBuffer

fn clone(&self) -> EditorBuffer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for EditorBuffer

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for EditorBuffer

fn deserialize<__D>( __deserializer: __D ) -> Result<EditorBuffer, <__D as Deserializer<'de>>::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl GetSize for EditorBuffer

fn get_heap_size(&self) -> usize

Determines how many bytes this object occupies inside the heap.

fn get_stack_size() -> usize

Determines how may bytes this object occupies inside the stack.

fn get_size(&self) -> usize

Determines the total size of the object.

impl PartialEq for EditorBuffer

fn eq(&self, other: &EditorBuffer) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for EditorBuffer

fn serialize<__S>( &self, __serializer: __S ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for EditorBuffer