commit cb2367a1e25da6cef77cb164f404ec814a98482b
parent c8e54bf49d1950ab7de12c5ce82882bef4d0f508
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 15 Jun 2025 01:01:55 +0200
docs: api, misc
Diffstat:
10 files changed, 41 insertions(+), 43 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -2222,7 +2222,7 @@ whether a buffer is loaded.
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
- Activates buffer-update events on a channel, or as Lua callbacks.
+ Activates |api-buffer-updates| events on a channel, or as Lua callbacks.
Example (Lua): capture buffer updates in a global `events` variable (use
"vim.print(events)" to see its contents): >lua
@@ -2875,7 +2875,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
• hl_eol : when true, for a multiline highlight covering the
EOL of a line, continue the highlight for the rest of the
screen line (just like for diff and cursorline highlight).
- • virt_text : virtual text to link to this mark. A list of
+ • virt_text : *virtual-text* to link to this mark. A list of
`[text, highlight]` tuples, each representing a text chunk
with specified highlight. `highlight` element can either
be a single highlight group, or an array of multiple
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
@@ -189,17 +189,17 @@ If you want to type input for the job in a Vim window you have a few options:
A prompt buffer is created by setting 'buftype' to "prompt". You would
normally only do that in a newly created buffer.
-The user can edit and enter text at the very last line of the buffer. When
-pressing Enter in the prompt line the callback set with |prompt_setcallback()|
-is invoked. To enter multiple lines user can use Shift+Enter that'd add a new
-line. The final Enter submits the lines to |prompt_setcallback()|. It would
-normally send the line to a job. Another callback would receive the output
-from the job and display it in the buffer, below the prompt (and above the
-next prompt).
-
-Only the text after the last prompt, is editable. The rest of the buffer is
-not modifiable with Normal mode commands. It can be modified by calling
-functions, such as |append()|. Using other commands may mess up the buffer.
+The user can edit and enter text at the very last line of the buffer. Pressing
+Enter in the prompt line invokes the |prompt_setcallback()| callback. Use
+Shift+Enter to add a new line without submitting the prompt, or paste
+multiline text using any |put| or |paste| command. The callback is typically
+expected to process the prompt and show results by appending to the buffer,
+below the prompt (and above the next prompt).
+
+Only the text after the last prompt (starting from the |':| mark), is
+user-editable. The rest of the buffer is not modifiable with Normal mode
+commands. It can be modified by functions such as |append()|. Using other
+commands may mess up the buffer.
After setting 'buftype' to "prompt" Vim does not automatically start Insert
mode, use `:startinsert` if you want to enter Insert mode, so that the user
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
@@ -795,14 +795,6 @@ m< or m> Set the |'<| or |'>| mark. Useful to change what the
Note that the Visual mode cannot be set, only the
start and end position.
- *m:*
-m: Special mark for prompt buffers. It always shows the
- line where current prompt starts. Text from this line
- and below will be submitted when user submits.
- Note: This mark is readonly. You can not modify it's
- location. Also this mark is unique to prompt buffers as
- a result not available in regular buffers.
-
*:ma* *:mark* *E191*
:[range]ma[rk] {a-zA-Z'}
Set mark {a-zA-Z'} at last line number in [range],
@@ -950,6 +942,11 @@ was made yet in the current file.
the position will be on the last character.
To jump to older changes use |g;|.
+ *':* *`:*
+': In a prompt buffer, the start of the current prompt.
+ Text from this line until end of buffer will be
+ submitted when the user submits the prompt.
+
*'(* *`(*
'( `( To the start of the current sentence, like the |(|
command.
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
@@ -18,6 +18,10 @@ BREAKING CHANGES IN HEAD OR EXPERIMENTAL *news-breaking-dev*
The following changes to UNRELEASED features were made during the development
cycle (Nvim HEAD, the "master" branch).
+EVENTS
+
+• Renamed "nvim.find_exrc" |default-autocmds| group to "nvim.exrc".
+
EXPERIMENTS
• todo
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
@@ -210,7 +210,7 @@ nvim.swapfile:
swapfile is owned by a running Nvim process. Shows |W325| "Ignoring
swapfile…" message.
-nvim.find_exrc:
+nvim.exrc:
- VimEnter: Extend 'exrc' to also search for project-local configuration files
in all parent directories.
@@ -304,6 +304,10 @@ Commands:
User commands can support |:command-preview| to show results as you type
- |:write| with "++p" flag creates parent directories.
+Editor:
+- |prompt-buffer| supports multiline input/paste, undo/redo, and o/O normal
+ commands.
+
Events (autocommands):
- Fixed inconsistent behavior in execution of nested autocommands #23368
- |RecordingEnter|
@@ -472,12 +476,6 @@ Variables:
instead of always being strings. |v:option_old| is now the old global value
for all global-local options, instead of just string global-local options.
-Prompt-Buffer:
-- supports multiline inputs.
-- supports multiline paste.
-- supports undo/redo on current prompt.
-- supports normal o/O operations.
-
Vimscript:
- |:redir| nested in |execute()| works.
diff --git a/runtime/lua/vim/_defaults.lua b/runtime/lua/vim/_defaults.lua
@@ -935,7 +935,7 @@ do
end
vim.api.nvim_create_autocmd('VimEnter', {
- group = vim.api.nvim_create_augroup('nvim.find_exrc', {}),
+ group = vim.api.nvim_create_augroup('nvim.exrc', {}),
desc = 'Find exrc files in parent directories',
callback = function()
if not vim.o.exrc then
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
@@ -159,7 +159,7 @@ function vim.api.nvim__unpack(str) end
--- @return integer
function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end
---- Activates buffer-update events on a channel, or as Lua callbacks.
+--- Activates `api-buffer-updates` events on a channel, or as Lua callbacks.
---
--- Example (Lua): capture buffer updates in a global `events` variable
--- (use "vim.print(events)" to see its contents):
@@ -575,7 +575,7 @@ function vim.api.nvim_buf_line_count(buffer) end
--- EOL of a line, continue the highlight for the rest
--- of the screen line (just like for diff and
--- cursorline highlight).
---- - virt_text : virtual text to link to this mark.
+--- - virt_text : [](virtual-text) to link to this mark.
--- A list of `[text, highlight]` tuples, each representing a
--- text chunk with specified highlight. `highlight` element
--- can either be a single highlight group, or an array of
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
@@ -87,7 +87,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
return buf->b_ml.ml_line_count;
}
-/// Activates buffer-update events on a channel, or as Lua callbacks.
+/// Activates |api-buffer-updates| events on a channel, or as Lua callbacks.
///
/// Example (Lua): capture buffer updates in a global `events` variable
/// (use "vim.print(events)" to see its contents):
diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
@@ -407,7 +407,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
/// EOL of a line, continue the highlight for the rest
/// of the screen line (just like for diff and
/// cursorline highlight).
-/// - virt_text : virtual text to link to this mark.
+/// - virt_text : [](virtual-text) to link to this mark.
/// A list of `[text, highlight]` tuples, each representing a
/// text chunk with specified highlight. `highlight` element
/// can either be a single highlight group, or an array of
diff --git a/test/functional/legacy/prompt_buffer_spec.lua b/test/functional/legacy/prompt_buffer_spec.lua
@@ -247,7 +247,7 @@ describe('prompt buffer', function()
Close]])
end)
- it('can insert mutli line text', function()
+ it('can insert multiline text', function()
source_script()
feed('line 1<s-cr>line 2<s-cr>line 3')
screen:expect([[
@@ -275,7 +275,7 @@ describe('prompt buffer', function()
]])
end)
- it('can paste multiline text', function()
+ it('can put (p) multiline text', function()
source_script()
fn('setreg', 'a', 'line 1\nline 2\nline 3')
feed('<esc>"ap')
@@ -302,7 +302,7 @@ describe('prompt buffer', function()
]])
end)
- it('undo works for current prompt', function()
+ it('can undo current prompt', function()
source_script()
-- text editiing alowed in current prompt
feed('tests-initial<esc>')
@@ -507,19 +507,18 @@ describe('prompt buffer', function()
]])
end)
- it(': mark follows current prompt', function()
+ it("sets the ': mark", function()
source_script()
feed('asdf')
eq({ 1, 1 }, api.nvim_buf_get_mark(0, ':'))
feed('<cr>')
eq({ 3, 1 }, api.nvim_buf_get_mark(0, ':'))
- end)
+ -- Multiline prompt.
+ feed('<s-cr>line1<s-cr>line2<s-cr>line3<cr>')
+ eq({ 11, 1 }, api.nvim_buf_get_mark(0, ':'))
- it(': mark only available in prompt buffer', function()
- source_script()
- feed('asdf')
- eq({ 1, 1 }, api.nvim_buf_get_mark(0, ':'))
+ -- ': mark is only available in prompt buffer.
source('set buftype=')
- eq(false, pcall(api.nvim_buf_get_mark, 0, ':'))
+ eq("Invalid mark name: ':'", t.pcall_err(api.nvim_buf_get_mark, 0, ':'))
end)
end)
