commit f8d01904915a0d3f5911c4b0c6ff64d040c3f0d6
parent 10b610bbd93a1e987dd39f406635820c794b0c3c
Author: Phạm Bình An <111893501+brianhuster@users.noreply.github.com>
Date: Tue, 30 Dec 2025 15:57:35 +0700
docs(prompt): Lua example, adjust for multiline input #37121
Diffstat:
2 files changed, 46 insertions(+), 43 deletions(-)
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
@@ -186,16 +186,16 @@ normally only do that in a newly created buffer: >vim
:set buftype=prompt
-The user can edit and enter text at the end of the buffer. Pressing Enter in
-the prompt section invokes the |prompt_setcallback()| callback, which is
+The user can edit and input text at the end of the buffer. Pressing Enter in
+the input section invokes the |prompt_setcallback()| callback, which is
typically expected to process the prompt and show results by appending to the
-buffer. To input multiline text, use Shift+Enter to add a new line without
+buffer. To input multiline text, use Shift-<Enter> to add a new line without
submitting the prompt, or just |put| or |paste| multiline text.
-Only the "prompt" part of the buffer user-editable, given by the |':| mark.
-The rest of the buffer is not modifiable with Normal mode commands, though it
-can be modified by functions such as |append()|. Using other commands may
-mess up the buffer.
+Only the section starting with the mark |':| of the buffer (after the prompt)
+is editable. The rest of the buffer is not modifiable with Normal mode
+commands, though it can be modified by functions such as |append()|. Using
+other commands may mess up the buffer.
After setting `buftype=prompt`:
- Nvim unsets the 'comments' option.
@@ -218,40 +218,43 @@ the cursor to the last line. "A" will move to the end of the line, "I" to the
start of the line.
Example: start a shell in the background and prompt for the next shell
-command, displaying shell output above the prompt: >vim
-
- " Handles a line of user input.
- func OnSubmit(text)
- " Send the text to a shell with Enter appended.
- call chansend(g:shell_job, [a:text, ''])
- endfunc
-
- " Handles output from the shell.
- func OnOutput(channel, msg, name)
- " Add shell output above the prompt.
- call append(line('$') - 1, a:msg)
- endfunc
-
- " Handles the shell exit.
- func JobExit(job, status, event)
- quit!
- endfunc
-
- " Start a shell in the background.
- let shell_job = jobstart(['/bin/sh'], #{
- \ on_stdout: function('OnOutput'),
- \ on_stderr: function('OnOutput'),
- \ on_exit: function('JobExit'),
- \ })
-
- new
- set buftype=prompt
- let buf = bufnr('')
- call prompt_setcallback(buf, function('OnSubmit'))
- call prompt_setprompt(buf, 'shell command: ')
-
- " Start accepting shell commands.
- startinsert
+command, displaying shell output above the prompt: >lua
+
+ local shell_job
+
+ -- Handles a line of user input.
+ local function on_submit(text)
+ -- Send the text to the shell with Enter appended.
+ vim.api.nvim_chan_send(shell_job, text .. "\n")
+ end
+
+ -- Handles output from the shell.
+ local function on_output(_, msg, _)
+ -- Add shell output above the prompt.
+ local input_start = vim.api.nvim_buf_get_mark(0, ":")[1]
+ vim.fn.append(input_start - 1, msg)
+ end
+
+ -- Handles the shell exit.
+ local function on_exit(_, _, _)
+ vim.cmd("quit!")
+ end
+
+ -- Start a shell in the background.
+ shell_job = vim.fn.jobstart({ "/bin/sh" }, {
+ on_stdout = on_output,
+ on_stderr = on_output,
+ on_exit = on_exit,
+ })
+
+ vim.cmd("new")
+ vim.bo.buftype = "prompt"
+ local buf = vim.api.nvim_get_current_buf()
+ vim.fn.prompt_setcallback(buf, on_submit)
+ vim.fn.prompt_setprompt(buf, "shell command: ")
+
+ -- Start accepting shell commands.
+ vim.cmd("startinsert")
<
vim:tw=78:ts=8:et:sw=4:ft=help:norl:
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
@@ -943,8 +943,8 @@ was made yet in the current file.
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
+': In a prompt buffer, the start of the current user
+ input. Text from this mark until end of buffer will be
submitted when the user submits the prompt.
*'(* *`(*
