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(OpenLinePlacement::Below),
399            EditorInput::OpenAbove => self.open_line(OpenLinePlacement::Above),
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, placement: OpenLinePlacement) -> 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 placement == OpenLinePlacement::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
643#[derive(Clone, Copy, Debug, Eq, PartialEq)]
644enum OpenLinePlacement {
645    Above,
646    Below,
647}
648
649fn previous_boundary(line: &str, byte_column: usize) -> usize {
650    let end = byte_column.min(line.len());
651    line[..end]
652        .char_indices()
653        .next_back()
654        .map_or(0, |(column, _)| column)
655}
656
657fn next_boundary(line: &str, byte_column: usize) -> usize {
658    let start = byte_column.min(line.len());
659    line[start..].chars().next().map_or(start, |character| {
660        start.saturating_add(character.len_utf8())
661    })
662}
663
664#[cfg(test)]
665mod tests {
666    use super::{EditOutcome, EditableBuffer, EditorInput, InsertEscapeSequence, Mode};
667    use crate::{Cursor, Motion, MotionKind, Viewport};
668
669    #[test]
670    fn selecting_a_cursor_resets_the_column_for_vertical_motion() {
671        let mut buffer = EditableBuffer::new("abcdef\nx\nabcdef", Viewport::new(0, 0, 3, 20, 0));
672        buffer.set_cursor(Cursor::new(0, 4));
673        let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
674        buffer.set_cursor(Cursor::new(1, 0));
675        let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
676        assert_eq!(buffer.cursor(), Cursor::new(2, 0));
677    }
678
679    #[test]
680    fn leaving_insert_mode_resets_the_column_for_vertical_motion() {
681        for escape in [EditorInput::Escape, EditorInput::Character('j')] {
682            let mut buffer = EditableBuffer::new("abcdef\nabcdef", Viewport::new(0, 0, 2, 20, 0));
683            let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::LineEnd)));
684            let _ = buffer.handle(EditorInput::InsertLineStart);
685            let _ = buffer.handle(EditorInput::Character('界'));
686            if escape == EditorInput::Character('j') {
687                let _ = buffer.handle(escape);
688            }
689            let _ = buffer.handle(escape);
690            let _ = buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Down)));
691            assert_eq!(buffer.cursor(), Cursor::new(1, 0), "{escape:?}");
692        }
693    }
694
695    #[test]
696    fn normal_insert_correction_newline_and_escape_preserve_content_and_cursor() {
697        let mut buffer = EditableBuffer::new("abcd", Viewport::new(0, 0, 4, 20, 0));
698        assert_eq!(
699            buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Right))),
700            EditOutcome::Moved
701        );
702        assert_eq!(buffer.handle(EditorInput::Insert), EditOutcome::ModeChanged);
703        assert_eq!(
704            buffer.handle(EditorInput::Character('x')),
705            EditOutcome::Changed
706        );
707        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
708        for character in "j3qQ".chars() {
709            assert_eq!(
710                buffer.handle(EditorInput::Character(character)),
711                EditOutcome::Changed
712            );
713        }
714        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
715        assert_eq!(
716            buffer.handle(EditorInput::Character('界')),
717            EditOutcome::Changed
718        );
719        assert_eq!(buffer.handle(EditorInput::Escape), EditOutcome::ModeChanged);
720
721        assert_eq!(buffer.mode(), Mode::Normal);
722        assert_eq!(buffer.text(), "aj3qQ\n界bcd");
723        assert_eq!(buffer.cursor(), Cursor::new(1, 0));
724    }
725
726    #[test]
727    fn insert_mode_treats_motion_letters_digits_and_quit_letters_as_text() {
728        let mut buffer = EditableBuffer::new("", Viewport::new(0, 0, 2, 10, 0));
729        assert_eq!(buffer.handle(EditorInput::Insert), EditOutcome::ModeChanged);
730        for character in "jk123qQ".chars() {
731            let _ = buffer.handle(EditorInput::Character(character));
732        }
733        assert_eq!(buffer.text(), "jk123qQ");
734        assert_eq!(buffer.handle(EditorInput::Escape), EditOutcome::ModeChanged);
735        assert_eq!(buffer.cursor(), Cursor::new(0, 6));
736    }
737
738    #[test]
739    fn byte_limit_and_unicode_corrections_keep_boundaries() {
740        let mut buffer =
741            EditableBuffer::with_byte_limit("界", Viewport::new(0, 0, 2, 10, 0), "界x".len());
742        let _ = buffer.handle(EditorInput::AppendLineEnd);
743        assert_eq!(
744            buffer.handle(EditorInput::Character('x')),
745            EditOutcome::Changed
746        );
747        assert_eq!(
748            buffer.handle(EditorInput::Character('y')),
749            EditOutcome::Ignored
750        );
751        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
752        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
753        assert_eq!(buffer.text(), "");
754        assert_eq!(buffer.cursor(), Cursor::new(0, 0));
755    }
756
757    #[test]
758    fn line_joining_corrections_are_symmetric() {
759        let mut buffer = EditableBuffer::new("one\ntwo", Viewport::new(0, 0, 3, 20, 0));
760        buffer.set_cursor(Cursor::new(1, 0));
761        let _ = buffer.handle(EditorInput::Insert);
762        assert_eq!(buffer.handle(EditorInput::Backspace), EditOutcome::Changed);
763        assert_eq!(buffer.text(), "onetwo");
764        assert_eq!(buffer.cursor(), Cursor::new(0, 3));
765
766        let _ = buffer.handle(EditorInput::Newline);
767        let _ = buffer.handle(EditorInput::Escape);
768        buffer.set_cursor(Cursor::new(0, 2));
769        let _ = buffer.handle(EditorInput::AppendLineEnd);
770        assert_eq!(buffer.handle(EditorInput::Delete), EditOutcome::Changed);
771        assert_eq!(buffer.text(), "onetwo");
772    }
773
774    #[test]
775    fn new_lines_respect_the_byte_limit() {
776        let mut buffer =
777            EditableBuffer::with_byte_limit("one", Viewport::new(0, 0, 3, 20, 0), "one".len());
778        assert_eq!(buffer.handle(EditorInput::OpenBelow), EditOutcome::Ignored);
779        assert_eq!(buffer.handle(EditorInput::OpenAbove), EditOutcome::Ignored);
780
781        let _ = buffer.handle(EditorInput::AppendLineEnd);
782        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Ignored);
783        assert_eq!(buffer.text(), "one");
784    }
785
786    #[test]
787    fn insert_cursor_stays_visible_and_line_separators_use_newline_input() {
788        let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 1, 2, 0));
789        let _ = buffer.handle(EditorInput::AppendLineEnd);
790        assert_eq!(
791            buffer.handle(EditorInput::Character('\n')),
792            EditOutcome::Ignored
793        );
794        assert_eq!(
795            buffer.handle(EditorInput::Character('\r')),
796            EditOutcome::Ignored
797        );
798        assert_eq!(buffer.text(), "ab");
799
800        assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
801        assert_eq!(buffer.cursor(), Cursor::new(1, 0));
802        assert_eq!(buffer.viewport().top(), 1);
803
804        assert_eq!(
805            buffer.handle(EditorInput::Character('界')),
806            EditOutcome::Changed
807        );
808        assert_eq!(buffer.viewport().left(), 1);
809        assert_eq!(buffer.text(), "ab\n界");
810    }
811
812    #[test]
813    fn default_jj_returns_to_normal_without_inserting_the_sequence() {
814        let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
815        let mut escaped = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
816        assert_eq!(
817            buffer.handle(EditorInput::AppendLineEnd),
818            EditOutcome::ModeChanged
819        );
820        let _ = escaped.handle(EditorInput::AppendLineEnd);
821        let _ = escaped.handle(EditorInput::Escape);
822        assert_eq!(
823            buffer.handle(EditorInput::Character('j')),
824            EditOutcome::Changed
825        );
826        assert_eq!(buffer.text(), "abj");
827        assert!(buffer.has_pending_input());
828
829        assert_eq!(
830            buffer.handle(EditorInput::Character('j')),
831            EditOutcome::ModeChanged
832        );
833        assert_eq!(buffer.text(), "ab");
834        assert_eq!(buffer.mode(), Mode::Normal);
835        assert_eq!(buffer.cursor(), Cursor::new(0, 1));
836        assert_eq!(buffer.text(), escaped.text());
837        assert_eq!(buffer.cursor(), escaped.cursor());
838        assert_eq!(buffer.viewport(), escaped.viewport());
839        assert!(!buffer.has_pending_input());
840    }
841
842    #[test]
843    fn lone_j_mismatch_and_context_flush_keep_literal_input_in_order() {
844        let mut buffer = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
845        let _ = buffer.handle(EditorInput::Insert);
846        assert_eq!(
847            buffer.handle(EditorInput::Character('j')),
848            EditOutcome::Changed
849        );
850        assert_eq!(buffer.text(), "j");
851        assert!(buffer.has_pending_input());
852
853        assert_eq!(
854            buffer.handle(EditorInput::Character('界')),
855            EditOutcome::Changed
856        );
857        assert_eq!(buffer.text(), "j界");
858        assert!(!buffer.has_pending_input());
859
860        let _ = buffer.handle(EditorInput::Character('j'));
861        assert!(buffer.flush_pending_input());
862        assert_eq!(buffer.text(), "j界j");
863        assert!(!buffer.flush_pending_input());
864
865        let _ = buffer.handle(EditorInput::Character('j'));
866        buffer.set_cursor(Cursor::new(0, 0));
867        assert_eq!(buffer.text(), "j界jj");
868        assert!(!buffer.has_pending_input());
869
870        let _ = buffer.handle(EditorInput::Character('j'));
871        let before_context_input = buffer.text();
872        assert_eq!(
873            buffer.handle(EditorInput::Motion(Motion::new(MotionKind::Right))),
874            EditOutcome::Ignored
875        );
876        assert_eq!(buffer.text(), before_context_input);
877        assert!(!buffer.has_pending_input());
878
879        let _ = buffer.handle(EditorInput::Character('j'));
880        let before_invalid_character = buffer.text();
881        assert_eq!(
882            buffer.handle(EditorInput::Character('\n')),
883            EditOutcome::Ignored
884        );
885        assert_eq!(buffer.text(), before_invalid_character);
886        assert!(!buffer.has_pending_input());
887    }
888
889    #[test]
890    fn editing_keys_after_j_observe_the_inserted_prefix() {
891        let mut backspace = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
892        let _ = backspace.handle(EditorInput::Insert);
893        let _ = backspace.handle(EditorInput::Character('j'));
894        assert_eq!(
895            backspace.handle(EditorInput::Backspace),
896            EditOutcome::Changed
897        );
898        assert_eq!(backspace.text(), "ab");
899        assert_eq!(backspace.cursor(), Cursor::new(0, 0));
900
901        let mut delete = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
902        let _ = delete.handle(EditorInput::Insert);
903        let _ = delete.handle(EditorInput::Character('j'));
904        assert_eq!(delete.handle(EditorInput::Delete), EditOutcome::Changed);
905        assert_eq!(delete.text(), "jb");
906        assert_eq!(delete.cursor(), Cursor::new(0, 1));
907
908        let mut newline = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
909        let _ = newline.handle(EditorInput::Insert);
910        let _ = newline.handle(EditorInput::Character('j'));
911        assert_eq!(newline.handle(EditorInput::Newline), EditOutcome::Changed);
912        assert_eq!(newline.text(), "j\n");
913        assert_eq!(newline.cursor(), Cursor::new(1, 0));
914
915        let mut escape = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
916        let _ = escape.handle(EditorInput::Insert);
917        let _ = escape.handle(EditorInput::Character('j'));
918        assert_eq!(escape.handle(EditorInput::Escape), EditOutcome::ModeChanged);
919        assert_eq!(escape.text(), "j");
920        assert_eq!(escape.mode(), Mode::Normal);
921        assert_eq!(escape.cursor(), Cursor::new(0, 0));
922    }
923
924    #[test]
925    fn insert_escape_can_be_disabled_or_replaced_for_literal_jj() {
926        let mut literal = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0))
927            .with_insert_escape_sequence(InsertEscapeSequence::disabled());
928        let _ = literal.handle(EditorInput::Insert);
929        let _ = literal.handle(EditorInput::Character('j'));
930        let _ = literal.handle(EditorInput::Character('j'));
931        assert_eq!(literal.text(), "jj");
932        assert_eq!(literal.mode(), Mode::Insert);
933
934        let sequence = InsertEscapeSequence::new("jk")
935            .unwrap_or_else(|error| panic!("valid sequence: {error}"));
936        let mut replaced = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0))
937            .with_insert_escape_sequence(sequence);
938        let _ = replaced.handle(EditorInput::Insert);
939        let _ = replaced.handle(EditorInput::Character('j'));
940        let _ = replaced.handle(EditorInput::Character('j'));
941        assert_eq!(replaced.text(), "jj");
942        assert!(replaced.flush_pending_input());
943        let _ = replaced.handle(EditorInput::Character('j'));
944        assert_eq!(
945            replaced.handle(EditorInput::Character('k')),
946            EditOutcome::ModeChanged
947        );
948        assert_eq!(replaced.text(), "jj");
949        assert_eq!(replaced.mode(), Mode::Normal);
950
951        let mut reconfigured = EditableBuffer::new("", Viewport::new(0, 0, 2, 20, 0));
952        let _ = reconfigured.handle(EditorInput::Insert);
953        let _ = reconfigured.handle(EditorInput::Character('j'));
954        assert!(reconfigured.has_pending_input());
955        reconfigured.set_insert_escape_sequence(InsertEscapeSequence::disabled());
956        assert_eq!(reconfigured.text(), "j");
957        assert!(!reconfigured.has_pending_input());
958        let _ = reconfigured.handle(EditorInput::Character('j'));
959        assert_eq!(reconfigured.text(), "jj");
960        assert_eq!(reconfigured.mode(), Mode::Insert);
961    }
962
963    #[test]
964    fn insert_escape_respects_byte_limits_and_unicode_sequences() {
965        let mut full =
966            EditableBuffer::with_byte_limit("x", Viewport::new(0, 0, 2, 20, 0), "x".len());
967        let _ = full.handle(EditorInput::AppendLineEnd);
968        assert_eq!(
969            full.handle(EditorInput::Character('j')),
970            EditOutcome::Ignored
971        );
972        assert!(full.has_pending_input());
973        assert_eq!(
974            full.handle(EditorInput::Character('j')),
975            EditOutcome::ModeChanged
976        );
977        assert_eq!(full.text(), "x");
978        assert_eq!(full.mode(), Mode::Normal);
979
980        let sequence = InsertEscapeSequence::new("界界")
981            .unwrap_or_else(|error| panic!("valid Unicode sequence: {error}"));
982        let mut unicode = EditableBuffer::new("a", Viewport::new(0, 0, 2, 20, 0))
983            .with_insert_escape_sequence(sequence);
984        let _ = unicode.handle(EditorInput::AppendLineEnd);
985        let _ = unicode.handle(EditorInput::Character('界'));
986        assert_eq!(unicode.text(), "a界");
987        assert_eq!(
988            unicode.handle(EditorInput::Character('界')),
989            EditOutcome::ModeChanged
990        );
991        assert_eq!(unicode.text(), "a");
992        assert_eq!(unicode.cursor(), Cursor::new(0, 0));
993
994        assert!(InsertEscapeSequence::new("").is_err());
995        assert!(InsertEscapeSequence::new("j\nj").is_err());
996    }
997}