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, Copy, Debug)]
215struct PendingInsertEscape {
216    matched_sequence_bytes: usize,
217    start: Cursor,
218    inserted_text_bytes: usize,
219}
220
221impl EditableBuffer {
222    /// Creates an editable buffer without a library-enforced insertion limit.
223    ///
224    /// Applications accepting untrusted or long-lived input should normally
225    /// choose [`Self::with_byte_limit`] instead.
226    #[must_use]
227    pub fn new(text: &str, viewport: Viewport) -> Self {
228        Self::with_byte_limit(text, viewport, usize::MAX)
229    }
230
231    /// Creates an editable buffer whose future content cannot exceed `byte_limit` bytes.
232    ///
233    /// Existing input is retained even when it already exceeds the limit; the
234    /// limit only prevents additional characters or newlines until corrections
235    /// bring the content below it. The size is UTF-8 content bytes plus one byte
236    /// for each logical `\n` separator. Initial text is preserved verbatim:
237    /// only `\n` splits lines, and `\r` remains content. Callers wanting CRLF
238    /// normalization should perform it before construction.
239    #[must_use]
240    pub fn with_byte_limit(text: &str, viewport: Viewport, byte_limit: usize) -> Self {
241        let lines = text.split('\n').map(str::to_owned).collect::<Vec<_>>();
242        Self {
243            lines,
244            cursor: Cursor::new(0, 0),
245            viewport,
246            mode: Mode::Normal,
247            byte_limit,
248            byte_len: text.len(),
249            insert_escape_sequence: InsertEscapeSequence::default(),
250            pending_insert_escape: None,
251        }
252    }
253
254    /// Replaces the default `jj` Insert escape sequence for this buffer.
255    ///
256    /// This builder is intended for construction-time configuration. Use
257    /// [`Self::set_insert_escape_sequence`] to replace it later.
258    #[must_use]
259    pub fn with_insert_escape_sequence(mut self, sequence: InsertEscapeSequence) -> Self {
260        let _ = self.flush_pending_input();
261        self.insert_escape_sequence = sequence;
262        self
263    }
264
265    /// Returns the active Insert escape sequence configuration.
266    #[must_use]
267    pub const fn insert_escape_sequence(&self) -> &InsertEscapeSequence {
268        &self.insert_escape_sequence
269    }
270
271    /// Replaces the Insert escape sequence without discarding a typed prefix.
272    ///
273    /// A pending prefix has already been inserted literally, so changing the
274    /// configuration commits it simply by forgetting its escape-candidate
275    /// status.
276    pub fn set_insert_escape_sequence(&mut self, sequence: InsertEscapeSequence) {
277        let _ = self.flush_pending_input();
278        self.insert_escape_sequence = sequence;
279    }
280
281    /// Reports whether inserted text still matches a prefix of the escape sequence.
282    #[must_use]
283    pub const fn has_pending_input(&self) -> bool {
284        self.pending_insert_escape.is_some()
285    }
286
287    /// Commits a possible escape prefix as literal input.
288    ///
289    /// The prefix is already present in the text, so this operation only clears
290    /// recognition state and returns whether any state was cleared. Call it
291    /// before an application changes focus or associates this buffer with a
292    /// different input target. Dropping or abandoning the resolver without a
293    /// flush still cannot lose the typed characters.
294    #[must_use]
295    pub fn flush_pending_input(&mut self) -> bool {
296        self.pending_insert_escape.take().is_some()
297    }
298
299    /// Returns the active mode.
300    #[must_use]
301    pub const fn mode(&self) -> Mode {
302        self.mode
303    }
304
305    /// Returns the current cursor.
306    #[must_use]
307    pub const fn cursor(&self) -> Cursor {
308        self.cursor
309    }
310
311    /// Returns the current viewport after any automatic cursor reveal.
312    #[must_use]
313    pub const fn viewport(&self) -> &Viewport {
314        &self.viewport
315    }
316
317    /// Returns the logical lines, including a final empty line after a trailing newline.
318    #[must_use]
319    pub fn lines(&self) -> &[String] {
320        &self.lines
321    }
322
323    /// Returns the content size, including newline separators.
324    #[must_use]
325    pub const fn byte_len(&self) -> usize {
326        self.byte_len
327    }
328
329    /// Allocates and returns the complete buffer content joined with `\n`.
330    #[must_use]
331    pub fn text(&self) -> String {
332        self.lines.join("\n")
333    }
334
335    /// Selects a cursor, clamps it according to the active mode, and reveals it.
336    ///
337    /// A line beyond the buffer selects the final line. A byte inside a UTF-8
338    /// scalar rounds backward to that scalar's start. Subsequent vertical
339    /// motions derive their desired column from this selection.
340    pub fn set_cursor(&mut self, cursor: Cursor) {
341        let _ = self.flush_pending_input();
342        self.cursor = cursor;
343        self.clamp_cursor();
344        self.viewport = self.viewport.with_desired_column(None);
345        self.reveal_cursor();
346    }
347
348    /// Applies one framework-independent input according to the active mode.
349    ///
350    /// [`EditOutcome::Changed`] takes precedence when an input also enters
351    /// Insert mode or moves the cursor, as `o` and `O` do. An ignored input
352    /// leaves content, cursor, viewport, and mode unchanged. It may still
353    /// advance escape-sequence recognition when the byte limit prevents a
354    /// possible prefix from being inserted.
355    pub fn handle(&mut self, input: EditorInput) -> EditOutcome {
356        let outcome = match self.mode {
357            Mode::Normal => self.handle_normal(input),
358            Mode::Insert => self.handle_insert(input),
359        };
360        if outcome != EditOutcome::Ignored {
361            if !matches!(input, EditorInput::Motion(_)) {
362                self.viewport = self.viewport.with_desired_column(None);
363            }
364            self.reveal_cursor();
365        }
366        outcome
367    }
368
369    fn handle_normal(&mut self, input: EditorInput) -> EditOutcome {
370        match input {
371            EditorInput::Motion(motion) => {
372                let before = (self.cursor, self.viewport);
373                let lines = self.lines.iter().map(String::as_str).collect::<Vec<_>>();
374                self.cursor = apply(&lines, self.cursor, &mut self.viewport, motion);
375                if before == (self.cursor, self.viewport) {
376                    EditOutcome::Ignored
377                } else {
378                    EditOutcome::Moved
379                }
380            }
381            EditorInput::Insert => self.enter_insert(self.cursor.byte_column()),
382            EditorInput::Append => {
383                let column = next_boundary(self.current_line(), self.cursor.byte_column());
384                self.enter_insert(column)
385            }
386            EditorInput::InsertLineStart => {
387                let column = self
388                    .current_line()
389                    .char_indices()
390                    .find(|(_, character)| !character.is_whitespace())
391                    .map_or(self.current_line().len(), |(column, _)| column);
392                self.enter_insert(column)
393            }
394            EditorInput::AppendLineEnd => {
395                let column = self.current_line().len();
396                self.enter_insert(column)
397            }
398            EditorInput::OpenBelow => self.open_line(false),
399            EditorInput::OpenAbove => self.open_line(true),
400            EditorInput::Character(_)
401            | EditorInput::Newline
402            | EditorInput::Backspace
403            | EditorInput::Delete
404            | EditorInput::Escape => EditOutcome::Ignored,
405        }
406    }
407
408    fn handle_insert(&mut self, input: EditorInput) -> EditOutcome {
409        if let EditorInput::Character(character) = input {
410            return self.handle_insert_character(character);
411        }
412        // Non-character input terminates recognition, but the possible prefix
413        // is already literal text. The editing operation then observes it in
414        // exactly the order the caller submitted inputs.
415        let _ = self.flush_pending_input();
416        match input {
417            EditorInput::Newline => self.insert_newline(),
418            EditorInput::Backspace => self.backspace(),
419            EditorInput::Delete => self.delete(),
420            EditorInput::Escape => self.leave_insert_mode(),
421            EditorInput::Character(_) => unreachable!("characters return before this match"),
422            EditorInput::Motion(_)
423            | EditorInput::Insert
424            | EditorInput::Append
425            | EditorInput::InsertLineStart
426            | EditorInput::AppendLineEnd
427            | EditorInput::OpenBelow
428            | EditorInput::OpenAbove => EditOutcome::Ignored,
429        }
430    }
431
432    fn enter_insert(&mut self, column: usize) -> EditOutcome {
433        self.pending_insert_escape = None;
434        self.cursor = Cursor::new(self.cursor.line(), column);
435        self.mode = Mode::Insert;
436        self.clamp_cursor();
437        EditOutcome::ModeChanged
438    }
439
440    fn insert_character(&mut self, character: char) -> EditOutcome {
441        if matches!(character, '\n' | '\r') {
442            return EditOutcome::Ignored;
443        }
444        if self
445            .byte_len
446            .checked_add(character.len_utf8())
447            .is_none_or(|next| next > self.byte_limit)
448        {
449            return EditOutcome::Ignored;
450        }
451        let line = self.cursor.line();
452        let column = self.cursor.byte_column();
453        self.lines[line].insert(column, character);
454        self.cursor = Cursor::new(line, column.saturating_add(character.len_utf8()));
455        self.byte_len = self.byte_len.saturating_add(character.len_utf8());
456        EditOutcome::Changed
457    }
458
459    fn handle_insert_character(&mut self, character: char) -> EditOutcome {
460        if let Some(mut pending) = self.pending_insert_escape.take() {
461            let expected = self.insert_escape_sequence.sequence[pending.matched_sequence_bytes..]
462                .chars()
463                .next();
464            if expected == Some(character) {
465                let matched_sequence_bytes = pending
466                    .matched_sequence_bytes
467                    .saturating_add(character.len_utf8());
468                if matched_sequence_bytes == self.insert_escape_sequence.sequence.len() {
469                    self.remove_pending_escape_prefix(pending);
470                    return self.leave_insert_mode();
471                }
472                let outcome = self.insert_character(character);
473                pending.matched_sequence_bytes = matched_sequence_bytes;
474                if outcome == EditOutcome::Changed {
475                    pending.inserted_text_bytes = pending
476                        .inserted_text_bytes
477                        .saturating_add(character.len_utf8());
478                }
479                self.pending_insert_escape = Some(pending);
480                return outcome;
481            }
482            // The existing candidate stays in the buffer as literal text. The
483            // mismatching character may itself start a new candidate, which
484            // matters for replaceable sequences with overlapping prefixes.
485        }
486
487        let Some(first) = self.insert_escape_sequence.sequence.chars().next() else {
488            return self.insert_character(character);
489        };
490        if character != first {
491            return self.insert_character(character);
492        }
493        if character.len_utf8() == self.insert_escape_sequence.sequence.len() {
494            return self.leave_insert_mode();
495        }
496
497        let start = self.cursor;
498        let outcome = self.insert_character(character);
499        self.pending_insert_escape = Some(PendingInsertEscape {
500            matched_sequence_bytes: character.len_utf8(),
501            start,
502            inserted_text_bytes: if outcome == EditOutcome::Changed {
503                character.len_utf8()
504            } else {
505                0
506            },
507        });
508        outcome
509    }
510
511    fn remove_pending_escape_prefix(&mut self, pending: PendingInsertEscape) {
512        let line = pending.start.line();
513        let start = pending.start.byte_column();
514        let end = start.saturating_add(pending.inserted_text_bytes);
515        if start < end {
516            self.lines[line].drain(start..end);
517            self.byte_len = self.byte_len.saturating_sub(pending.inserted_text_bytes);
518        }
519        self.cursor = pending.start;
520    }
521
522    fn leave_insert_mode(&mut self) -> EditOutcome {
523        self.pending_insert_escape = None;
524        // Vim leaves Insert mode on the character preceding the insertion
525        // point; byte subtraction would split UTF-8.
526        if self.cursor.byte_column() > 0 {
527            let column = previous_boundary(self.current_line(), self.cursor.byte_column());
528            self.cursor = Cursor::new(self.cursor.line(), column);
529        }
530        self.mode = Mode::Normal;
531        self.clamp_cursor();
532        EditOutcome::ModeChanged
533    }
534
535    fn insert_newline(&mut self) -> EditOutcome {
536        if self
537            .byte_len
538            .checked_add(1)
539            .is_none_or(|next| next > self.byte_limit)
540        {
541            return EditOutcome::Ignored;
542        }
543        let line = self.cursor.line();
544        let column = self.cursor.byte_column();
545        let suffix = self.lines[line].split_off(column);
546        self.lines.insert(line.saturating_add(1), suffix);
547        self.cursor = Cursor::new(line.saturating_add(1), 0);
548        self.byte_len = self.byte_len.saturating_add(1);
549        EditOutcome::Changed
550    }
551
552    fn open_line(&mut self, above: bool) -> EditOutcome {
553        if self
554            .byte_len
555            .checked_add(1)
556            .is_none_or(|next| next > self.byte_limit)
557        {
558            return EditOutcome::Ignored;
559        }
560        let line = if above {
561            self.cursor.line().min(self.lines.len().saturating_sub(1))
562        } else {
563            self.cursor.line().saturating_add(1).min(self.lines.len())
564        };
565        self.lines.insert(line, String::new());
566        self.byte_len = self.byte_len.saturating_add(1);
567        self.cursor = Cursor::new(line, 0);
568        self.mode = Mode::Insert;
569        self.pending_insert_escape = None;
570        EditOutcome::Changed
571    }
572
573    fn backspace(&mut self) -> EditOutcome {
574        let line = self.cursor.line();
575        let column = self.cursor.byte_column();
576        if column > 0 {
577            let previous = previous_boundary(&self.lines[line], column);
578            self.lines[line].drain(previous..column);
579            self.byte_len = self
580                .byte_len
581                .saturating_sub(column.saturating_sub(previous));
582            self.cursor = Cursor::new(line, previous);
583            return EditOutcome::Changed;
584        }
585        if line == 0 {
586            return EditOutcome::Ignored;
587        }
588        let current = self.lines.remove(line);
589        let previous = line.saturating_sub(1);
590        let column = self.lines[previous].len();
591        self.lines[previous].push_str(&current);
592        self.byte_len = self.byte_len.saturating_sub(1);
593        self.cursor = Cursor::new(previous, column);
594        EditOutcome::Changed
595    }
596
597    fn delete(&mut self) -> EditOutcome {
598        let line = self.cursor.line();
599        let column = self.cursor.byte_column();
600        if column < self.lines[line].len() {
601            let next = next_boundary(&self.lines[line], column);
602            self.lines[line].drain(column..next);
603            self.byte_len = self.byte_len.saturating_sub(next.saturating_sub(column));
604            return EditOutcome::Changed;
605        }
606        if line.saturating_add(1) >= self.lines.len() {
607            return EditOutcome::Ignored;
608        }
609        let next = self.lines.remove(line.saturating_add(1));
610        self.lines[line].push_str(&next);
611        self.byte_len = self.byte_len.saturating_sub(1);
612        EditOutcome::Changed
613    }
614
615    fn current_line(&self) -> &str {
616        &self.lines[self.cursor.line()]
617    }
618
619    fn clamp_cursor(&mut self) {
620        let line = self.cursor.line().min(self.lines.len().saturating_sub(1));
621        let text = &self.lines[line];
622        let mut column = self.cursor.byte_column().min(text.len());
623        while !text.is_char_boundary(column) {
624            column = column.saturating_sub(1);
625        }
626        if self.mode == Mode::Normal && column == text.len() && !text.is_empty() {
627            column = previous_boundary(text, text.len());
628        }
629        self.cursor = Cursor::new(line, column);
630    }
631
632    fn reveal_cursor(&mut self) {
633        let line = self.cursor.line();
634        crate::motion::reveal_cursor_line(
635            &self.lines[line],
636            self.lines.len().saturating_sub(1),
637            self.cursor,
638            &mut self.viewport,
639        );
640    }
641}
642
643fn previous_boundary(line: &str, byte_column: usize) -> usize {
644    let end = byte_column.min(line.len());
645    line[..end]
646        .char_indices()
647        .next_back()
648        .map_or(0, |(column, _)| column)
649}
650
651fn next_boundary(line: &str, byte_column: usize) -> usize {
652    let start = byte_column.min(line.len());
653    line[start..].chars().next().map_or(start, |character| {
654        start.saturating_add(character.len_utf8())
655    })
656}
657
658#[cfg(test)]
659mod tests {
660    use super::{EditOutcome, EditableBuffer, EditorInput, InsertEscapeSequence, Mode};
661    use crate::{Cursor, Motion, MotionKind, Viewport};
662
663    #[test]
664    fn selecting_a_cursor_resets_the_column_for_vertical_motion() {
665        let mut buffer = EditableBuffer::new("abcdef\nx\nabcdef", Viewport::new(0, 0, 3, 20, 0));
666        buffer.set_cursor(Cursor::new(0, 4));
667        let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
668        buffer.set_cursor(Cursor::new(1, 0));
669        let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
670        assert_eq!(buffer.cursor(), Cursor::new(2, 0));
671    }
672
673    #[test]
674    fn leaving_insert_mode_resets_the_column_for_vertical_motion() {
675        for escape in [EditorInput::Escape, EditorInput::Character('j')] {
676            let mut buffer = EditableBuffer::new("abcdef\nabcdef", Viewport::new(0, 0, 2, 20, 0));
677            let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::LineEnd)));
678            let _ = buffer.handle(EditorInput::InsertLineStart);
679            let _ = buffer.handle(EditorInput::Character('界'));
680            if escape == EditorInput::Character('j') {
681                let _ = buffer.handle(escape);
682            }
683            let _ = buffer.handle(escape);
684            let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
685            assert_eq!(buffer.cursor(), Cursor::new(1, 0), "{escape:?}");
686        }
687    }
688
689    #[test]
690    fn normal_insert_correction_newline_and_escape_preserve_content_and_cursor() {
691        let mut buffer = EditableBuffer::new("abcd", Viewport::new(0, 0, 4, 20, 0));
692        assert_eq!(
693            buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Right))),
694            EditOutcome::Moved
695        );
696        assert_eq!(buffer.handle(EditorInput::Insert), EditOutcome::ModeChanged);
697        assert_eq!(
698            buffer.handle(EditorInput::Character('x')),
699            EditOutcome::Changed
700        );
701        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
702        for character in "j3qQ".chars() {
703            assert_eq!(
704                buffer.handle(EditorInput::Character(character)),
705                EditOutcome::Changed
706            );
707        }
708        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
709        assert_eq!(
710            buffer.handle(EditorInput::Character('界')),
711            EditOutcome::Changed
712        );
713        assert_eq!(buffer.handle(EditorInput::Escape), EditOutcome::ModeChanged);
714
715        assert_eq!(buffer.mode(), Mode::Normal);
716        assert_eq!(buffer.text(), "aj3qQ\n界bcd");
717        assert_eq!(buffer.cursor(), Cursor::new(1, 0));
718    }
719
720    #[test]
721    fn insert_mode_treats_motion_letters_digits_and_quit_letters_as_text() {
722        let mut buffer = EditableBuffer::new("", Viewport::new(0, 0, 2, 10, 0));
723        assert_eq!(buffer.handle(EditorInput::Insert), EditOutcome::ModeChanged);
724        for character in "jk123qQ".chars() {
725            let _ = buffer.handle(EditorInput::Character(character));
726        }
727        assert_eq!(buffer.text(), "jk123qQ");
728        assert_eq!(buffer.handle(EditorInput::Escape), EditOutcome::ModeChanged);
729        assert_eq!(buffer.cursor(), Cursor::new(0, 6));
730    }
731
732    #[test]
733    fn byte_limit_and_unicode_corrections_keep_boundaries() {
734        let mut buffer =
735            EditableBuffer::with_byte_limit("界", Viewport::new(0, 0, 2, 10, 0), "界x".len());
736        let _ = buffer.handle(EditorInput::AppendLineEnd);
737        assert_eq!(
738            buffer.handle(EditorInput::Character('x')),
739            EditOutcome::Changed
740        );
741        assert_eq!(
742            buffer.handle(EditorInput::Character('y')),
743            EditOutcome::Ignored
744        );
745        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
746        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
747        assert_eq!(buffer.text(), "");
748        assert_eq!(buffer.cursor(), Cursor::new(0, 0));
749    }
750
751    #[test]
752    fn line_joining_corrections_are_symmetric() {
753        let mut buffer = EditableBuffer::new("one\ntwo", Viewport::new(0, 0, 3, 20, 0));
754        buffer.set_cursor(Cursor::new(1, 0));
755        let _ = buffer.handle(EditorInput::Insert);
756        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
757        assert_eq!(buffer.text(), "onetwo");
758        assert_eq!(buffer.cursor(), Cursor::new(0, 3));
759
760        let _ = buffer.handle(EditorInput::Newline);
761        let _ = buffer.handle(EditorInput::Escape);
762        buffer.set_cursor(Cursor::new(0, 2));
763        let _ = buffer.handle(EditorInput::AppendLineEnd);
764        assert_eq!(buffer.handle(EditorInput::Delete), EditOutcome::Changed);
765        assert_eq!(buffer.text(), "onetwo");
766    }
767
768    #[test]
769    fn new_lines_respect_the_byte_limit() {
770        let mut buffer =
771            EditableBuffer::with_byte_limit("one", Viewport::new(0, 0, 3, 20, 0), "one".len());
772        assert_eq!(buffer.handle(EditorInput::OpenBelow), EditOutcome::Ignored);
773        assert_eq!(buffer.handle(EditorInput::OpenAbove), EditOutcome::Ignored);
774
775        let _ = buffer.handle(EditorInput::AppendLineEnd);
776        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Ignored);
777        assert_eq!(buffer.text(), "one");
778    }
779
780    #[test]
781    fn insert_cursor_stays_visible_and_line_separators_use_newline_input() {
782        let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 1, 2, 0));
783        let _ = buffer.handle(EditorInput::AppendLineEnd);
784        assert_eq!(
785            buffer.handle(EditorInput::Character('\n')),
786            EditOutcome::Ignored
787        );
788        assert_eq!(
789            buffer.handle(EditorInput::Character('\r')),
790            EditOutcome::Ignored
791        );
792        assert_eq!(buffer.text(), "ab");
793
794        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
795        assert_eq!(buffer.cursor(), Cursor::new(1, 0));
796        assert_eq!(buffer.viewport().top(), 1);
797
798        assert_eq!(
799            buffer.handle(EditorInput::Character('界')),
800            EditOutcome::Changed
801        );
802        assert_eq!(buffer.viewport().left(), 1);
803        assert_eq!(buffer.text(), "ab\n界");
804    }
805
806    #[test]
807    fn default_jj_returns_to_normal_without_inserting_the_sequence() {
808        let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
809        let mut escaped = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
810        assert_eq!(
811            buffer.handle(EditorInput::AppendLineEnd),
812            EditOutcome::ModeChanged
813        );
814        let _ = escaped.handle(EditorInput::AppendLineEnd);
815        let _ = escaped.handle(EditorInput::Escape);
816        assert_eq!(
817            buffer.handle(EditorInput::Character('j')),
818            EditOutcome::Changed
819        );
820        assert_eq!(buffer.text(), "abj");
821        assert!(buffer.has_pending_input());
822
823        assert_eq!(
824            buffer.handle(EditorInput::Character('j')),
825            EditOutcome::ModeChanged
826        );
827        assert_eq!(buffer.text(), "ab");
828        assert_eq!(buffer.mode(), Mode::Normal);
829        assert_eq!(buffer.cursor(), Cursor::new(0, 1));
830        assert_eq!(buffer.text(), escaped.text());
831        assert_eq!(buffer.cursor(), escaped.cursor());
832        assert_eq!(buffer.viewport(), escaped.viewport());
833        assert!(!buffer.has_pending_input());
834    }
835
836    #[test]
837    fn lone_j_mismatch_and_context_flush_keep_literal_input_in_order() {
838        let mut buffer = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
839        let _ = buffer.handle(EditorInput::Insert);
840        assert_eq!(
841            buffer.handle(EditorInput::Character('j')),
842            EditOutcome::Changed
843        );
844        assert_eq!(buffer.text(), "j");
845        assert!(buffer.has_pending_input());
846
847        assert_eq!(
848            buffer.handle(EditorInput::Character('界')),
849            EditOutcome::Changed
850        );
851        assert_eq!(buffer.text(), "j界");
852        assert!(!buffer.has_pending_input());
853
854        let _ = buffer.handle(EditorInput::Character('j'));
855        assert!(buffer.flush_pending_input());
856        assert_eq!(buffer.text(), "j界j");
857        assert!(!buffer.flush_pending_input());
858
859        let _ = buffer.handle(EditorInput::Character('j'));
860        buffer.set_cursor(Cursor::new(0, 0));
861        assert_eq!(buffer.text(), "j界jj");
862        assert!(!buffer.has_pending_input());
863
864        let _ = buffer.handle(EditorInput::Character('j'));
865        let before_context_input = buffer.text();
866        assert_eq!(
867            buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Right))),
868            EditOutcome::Ignored
869        );
870        assert_eq!(buffer.text(), before_context_input);
871        assert!(!buffer.has_pending_input());
872
873        let _ = buffer.handle(EditorInput::Character('j'));
874        let before_invalid_character = buffer.text();
875        assert_eq!(
876            buffer.handle(EditorInput::Character('\n')),
877            EditOutcome::Ignored
878        );
879        assert_eq!(buffer.text(), before_invalid_character);
880        assert!(!buffer.has_pending_input());
881    }
882
883    #[test]
884    fn editing_keys_after_j_observe_the_inserted_prefix() {
885        let mut backspace = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
886        let _ = backspace.handle(EditorInput::Insert);
887        let _ = backspace.handle(EditorInput::Character('j'));
888        assert_eq!(
889            backspace.handle(EditorInput::Backspace),
890            EditOutcome::Changed
891        );
892        assert_eq!(backspace.text(), "ab");
893        assert_eq!(backspace.cursor(), Cursor::new(0, 0));
894
895        let mut delete = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
896        let _ = delete.handle(EditorInput::Insert);
897        let _ = delete.handle(EditorInput::Character('j'));
898        assert_eq!(delete.handle(EditorInput::Delete), EditOutcome::Changed);
899        assert_eq!(delete.text(), "jb");
900        assert_eq!(delete.cursor(), Cursor::new(0, 1));
901
902        let mut newline = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
903        let _ = newline.handle(EditorInput::Insert);
904        let _ = newline.handle(EditorInput::Character('j'));
905        assert_eq!(newline.handle(EditorInput::Newline), EditOutcome::Changed);
906        assert_eq!(newline.text(), "j\n");
907        assert_eq!(newline.cursor(), Cursor::new(1, 0));
908
909        let mut escape = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
910        let _ = escape.handle(EditorInput::Insert);
911        let _ = escape.handle(EditorInput::Character('j'));
912        assert_eq!(escape.handle(EditorInput::Escape), EditOutcome::ModeChanged);
913        assert_eq!(escape.text(), "j");
914        assert_eq!(escape.mode(), Mode::Normal);
915        assert_eq!(escape.cursor(), Cursor::new(0, 0));
916    }
917
918    #[test]
919    fn insert_escape_can_be_disabled_or_replaced_for_literal_jj() {
920        let mut literal = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0))
921            .with_insert_escape_sequence(InsertEscapeSequence::disabled());
922        let _ = literal.handle(EditorInput::Insert);
923        let _ = literal.handle(EditorInput::Character('j'));
924        let _ = literal.handle(EditorInput::Character('j'));
925        assert_eq!(literal.text(), "jj");
926        assert_eq!(literal.mode(), Mode::Insert);
927
928        let sequence = InsertEscapeSequence::new("jk")
929            .unwrap_or_else(|error| panic!("valid sequence: {error}"));
930        let mut replaced = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0))
931            .with_insert_escape_sequence(sequence);
932        let _ = replaced.handle(EditorInput::Insert);
933        let _ = replaced.handle(EditorInput::Character('j'));
934        let _ = replaced.handle(EditorInput::Character('j'));
935        assert_eq!(replaced.text(), "jj");
936        assert!(replaced.flush_pending_input());
937        let _ = replaced.handle(EditorInput::Character('j'));
938        assert_eq!(
939            replaced.handle(EditorInput::Character('k')),
940            EditOutcome::ModeChanged
941        );
942        assert_eq!(replaced.text(), "jj");
943        assert_eq!(replaced.mode(), Mode::Normal);
944
945        let mut reconfigured = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
946        let _ = reconfigured.handle(EditorInput::Insert);
947        let _ = reconfigured.handle(EditorInput::Character('j'));
948        assert!(reconfigured.has_pending_input());
949        reconfigured.set_insert_escape_sequence(InsertEscapeSequence::disabled());
950        assert_eq!(reconfigured.text(), "j");
951        assert!(!reconfigured.has_pending_input());
952        let _ = reconfigured.handle(EditorInput::Character('j'));
953        assert_eq!(reconfigured.text(), "jj");
954        assert_eq!(reconfigured.mode(), Mode::Insert);
955    }
956
957    #[test]
958    fn insert_escape_respects_byte_limits_and_unicode_sequences() {
959        let mut full =
960            EditableBuffer::with_byte_limit("x", Viewport::new(0, 0, 2, 20, 0), "x".len());
961        let _ = full.handle(EditorInput::AppendLineEnd);
962        assert_eq!(
963            full.handle(EditorInput::Character('j')),
964            EditOutcome::Ignored
965        );
966        assert!(full.has_pending_input());
967        assert_eq!(
968            full.handle(EditorInput::Character('j')),
969            EditOutcome::ModeChanged
970        );
971        assert_eq!(full.text(), "x");
972        assert_eq!(full.mode(), Mode::Normal);
973
974        let sequence = InsertEscapeSequence::new("界界")
975            .unwrap_or_else(|error| panic!("valid Unicode sequence: {error}"));
976        let mut unicode = EditableBuffer::new("a", Viewport::new(0, 0, 2, 20, 0))
977            .with_insert_escape_sequence(sequence);
978        let _ = unicode.handle(EditorInput::AppendLineEnd);
979        let _ = unicode.handle(EditorInput::Character('界'));
980        assert_eq!(unicode.text(), "a界");
981        assert_eq!(
982            unicode.handle(EditorInput::Character('界')),
983            EditOutcome::ModeChanged
984        );
985        assert_eq!(unicode.text(), "a");
986        assert_eq!(unicode.cursor(), Cursor::new(0, 0));
987
988        assert!(InsertEscapeSequence::new("").is_err());
989        assert!(InsertEscapeSequence::new("j\nj").is_err());
990    }
991}