Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
CHANGELOG
=========

Unreleased
----------

New features:
- Support ``r`` to replace characters in Vi character, line, and block selections,
preserving line endings.

3.0.53: 2026-07-26
------------------

Expand Down
10 changes: 10 additions & 0 deletions docs/pages/advanced_topics/key_bindings.rst
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,16 @@ the `record_in_macro` parameter to `False`:
pass


Replacing a Vi selection
------------------------

In Vi mode, select text with ``v`` (characters), ``V`` (lines), or ``Control-V``
(a rectangular block), then press ``r`` followed by a character. This replaces
each selected character with that character, preserving line endings. The
selection ends and the cursor moves to its beginning. Press ``Escape`` after
``r`` to cancel without changing the text.


Creating new Vi text objects and operators
------------------------------------------

Expand Down
23 changes: 23 additions & 0 deletions src/prompt_toolkit/key_binding/bindings/vi.py
Original file line number Diff line number Diff line change
Expand Up @@ -449,6 +449,7 @@ def load_vi_bindings() -> KeyBindingsBase:
handle("c-v", filter=vi_insert_mode)(get_by_name("quoted-insert"))

@handle("escape")
@handle("r", "escape", filter=vi_selection_mode)
def _back_to_navigation(event: E) -> None:
"""
Escape goes to vi navigation mode.
Expand Down Expand Up @@ -827,6 +828,28 @@ def _replace(event: E) -> None:
"""
event.app.vi_state.input_mode = InputMode.REPLACE_SINGLE

@handle("r", Keys.Any, filter=vi_selection_mode)
def _replace_selection(event: E) -> None:
"""
Replace every selected character, except for line endings.
"""
# Ignore keys like arrows, whose data contains an escape sequence.
if len(event.data) != 1:
return

buff = event.current_buffer
document = buff.document
ranges = list(document.selection_ranges())
text = list(document.text)

for start, end in ranges:
text[start:end] = [
c if c == "\n" else event.data for c in document.text[start:end]
]

buff.document = Document("".join(text), cursor_position=ranges[0][0])
buff.exit_selection()

@handle("R", filter=vi_navigation_mode)
def _replace_mode(event: E) -> None:
"""
Expand Down
102 changes: 102 additions & 0 deletions tests/test_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -667,6 +667,108 @@ def test_vi_digraphs():
assert result.text == "helloy"


@pytest.mark.parametrize(
"text, selection, replacement, expected, cursor",
[
("hello", "vll", "#", "###lo", 0),
("hello", "$vhh", "#", "he###", 2),
("hello", "lv", "#", "h#llo", 1),
("abcde\n\nfghij", "lvjjll", "#", "a####\n\n####j", 1),
("abcde\n\nfghij", "jjlllvkkhh", "#", "a####\n\n####j", 1),
("a\nbc\n\ndef", "jVj", "#", "a\n##\n\ndef", 2),
("a\nbc\n\ndef", "jjjVk", "#", "a\nbc\n\n###", 5),
("abc\ndef\n", "jVj", "#", "abc\n###\n", 4),
("abcde\nx\n\nfghij", "ll\x16jjjl", "#", "ab##e\nx\n\nfg##j", 2),
("abcde\nx\n\nfghij", "jjjlll\x16kkkh", "#", "ab##e\nx\n\nfg##j", 2),
("abcde\nx\n\nfghij", "lll\x16jjjh", "#", "ab##e\nx\n\nfg##j", 2),
("\n\n\n", "\x16jj", "#", "\n\n\n", 0),
("", "v", "#", "", 0),
("", "V", "#", "", 0),
("", "\x16", "#", "", 0),
("###", "vll", "#", "###", 0),
("a\tb", "vll", "#", "###", 0),
("hello", "lvll", "界", "h界界界o", 1),
("hello", "lvll", "\\", "h\\\\\\o", 1),
],
)
def test_vi_replace_selection(text, selection, replacement, expected, cursor):
bindings = KeyBindings()
clipboard = InMemoryClipboard(ClipboardData("clipboard text"))

@bindings.add("c-q")
def finish(event):
# Finish without Escape so that we can check that replacement exits
# selection mode, even when the text did not change.
event.app.exit()

result, cli = _feed_cli_with_input(
text.replace("\n", "\r").replace("\t", "\x16\t")
+ "\x1bgg"
+ selection
+ "r"
+ replacement
+ "\x11",
editing_mode=EditingMode.VI,
multiline=True,
clipboard=clipboard,
key_bindings=bindings,
check_line_ending=False,
)
assert result.text == expected
assert result.cursor_position == cursor
assert cli.current_buffer.selection_state is None
assert clipboard.get_data().text == "clipboard text"


@pytest.mark.parametrize("selection", ["vjl", "Vj", "\x16jl"])
def test_vi_replace_selection_undo(selection):
result, cli = _feed_cli_with_input(
"abc\rdef\x1bgg" + selection + "r#u\x1b\r",
editing_mode=EditingMode.VI,
multiline=True,
)
assert result.text == "abc\ndef"


@pytest.mark.parametrize("selection", ["vll", "V", "\x16ll"])
def test_vi_replace_selection_cancel(selection):
result, cli = _feed_cli_with_input(
"hello\x1bgg" + selection + "r\x1b\r",
editing_mode=EditingMode.VI,
)
assert result.text == "hello"
assert cli.current_buffer.selection_state is None


def test_vi_replace_selection_read_only():
bindings = KeyBindings()

@bindings.add("c-o")
def make_read_only(event):
event.current_buffer.read_only = lambda: True

result, cli = _feed_cli_with_input(
"hello\x1bggvll\x0fr#\x1b\r",
editing_mode=EditingMode.VI,
key_bindings=bindings,
)
assert result.text == "hello"


@pytest.mark.parametrize("key", ["\x1b[D", "\x1b[3~"])
def test_vi_replace_selection_special_key(key):
result, cli = _feed_cli_with_input(
"hello\x1bggvllr" + key + "\x1b\r", editing_mode=EditingMode.VI
)
assert result.text == "hello"


def test_vi_replace_single():
result, cli = _feed_cli_with_input("hello\x1bggr#\r", editing_mode=EditingMode.VI)
assert result.text == "#ello"
assert result.cursor_position == 0


def test_vi_block_editing():
"Test Vi Control-V style block insertion."
feed = partial(_feed_cli_with_input, editing_mode=EditingMode.VI, multiline=True)
Expand Down
Loading