From cb2367a1e25da6cef77cb164f404ec814a98482b Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 15 Jun 2025 01:01:55 +0200 Subject: [PATCH] docs: api, misc --- runtime/doc/api.txt | 4 ++-- runtime/doc/channel.txt | 20 +++++++++---------- runtime/doc/motion.txt | 13 +++++------- runtime/doc/news.txt | 4 ++++ runtime/doc/vim_diff.txt | 12 +++++------ runtime/lua/vim/_defaults.lua | 2 +- runtime/lua/vim/_meta/api.lua | 4 ++-- src/nvim/api/buffer.c | 2 +- src/nvim/api/extmark.c | 2 +- test/functional/legacy/prompt_buffer_spec.lua | 19 +++++++++--------- 10 files changed, 40 insertions(+), 42 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 92c774de2c..3a35d5dbec 100644 --- 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 index 28e4a70393..20d2aba625 100644 --- 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). +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, 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. +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 index b0d8569121..c5b59adc3c 100644 --- 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 index 8738e9f78a..6077cd691a 100644 --- 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 index e60e0a7901..995b415096 100644 --- 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 index aa3eb57254..496e49b340 100644 --- 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 index a86d52e620..6c4c4eaa07 100644 --- 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 index 2304d9d0cc..f6675435b7 100644 --- 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 index ee9d5d8067..0c454753ea 100644 --- 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 index 5a1c9d7c78..36d115c1e5 100644 --- 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 1line 2line 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('"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') @@ -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('') eq({ 3, 1 }, api.nvim_buf_get_mark(0, ':')) - end) + -- Multiline prompt. + feed('line1line2line3') + 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)