Skip to main content

vim_navigation/
editor.rs

1//! Explicitly mutable Normal/Insert buffer state.
2//!
3//! [`EditableBuffer`] is an opt-in owner of text, mode, cursor, viewport, and
4//! byte-limit invariants. It is intentionally separate from read-only
5//! [`crate::motion::apply`]: an application can reuse every motion without
6//! granting editing capability to its documents.
7//!
8//! In [`Mode::Normal`], the cursor identifies a Unicode scalar value or column
9//! zero on an empty line. In [`Mode::Insert`], it is an insertion point and may
10//! equal the line's byte length. Columns are always UTF-8 byte boundaries;
11//! viewport columns are display cells. Every successful move or edit reveals
12//! the cursor. Wrong-mode commands, line separators passed as
13//! [`EditorInput::Character`], boundary corrections, and input exceeding the
14//! configured byte limit return [`EditOutcome::Ignored`] rather than panicking.
15//!
16//! The caller remains responsible for mapping keys, displaying the active
17//! mode, choosing an input limit, and deciding whether a resource is editable.
18//! Search prompts with their own confirm/cancel semantics need not use this
19//! buffer. The default Insert escape sequence is `jj`; [`EditableBuffer`]
20//! inserts a possible prefix immediately, so a lone prefix is never hidden
21//! behind a timeout.
22//!
23//! # Example
24//!
25//! ```
26//! use vim_navigation::editor::{EditOutcome, EditableBuffer, EditorInput};
27//! use vim_navigation::motion::Viewport;
28//!
29//! let mut buffer =
30//!     EditableBuffer::with_byte_limit("a", Viewport::new(0, 0, 1, 10, 0), 2);
31//! assert_eq!(buffer.handle(EditorInput::Append), EditOutcome::ModeChanged);
32//! assert_eq!(buffer.handle(EditorInput::Character('界')), EditOutcome::Ignored);
33//! assert_eq!(buffer.handle(EditorInput::Character('b')), EditOutcome::Changed);
34//! assert_eq!(buffer.handle(EditorInput::Escape), EditOutcome::ModeChanged);
35//! assert_eq!(buffer.text(), "ab");
36//! ```
37
38use std::error::Error;
39use std::fmt::{self, Display, Formatter};
40
41use crate::{Cursor, Motion, Viewport, apply};
42
43/// The active modal input state.
44#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
45pub enum Mode {
46    /// Motions and insertion-start commands are accepted; text is not changed.
47    #[default]
48    Normal,
49    /// Character input, newline, and basic corrections may mutate the buffer.
50    Insert,
51}
52
53/// Configures the character sequence that leaves Insert mode.
54///
55/// [`Default`] is `jj`. A prefix is inserted into the buffer immediately and
56/// remembered only as a possible escape, so a lone `j`, a mismatch, context
57/// switch, or caller that never supplies another input cannot lose text. When
58/// the complete sequence arrives, its already-inserted prefix is removed and
59/// the buffer follows the same cursor-normalization contract as
60/// [`EditorInput::Escape`].
61///
62/// Use [`Self::disabled`] to permit literal `jj`, or [`Self::new`] to replace
63/// the default with another sequence such as `jk`.
64///
65/// ```
66/// use vim_navigation::InsertEscapeSequence;
67///
68/// assert_eq!(InsertEscapeSequence::default().as_str(), Some("jj"));
69/// assert_eq!(InsertEscapeSequence::new("jk")?.as_str(), Some("jk"));
70/// assert_eq!(InsertEscapeSequence::disabled().as_str(), None);
71/// # Ok::<(), vim_navigation::InsertEscapeSequenceError>(())
72/// ```
73#[derive(Clone, Debug, Eq, PartialEq)]
74pub struct InsertEscapeSequence {
75    sequence: String,
76}
77
78impl InsertEscapeSequence {
79    /// Creates a non-empty escape sequence containing no line separators.
80    ///
81    /// The sequence is matched as Unicode scalar values in insertion order.
82    /// Use [`Self::disabled`] instead of an empty string.
83    ///
84    /// # Errors
85    ///
86    /// Returns [`InsertEscapeSequenceError`] for an empty sequence or one
87    /// containing `\n` or `\r`.
88    pub fn new(sequence: &str) -> Result<Self, InsertEscapeSequenceError> {
89        if sequence.is_empty() || sequence.contains(['\n', '\r']) {
90            return Err(InsertEscapeSequenceError { _private: () });
91        }
92        Ok(Self {
93            sequence: sequence.to_owned(),
94        })
95    }
96
97    /// Disables Insert-mode character escape recognition.
98    ///
99    /// With this setting, `jj` and every other character sequence are inserted
100    /// literally; [`EditorInput::Escape`] remains available.
101    #[must_use]
102    pub const fn disabled() -> Self {
103        Self {
104            sequence: String::new(),
105        }
106    }
107
108    /// Returns the configured sequence, or `None` when recognition is disabled.
109    #[must_use]
110    pub fn as_str(&self) -> Option<&str> {
111        (!self.sequence.is_empty()).then_some(self.sequence.as_str())
112    }
113}
114
115impl Default for InsertEscapeSequence {
116    fn default() -> Self {
117        Self {
118            sequence: "jj".to_owned(),
119        }
120    }
121}
122
123/// An invalid Insert-mode escape sequence.
124///
125/// Sequences must be non-empty and contain no line separators. The type keeps
126/// its representation private so validation can evolve without exposing
127/// additional exhaustive error variants.
128#[derive(Clone, Copy, Debug, Eq, PartialEq)]
129pub struct InsertEscapeSequenceError {
130    _private: (),
131}
132
133impl Display for InsertEscapeSequenceError {
134    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
135        formatter
136            .write_str("insert escape sequence must be non-empty and contain no line separator")
137    }
138}
139
140impl Error for InsertEscapeSequenceError {}
141
142/// Framework-independent input accepted by [`EditableBuffer`].
143#[derive(Clone, Copy, Debug, Eq, PartialEq)]
144pub enum EditorInput {
145    /// Apply a completed Vim motion in Normal mode; ignored in Insert mode.
146    Motion(Motion),
147    /// Start insertion at the cursor (`i`).
148    Insert,
149    /// Start insertion after the cursor (`a`).
150    Append,
151    /// Start insertion at the first non-blank byte (`I`).
152    InsertLineStart,
153    /// Start insertion after the line (`A`).
154    AppendLineEnd,
155    /// Open a new line below and enter Insert mode (`o`).
156    OpenBelow,
157    /// Open a new line above and enter Insert mode (`O`).
158    OpenAbove,
159    /// Insert one non-line-separator Unicode scalar value while in Insert mode.
160    ///
161    /// Use [`EditorInput::Newline`] for `\n` or `\r` input. The byte limit is
162    /// charged by [`char::len_utf8`], not by character or display width.
163    Character(char),
164    /// Split the current line while in Insert mode, charging one separator byte.
165    Newline,
166    /// Delete the preceding scalar value, joining lines at column zero.
167    ///
168    /// At the start of the first line this is ignored.
169    Backspace,
170    /// Delete the next scalar value, joining with the next line at line end.
171    ///
172    /// At the end of the final line this is ignored.
173    Delete,
174    /// Leave Insert mode while preserving content, or do nothing in Normal mode.
175    ///
176    /// On a non-empty line, leaving Insert moves the insertion-point cursor one
177    /// Unicode scalar left to satisfy the Normal-mode cursor invariant.
178    Escape,
179}
180
181/// The observable effect of one editor input.
182#[derive(Clone, Copy, Debug, Eq, PartialEq)]
183pub enum EditOutcome {
184    /// The input has no meaning in the current mode or exceeds the byte limit.
185    Ignored,
186    /// Only the cursor or viewport changed.
187    Moved,
188    /// Buffer content changed; the mode or cursor may also have changed.
189    Changed,
190    /// The mode changed; a recognized Insert escape prefix may also be removed.
191    ModeChanged,
192}
193
194/// A text buffer that opts into mutation separately from read-only motion.
195///
196/// The buffer always contains at least one line. Cursor columns remain UTF-8
197/// boundaries. In Normal mode the cursor is on a character (or column zero for
198/// an empty line); in Insert mode it may also be at the byte length of the line.
199/// The safe public operations clamp external coordinates and report
200/// unsupported or boundary input as [`EditOutcome::Ignored`]; they do not panic
201/// for caller-controlled positions or input.
202#[derive(Debug)]
203pub struct EditableBuffer {
204    lines: Vec<String>,
205    cursor: Cursor,
206    viewport: Viewport,
207    mode: Mode,
208    byte_limit: usize,
209    byte_len: usize,
210    insert_escape_sequence: InsertEscapeSequence,
211    pending_insert_escape: Option<PendingInsertEscape>,
212}
213
214#[derive(Clone, Debug)]
215struct PendingInsertEscape {
216    matched_sequence_bytes: usize,
217    start: Cursor,
218    inserted_text_bytes: usize,
219    // Byte-limit rejection can leave holes in the conceptual prefix. Keep the
220    // actual contribution of each scalar so overlap never removes literal text.
221    inserted_characters: Vec<usize>,
222}
223
224impl EditableBuffer {
225    /// Creates an editable buffer without a library-enforced insertion limit.
226    ///
227    /// Applications accepting untrusted or long-lived input should normally
228    /// choose [`Self::with_byte_limit`] instead.
229    #[must_use]
230    pub fn new(text: &str, viewport: Viewport) -> Self {
231        Self::with_byte_limit(text, viewport, usize::MAX)
232    }
233
234    /// Creates an editable buffer whose future content cannot exceed `byte_limit` bytes.
235    ///
236    /// Existing input is retained even when it already exceeds the limit; the
237    /// limit only prevents additional characters or newlines until corrections
238    /// bring the content below it. The size is UTF-8 content bytes plus one byte
239    /// for each logical `\n` separator. Initial text is preserved verbatim:
240    /// only `\n` splits lines, and `\r` remains content. Callers wanting CRLF
241    /// normalization should perform it before construction.
242    #[must_use]
243    pub fn with_byte_limit(text: &str, viewport: Viewport, byte_limit: usize) -> Self {
244        let lines = text.split('\n').map(str::to_owned).collect::<Vec<_>>();
245        Self {
246            lines,
247            cursor: Cursor::new(0, 0),
248            viewport,
249            mode: Mode::Normal,
250            byte_limit,
251            byte_len: text.len(),
252            insert_escape_sequence: InsertEscapeSequence::default(),
253            pending_insert_escape: None,
254        }
255    }
256
257    /// Replaces the default `jj` Insert escape sequence for this buffer.
258    ///
259    /// This builder is intended for construction-time configuration. Use
260    /// [`Self::set_insert_escape_sequence`] to replace it later.
261    #[must_use]
262    pub fn with_insert_escape_sequence(mut self, sequence: InsertEscapeSequence) -> Self {
263        let _ = self.flush_pending_input();
264        self.insert_escape_sequence = sequence;
265        self
266    }
267
268    /// Returns the active Insert escape sequence configuration.
269    #[must_use]
270    pub const fn insert_escape_sequence(&self) -> &InsertEscapeSequence {
271        &self.insert_escape_sequence
272    }
273
274    /// Replaces the Insert escape sequence without discarding a typed prefix.
275    ///
276    /// A pending prefix has already been inserted literally, so changing the
277    /// configuration commits it simply by forgetting its escape-candidate
278    /// status.
279    pub fn set_insert_escape_sequence(&mut self, sequence: InsertEscapeSequence) {
280        let _ = self.flush_pending_input();
281        self.insert_escape_sequence = sequence;
282    }
283
284    /// Reports whether inserted text still matches a prefix of the escape sequence.
285    #[must_use]
286    pub const fn has_pending_input(&self) -> bool {
287        self.pending_insert_escape.is_some()
288    }
289
290    /// Commits a possible escape prefix as literal input.
291    ///
292    /// The prefix is already present in the text, so this operation only clears
293    /// recognition state and returns whether any state was cleared. Call it
294    /// before an application changes focus or associates this buffer with a
295    /// different input target. Dropping or abandoning the resolver without a
296    /// flush still cannot lose the typed characters.
297    #[must_use]
298    pub fn flush_pending_input(&mut self) -> bool {
299        self.pending_insert_escape.take().is_some()
300    }
301
302    /// Returns the active mode.
303    #[must_use]
304    pub const fn mode(&self) -> Mode {
305        self.mode
306    }
307
308    /// Returns the current cursor.
309    #[must_use]
310    pub const fn cursor(&self) -> Cursor {
311        self.cursor
312    }
313
314    /// Returns the current viewport after any automatic cursor reveal.
315    #[must_use]
316    pub const fn viewport(&self) -> &Viewport {
317        &self.viewport
318    }
319
320    /// Updates the pane dimensions and reveals the cursor in the resized pane.
321    ///
322    /// Height is measured in logical lines; width and gutter are display cells.
323    /// Zero height or width is normalized to one, as in [`Viewport::new`]. Text,
324    /// mode, cursor, desired column, and a pending Insert escape sequence are
325    /// preserved. Only viewport geometry and the scroll position can change.
326    pub fn resize(&mut self, height: usize, width: usize, gutter: usize) {
327        self.viewport = Viewport::new(
328            self.viewport.top(),
329            self.viewport.left(),
330            height,
331            width,
332            gutter,
333        )
334        .with_desired_column(self.viewport.desired_column());
335        self.reveal_cursor();
336    }
337
338    /// Returns the logical lines, including a final empty line after a trailing newline.
339    #[must_use]
340    pub fn lines(&self) -> &[String] {
341        &self.lines
342    }
343
344    /// Returns the content size, including newline separators.
345    #[must_use]
346    pub const fn byte_len(&self) -> usize {
347        self.byte_len
348    }
349
350    /// Allocates and returns the complete buffer content joined with `\n`.
351    #[must_use]
352    pub fn text(&self) -> String {
353        self.lines.join("\n")
354    }
355
356    /// Selects a cursor, clamps it according to the active mode, and reveals it.
357    ///
358    /// A line beyond the buffer selects the final line. A byte inside a UTF-8
359    /// scalar rounds backward to that scalar's start. Subsequent vertical
360    /// motions derive their desired column from this selection.
361    pub fn set_cursor(&mut self, cursor: Cursor) {
362        let _ = self.flush_pending_input();
363        self.cursor = cursor;
364        self.clamp_cursor();
365        self.viewport = self.viewport.with_desired_column(None);
366        self.reveal_cursor();
367    }
368
369    /// Applies one framework-independent input according to the active mode.
370    ///
371    /// [`EditOutcome::Changed`] takes precedence when an input also enters
372    /// Insert mode or moves the cursor, as `o` and `O` do. An ignored input
373    /// leaves content, cursor, viewport, and mode unchanged. It may still
374    /// advance escape-sequence recognition when the byte limit prevents a
375    /// possible prefix from being inserted.
376    pub fn handle(&mut self, input: EditorInput) -> EditOutcome {
377        let outcome = match self.mode {
378            Mode::Normal => self.handle_normal(input),
379            Mode::Insert => self.handle_insert(input),
380        };
381        if outcome != EditOutcome::Ignored {
382            if !matches!(input, EditorInput::Motion(_)) {
383                self.viewport = self.viewport.with_desired_column(None);
384            }
385            self.reveal_cursor();
386        }
387        outcome
388    }
389
390    fn handle_normal(&mut self, input: EditorInput) -> EditOutcome {
391        match input {
392            EditorInput::Motion(motion) => {
393                let before = (self.cursor, self.viewport);
394                let lines = self.lines.iter().map(String::as_str).collect::<Vec<_>>();
395                self.cursor = apply(&lines, self.cursor, &mut self.viewport, motion);
396                if before == (self.cursor, self.viewport) {
397                    EditOutcome::Ignored
398                } else {
399                    EditOutcome::Moved
400                }
401            }
402            EditorInput::Insert => self.enter_insert(self.cursor.byte_column()),
403            EditorInput::Append => {
404                let column = next_boundary(self.current_line(), self.cursor.byte_column());
405                self.enter_insert(column)
406            }
407            EditorInput::InsertLineStart => {
408                let column = self
409                    .current_line()
410                    .char_indices()
411                    .find(|(_, character)| !character.is_whitespace())
412                    .map_or(self.current_line().len(), |(column, _)| column);
413                self.enter_insert(column)
414            }
415            EditorInput::AppendLineEnd => {
416                let column = self.current_line().len();
417                self.enter_insert(column)
418            }
419            EditorInput::OpenBelow => self.open_line(OpenLinePlacement::Below),
420            EditorInput::OpenAbove => self.open_line(OpenLinePlacement::Above),
421            EditorInput::Character(_)
422            | EditorInput::Newline
423            | EditorInput::Backspace
424            | EditorInput::Delete
425            | EditorInput::Escape => EditOutcome::Ignored,
426        }
427    }
428
429    fn handle_insert(&mut self, input: EditorInput) -> EditOutcome {
430        if let EditorInput::Character(character) = input {
431            return self.handle_insert_character(character);
432        }
433        // Non-character input terminates recognition, but the possible prefix
434        // is already literal text. The editing operation then observes it in
435        // exactly the order the caller submitted inputs.
436        let _ = self.flush_pending_input();
437        match input {
438            EditorInput::Newline => self.insert_newline(),
439            EditorInput::Backspace => self.backspace(),
440            EditorInput::Delete => self.delete(),
441            EditorInput::Escape => self.leave_insert_mode(),
442            EditorInput::Character(_) => unreachable!("characters return before this match"),
443            EditorInput::Motion(_)
444            | EditorInput::Insert
445            | EditorInput::Append
446            | EditorInput::InsertLineStart
447            | EditorInput::AppendLineEnd
448            | EditorInput::OpenBelow
449            | EditorInput::OpenAbove => EditOutcome::Ignored,
450        }
451    }
452
453    fn enter_insert(&mut self, column: usize) -> EditOutcome {
454        self.pending_insert_escape = None;
455        self.cursor = Cursor::new(self.cursor.line(), column);
456        self.mode = Mode::Insert;
457        self.clamp_cursor();
458        EditOutcome::ModeChanged
459    }
460
461    fn insert_character(&mut self, character: char) -> EditOutcome {
462        if matches!(character, '\n' | '\r') {
463            return EditOutcome::Ignored;
464        }
465        if self
466            .byte_len
467            .checked_add(character.len_utf8())
468            .is_none_or(|next| next > self.byte_limit)
469        {
470            return EditOutcome::Ignored;
471        }
472        let line = self.cursor.line();
473        let column = self.cursor.byte_column();
474        self.lines[line].insert(column, character);
475        self.cursor = Cursor::new(line, column.saturating_add(character.len_utf8()));
476        self.byte_len = self.byte_len.saturating_add(character.len_utf8());
477        EditOutcome::Changed
478    }
479
480    fn handle_insert_character(&mut self, character: char) -> EditOutcome {
481        if let Some(mut pending) = self.pending_insert_escape.take() {
482            let sequence = &self.insert_escape_sequence.sequence;
483            if !sequence[pending.matched_sequence_bytes..].starts_with(character) {
484                // Retain the longest suffix that is also a prefix and can
485                // accept this character (e.g. aab in aaab). A mismatch commits
486                // only the discarded part as literal text.
487                let matched = &sequence[..pending.matched_sequence_bytes];
488                let overlap = matched
489                    .char_indices()
490                    .enumerate()
491                    .skip(1)
492                    .find(|(_, (byte, _))| {
493                        let suffix = &matched[*byte..];
494                        sequence.starts_with(suffix)
495                            && sequence[suffix.len()..].starts_with(character)
496                    });
497                if let Some((scalars, (byte, _))) = overlap {
498                    let committed: usize = pending.inserted_characters.drain(..scalars).sum();
499                    pending.start = Cursor::new(
500                        pending.start.line(),
501                        pending.start.byte_column() + committed,
502                    );
503                    pending.inserted_text_bytes -= committed;
504                    pending.matched_sequence_bytes -= byte;
505                }
506            }
507            let expected = self.insert_escape_sequence.sequence[pending.matched_sequence_bytes..]
508                .chars()
509                .next();
510            if expected == Some(character) {
511                let matched_sequence_bytes = pending
512                    .matched_sequence_bytes
513                    .saturating_add(character.len_utf8());
514                if matched_sequence_bytes == self.insert_escape_sequence.sequence.len() {
515                    self.remove_pending_escape_prefix(pending);
516                    return self.leave_insert_mode();
517                }
518                let outcome = self.insert_character(character);
519                pending.matched_sequence_bytes = matched_sequence_bytes;
520                if outcome == EditOutcome::Changed {
521                    pending.inserted_text_bytes = pending
522                        .inserted_text_bytes
523                        .saturating_add(character.len_utf8());
524                }
525                pending
526                    .inserted_characters
527                    .push(if outcome == EditOutcome::Changed {
528                        character.len_utf8()
529                    } else {
530                        0
531                    });
532                self.pending_insert_escape = Some(pending);
533                return outcome;
534            }
535            // The existing candidate stays in the buffer as literal text. The
536            // mismatching character may itself start a new candidate, which
537            // matters for replaceable sequences with overlapping prefixes.
538        }
539
540        let Some(first) = self.insert_escape_sequence.sequence.chars().next() else {
541            return self.insert_character(character);
542        };
543        if character != first {
544            return self.insert_character(character);
545        }
546        if character.len_utf8() == self.insert_escape_sequence.sequence.len() {
547            return self.leave_insert_mode();
548        }
549
550        let start = self.cursor;
551        let outcome = self.insert_character(character);
552        self.pending_insert_escape = Some(PendingInsertEscape {
553            matched_sequence_bytes: character.len_utf8(),
554            start,
555            inserted_text_bytes: if outcome == EditOutcome::Changed {
556                character.len_utf8()
557            } else {
558                0
559            },
560            inserted_characters: vec![if outcome == EditOutcome::Changed {
561                character.len_utf8()
562            } else {
563                0
564            }],
565        });
566        outcome
567    }
568
569    fn remove_pending_escape_prefix(&mut self, pending: PendingInsertEscape) {
570        let line = pending.start.line();
571        let start = pending.start.byte_column();
572        let end = start.saturating_add(pending.inserted_text_bytes);
573        if start < end {
574            self.lines[line].drain(start..end);
575            self.byte_len = self.byte_len.saturating_sub(pending.inserted_text_bytes);
576        }
577        self.cursor = pending.start;
578    }
579
580    fn leave_insert_mode(&mut self) -> EditOutcome {
581        self.pending_insert_escape = None;
582        // Vim leaves Insert mode on the character preceding the insertion
583        // point; byte subtraction would split UTF-8.
584        if self.cursor.byte_column() > 0 {
585            let column = previous_boundary(self.current_line(), self.cursor.byte_column());
586            self.cursor = Cursor::new(self.cursor.line(), column);
587        }
588        self.mode = Mode::Normal;
589        self.clamp_cursor();
590        EditOutcome::ModeChanged
591    }
592
593    fn insert_newline(&mut self) -> EditOutcome {
594        if self
595            .byte_len
596            .checked_add(1)
597            .is_none_or(|next| next > self.byte_limit)
598        {
599            return EditOutcome::Ignored;
600        }
601        let line = self.cursor.line();
602        let column = self.cursor.byte_column();
603        let suffix = self.lines[line].split_off(column);
604        self.lines.insert(line.saturating_add(1), suffix);
605        self.cursor = Cursor::new(line.saturating_add(1), 0);
606        self.byte_len = self.byte_len.saturating_add(1);
607        EditOutcome::Changed
608    }
609
610    fn open_line(&mut self, placement: OpenLinePlacement) -> EditOutcome {
611        if self
612            .byte_len
613            .checked_add(1)
614            .is_none_or(|next| next > self.byte_limit)
615        {
616            return EditOutcome::Ignored;
617        }
618        let line = if placement == OpenLinePlacement::Above {
619            self.cursor.line().min(self.lines.len().saturating_sub(1))
620        } else {
621            self.cursor.line().saturating_add(1).min(self.lines.len())
622        };
623        self.lines.insert(line, String::new());
624        self.byte_len = self.byte_len.saturating_add(1);
625        self.cursor = Cursor::new(line, 0);
626        self.mode = Mode::Insert;
627        self.pending_insert_escape = None;
628        EditOutcome::Changed
629    }
630
631    fn backspace(&mut self) -> EditOutcome {
632        let line = self.cursor.line();
633        let column = self.cursor.byte_column();
634        if column > 0 {
635            let previous = previous_boundary(&self.lines[line], column);
636            self.lines[line].drain(previous..column);
637            self.byte_len = self
638                .byte_len
639                .saturating_sub(column.saturating_sub(previous));
640            self.cursor = Cursor::new(line, previous);
641            return EditOutcome::Changed;
642        }
643        if line == 0 {
644            return EditOutcome::Ignored;
645        }
646        let current = self.lines.remove(line);
647        let previous = line.saturating_sub(1);
648        let column = self.lines[previous].len();
649        self.lines[previous].push_str(&current);
650        self.byte_len = self.byte_len.saturating_sub(1);
651        self.cursor = Cursor::new(previous, column);
652        EditOutcome::Changed
653    }
654
655    fn delete(&mut self) -> EditOutcome {
656        let line = self.cursor.line();
657        let column = self.cursor.byte_column();
658        if column < self.lines[line].len() {
659            let next = next_boundary(&self.lines[line], column);
660            self.lines[line].drain(column..next);
661            self.byte_len = self.byte_len.saturating_sub(next.saturating_sub(column));
662            return EditOutcome::Changed;
663        }
664        if line.saturating_add(1) >= self.lines.len() {
665            return EditOutcome::Ignored;
666        }
667        let next = self.lines.remove(line.saturating_add(1));
668        self.lines[line].push_str(&next);
669        self.byte_len = self.byte_len.saturating_sub(1);
670        EditOutcome::Changed
671    }
672
673    fn current_line(&self) -> &str {
674        &self.lines[self.cursor.line()]
675    }
676
677    fn clamp_cursor(&mut self) {
678        let line = self.cursor.line().min(self.lines.len().saturating_sub(1));
679        let text = &self.lines[line];
680        let mut column = self.cursor.byte_column().min(text.len());
681        while !text.is_char_boundary(column) {
682            column = column.saturating_sub(1);
683        }
684        if self.mode == Mode::Normal && column == text.len() && !text.is_empty() {
685            column = previous_boundary(text, text.len());
686        }
687        self.cursor = Cursor::new(line, column);
688    }
689
690    fn reveal_cursor(&mut self) {
691        let line = self.cursor.line();
692        crate::motion::reveal_cursor_line(
693            &self.lines[line],
694            self.lines.len().saturating_sub(1),
695            self.cursor,
696            &mut self.viewport,
697        );
698    }
699}
700
701#[derive(Clone, Copy, Debug, Eq, PartialEq)]
702enum OpenLinePlacement {
703    Above,
704    Below,
705}
706
707fn previous_boundary(line: &str, byte_column: usize) -> usize {
708    let end = byte_column.min(line.len());
709    line[..end]
710        .char_indices()
711        .next_back()
712        .map_or(0, |(column, _)| column)
713}
714
715fn next_boundary(line: &str, byte_column: usize) -> usize {
716    let start = byte_column.min(line.len());
717    line[start..].chars().next().map_or(start, |character| {
718        start.saturating_add(character.len_utf8())
719    })
720}
721
722#[cfg(test)]
723mod tests {
724    use super::{EditOutcome, EditableBuffer, EditorInput, InsertEscapeSequence, Mode};
725    use crate::{Cursor, Motion, MotionKind, Viewport};
726
727    #[test]
728    fn selecting_a_cursor_resets_the_column_for_vertical_motion() {
729        let mut buffer = EditableBuffer::new("abcdef\nx\nabcdef", Viewport::new(0, 0, 3, 20, 0));
730        buffer.set_cursor(Cursor::new(0, 4));
731        let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
732        buffer.set_cursor(Cursor::new(1, 0));
733        let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
734        assert_eq!(buffer.cursor(), Cursor::new(2, 0));
735    }
736
737    #[test]
738    fn leaving_insert_mode_resets_the_column_for_vertical_motion() {
739        for escape in [EditorInput::Escape, EditorInput::Character('j')] {
740            let mut buffer = EditableBuffer::new("abcdef\nabcdef", Viewport::new(0, 0, 2, 20, 0));
741            let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::LineEnd)));
742            let _ = buffer.handle(EditorInput::InsertLineStart);
743            let _ = buffer.handle(EditorInput::Character('界'));
744            if escape == EditorInput::Character('j') {
745                let _ = buffer.handle(escape);
746            }
747            let _ = buffer.handle(escape);
748            let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
749            assert_eq!(buffer.cursor(), Cursor::new(1, 0), "{escape:?}");
750        }
751    }
752
753    #[test]
754    fn normal_insert_correction_newline_and_escape_preserve_content_and_cursor() {
755        let mut buffer = EditableBuffer::new("abcd", Viewport::new(0, 0, 4, 20, 0));
756        assert_eq!(
757            buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Right))),
758            EditOutcome::Moved
759        );
760        assert_eq!(buffer.handle(EditorInput::Insert), EditOutcome::ModeChanged);
761        assert_eq!(
762            buffer.handle(EditorInput::Character('x')),
763            EditOutcome::Changed
764        );
765        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
766        for character in "j3qQ".chars() {
767            assert_eq!(
768                buffer.handle(EditorInput::Character(character)),
769                EditOutcome::Changed
770            );
771        }
772        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
773        assert_eq!(
774            buffer.handle(EditorInput::Character('界')),
775            EditOutcome::Changed
776        );
777        assert_eq!(buffer.handle(EditorInput::Escape), EditOutcome::ModeChanged);
778
779        assert_eq!(buffer.mode(), Mode::Normal);
780        assert_eq!(buffer.text(), "aj3qQ\n界bcd");
781        assert_eq!(buffer.cursor(), Cursor::new(1, 0));
782    }
783
784    #[test]
785    fn insert_mode_treats_motion_letters_digits_and_quit_letters_as_text() {
786        let mut buffer = EditableBuffer::new("", Viewport::new(0, 0, 2, 10, 0));
787        assert_eq!(buffer.handle(EditorInput::Insert), EditOutcome::ModeChanged);
788        for character in "jk123qQ".chars() {
789            let _ = buffer.handle(EditorInput::Character(character));
790        }
791        assert_eq!(buffer.text(), "jk123qQ");
792        assert_eq!(buffer.handle(EditorInput::Escape), EditOutcome::ModeChanged);
793        assert_eq!(buffer.cursor(), Cursor::new(0, 6));
794    }
795
796    #[test]
797    fn byte_limit_and_unicode_corrections_keep_boundaries() {
798        let mut buffer =
799            EditableBuffer::with_byte_limit("界", Viewport::new(0, 0, 2, 10, 0), "界x".len());
800        let _ = buffer.handle(EditorInput::AppendLineEnd);
801        assert_eq!(
802            buffer.handle(EditorInput::Character('x')),
803            EditOutcome::Changed
804        );
805        assert_eq!(
806            buffer.handle(EditorInput::Character('y')),
807            EditOutcome::Ignored
808        );
809        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
810        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
811        assert_eq!(buffer.text(), "");
812        assert_eq!(buffer.cursor(), Cursor::new(0, 0));
813    }
814
815    #[test]
816    fn line_joining_corrections_are_symmetric() {
817        let mut buffer = EditableBuffer::new("one\ntwo", Viewport::new(0, 0, 3, 20, 0));
818        buffer.set_cursor(Cursor::new(1, 0));
819        let _ = buffer.handle(EditorInput::Insert);
820        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
821        assert_eq!(buffer.text(), "onetwo");
822        assert_eq!(buffer.cursor(), Cursor::new(0, 3));
823
824        let _ = buffer.handle(EditorInput::Newline);
825        let _ = buffer.handle(EditorInput::Escape);
826        buffer.set_cursor(Cursor::new(0, 2));
827        let _ = buffer.handle(EditorInput::AppendLineEnd);
828        assert_eq!(buffer.handle(EditorInput::Delete), EditOutcome::Changed);
829        assert_eq!(buffer.text(), "onetwo");
830    }
831
832    #[test]
833    fn new_lines_respect_the_byte_limit() {
834        let mut buffer =
835            EditableBuffer::with_byte_limit("one", Viewport::new(0, 0, 3, 20, 0), "one".len());
836        assert_eq!(buffer.handle(EditorInput::OpenBelow), EditOutcome::Ignored);
837        assert_eq!(buffer.handle(EditorInput::OpenAbove), EditOutcome::Ignored);
838
839        let _ = buffer.handle(EditorInput::AppendLineEnd);
840        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Ignored);
841        assert_eq!(buffer.text(), "one");
842    }
843
844    #[test]
845    fn insert_cursor_stays_visible_and_line_separators_use_newline_input() {
846        let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 1, 2, 0));
847        let _ = buffer.handle(EditorInput::AppendLineEnd);
848        assert_eq!(
849            buffer.handle(EditorInput::Character('\n')),
850            EditOutcome::Ignored
851        );
852        assert_eq!(
853            buffer.handle(EditorInput::Character('\r')),
854            EditOutcome::Ignored
855        );
856        assert_eq!(buffer.text(), "ab");
857
858        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
859        assert_eq!(buffer.cursor(), Cursor::new(1, 0));
860        assert_eq!(buffer.viewport().top(), 1);
861
862        assert_eq!(
863            buffer.handle(EditorInput::Character('界')),
864            EditOutcome::Changed
865        );
866        assert_eq!(buffer.viewport().left(), 1);
867        assert_eq!(buffer.text(), "ab\n界");
868    }
869
870    #[test]
871    fn default_jj_returns_to_normal_without_inserting_the_sequence() {
872        let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
873        let mut escaped = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
874        assert_eq!(
875            buffer.handle(EditorInput::AppendLineEnd),
876            EditOutcome::ModeChanged
877        );
878        let _ = escaped.handle(EditorInput::AppendLineEnd);
879        let _ = escaped.handle(EditorInput::Escape);
880        assert_eq!(
881            buffer.handle(EditorInput::Character('j')),
882            EditOutcome::Changed
883        );
884        assert_eq!(buffer.text(), "abj");
885        assert!(buffer.has_pending_input());
886
887        assert_eq!(
888            buffer.handle(EditorInput::Character('j')),
889            EditOutcome::ModeChanged
890        );
891        assert_eq!(buffer.text(), "ab");
892        assert_eq!(buffer.mode(), Mode::Normal);
893        assert_eq!(buffer.cursor(), Cursor::new(0, 1));
894        assert_eq!(buffer.text(), escaped.text());
895        assert_eq!(buffer.cursor(), escaped.cursor());
896        assert_eq!(buffer.viewport(), escaped.viewport());
897        assert!(!buffer.has_pending_input());
898    }
899
900    #[test]
901    fn lone_j_mismatch_and_context_flush_keep_literal_input_in_order() {
902        let mut buffer = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
903        let _ = buffer.handle(EditorInput::Insert);
904        assert_eq!(
905            buffer.handle(EditorInput::Character('j')),
906            EditOutcome::Changed
907        );
908        assert_eq!(buffer.text(), "j");
909        assert!(buffer.has_pending_input());
910
911        assert_eq!(
912            buffer.handle(EditorInput::Character('界')),
913            EditOutcome::Changed
914        );
915        assert_eq!(buffer.text(), "j界");
916        assert!(!buffer.has_pending_input());
917
918        let _ = buffer.handle(EditorInput::Character('j'));
919        assert!(buffer.flush_pending_input());
920        assert_eq!(buffer.text(), "j界j");
921        assert!(!buffer.flush_pending_input());
922
923        let _ = buffer.handle(EditorInput::Character('j'));
924        buffer.set_cursor(Cursor::new(0, 0));
925        assert_eq!(buffer.text(), "j界jj");
926        assert!(!buffer.has_pending_input());
927
928        let _ = buffer.handle(EditorInput::Character('j'));
929        let before_context_input = buffer.text();
930        assert_eq!(
931            buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Right))),
932            EditOutcome::Ignored
933        );
934        assert_eq!(buffer.text(), before_context_input);
935        assert!(!buffer.has_pending_input());
936
937        let _ = buffer.handle(EditorInput::Character('j'));
938        let before_invalid_character = buffer.text();
939        assert_eq!(
940            buffer.handle(EditorInput::Character('\n')),
941            EditOutcome::Ignored
942        );
943        assert_eq!(buffer.text(), before_invalid_character);
944        assert!(!buffer.has_pending_input());
945    }
946
947    #[test]
948    fn editing_keys_after_j_observe_the_inserted_prefix() {
949        let mut backspace = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
950        let _ = backspace.handle(EditorInput::Insert);
951        let _ = backspace.handle(EditorInput::Character('j'));
952        assert_eq!(
953            backspace.handle(EditorInput::Backspace),
954            EditOutcome::Changed
955        );
956        assert_eq!(backspace.text(), "ab");
957        assert_eq!(backspace.cursor(), Cursor::new(0, 0));
958
959        let mut delete = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
960        let _ = delete.handle(EditorInput::Insert);
961        let _ = delete.handle(EditorInput::Character('j'));
962        assert_eq!(delete.handle(EditorInput::Delete), EditOutcome::Changed);
963        assert_eq!(delete.text(), "jb");
964        assert_eq!(delete.cursor(), Cursor::new(0, 1));
965
966        let mut newline = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
967        let _ = newline.handle(EditorInput::Insert);
968        let _ = newline.handle(EditorInput::Character('j'));
969        assert_eq!(newline.handle(EditorInput::Newline), EditOutcome::Changed);
970        assert_eq!(newline.text(), "j\n");
971        assert_eq!(newline.cursor(), Cursor::new(1, 0));
972
973        let mut escape = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
974        let _ = escape.handle(EditorInput::Insert);
975        let _ = escape.handle(EditorInput::Character('j'));
976        assert_eq!(escape.handle(EditorInput::Escape), EditOutcome::ModeChanged);
977        assert_eq!(escape.text(), "j");
978        assert_eq!(escape.mode(), Mode::Normal);
979        assert_eq!(escape.cursor(), Cursor::new(0, 0));
980    }
981
982    #[test]
983    fn insert_escape_can_be_disabled_or_replaced_for_literal_jj() {
984        let mut literal = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0))
985            .with_insert_escape_sequence(InsertEscapeSequence::disabled());
986        let _ = literal.handle(EditorInput::Insert);
987        let _ = literal.handle(EditorInput::Character('j'));
988        let _ = literal.handle(EditorInput::Character('j'));
989        assert_eq!(literal.text(), "jj");
990        assert_eq!(literal.mode(), Mode::Insert);
991
992        let sequence = InsertEscapeSequence::new("jk")
993            .unwrap_or_else(|error| panic!("valid sequence: {error}"));
994        let mut replaced = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0))
995            .with_insert_escape_sequence(sequence);
996        let _ = replaced.handle(EditorInput::Insert);
997        let _ = replaced.handle(EditorInput::Character('j'));
998        let _ = replaced.handle(EditorInput::Character('j'));
999        assert_eq!(replaced.text(), "jj");
1000        assert!(replaced.flush_pending_input());
1001        let _ = replaced.handle(EditorInput::Character('j'));
1002        assert_eq!(
1003            replaced.handle(EditorInput::Character('k')),
1004            EditOutcome::ModeChanged
1005        );
1006        assert_eq!(replaced.text(), "jj");
1007        assert_eq!(replaced.mode(), Mode::Normal);
1008
1009        let mut reconfigured = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
1010        let _ = reconfigured.handle(EditorInput::Insert);
1011        let _ = reconfigured.handle(EditorInput::Character('j'));
1012        assert!(reconfigured.has_pending_input());
1013        reconfigured.set_insert_escape_sequence(InsertEscapeSequence::disabled());
1014        assert_eq!(reconfigured.text(), "j");
1015        assert!(!reconfigured.has_pending_input());
1016        let _ = reconfigured.handle(EditorInput::Character('j'));
1017        assert_eq!(reconfigured.text(), "jj");
1018        assert_eq!(reconfigured.mode(), Mode::Insert);
1019    }
1020
1021    #[test]
1022    fn insert_escape_respects_byte_limits_and_unicode_sequences() {
1023        let mut full =
1024            EditableBuffer::with_byte_limit("x", Viewport::new(0, 0, 2, 20, 0), "x".len());
1025        let _ = full.handle(EditorInput::AppendLineEnd);
1026        assert_eq!(
1027            full.handle(EditorInput::Character('j')),
1028            EditOutcome::Ignored
1029        );
1030        assert!(full.has_pending_input());
1031        assert_eq!(
1032            full.handle(EditorInput::Character('j')),
1033            EditOutcome::ModeChanged
1034        );
1035        assert_eq!(full.text(), "x");
1036        assert_eq!(full.mode(), Mode::Normal);
1037
1038        let sequence = InsertEscapeSequence::new("界界")
1039            .unwrap_or_else(|error| panic!("valid Unicode sequence: {error}"));
1040        let mut unicode = EditableBuffer::new("a", Viewport::new(0, 0, 2, 20, 0))
1041            .with_insert_escape_sequence(sequence);
1042        let _ = unicode.handle(EditorInput::AppendLineEnd);
1043        let _ = unicode.handle(EditorInput::Character('界'));
1044        assert_eq!(unicode.text(), "a界");
1045        assert_eq!(
1046            unicode.handle(EditorInput::Character('界')),
1047            EditOutcome::ModeChanged
1048        );
1049        assert_eq!(unicode.text(), "a");
1050        assert_eq!(unicode.cursor(), Cursor::new(0, 0));
1051
1052        assert!(InsertEscapeSequence::new("").is_err());
1053        assert!(InsertEscapeSequence::new("j\nj").is_err());
1054    }
1055}