Browse Source

doc: port prompt-buffer section (#14342)

[skip ci]

Changes from original include:
- "See |terminal-window|" -> "See |terminal|".
- Remove mention of using CTRL-W window commands in insert mode.
- Converted usage example to use the Nvim job and channel API.
- Removed logging from usage example, as ch_logfile() has no direct Nvim
- Fixed some small grammar/spelling mistakes.
Sean Dewar 3 weeks ago
committed by GitHub
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
  1. 77


@ -174,4 +174,81 @@ Put this in `uppercase.vim` and run: >
nvim --headless --cmd "source uppercase.vim"
5. Using a prompt buffer *prompt-buffer*
If you want to type input for the job in a Vim window you have a few options:
- Use a normal buffer and handle all possible commands yourself.
This will be complicated, since there are so many possible commands.
- Use a terminal window. This works well if what you type goes directly to
the job and the job output is directly displayed in the window.
See |terminal|.
- Use a window with a prompt buffer. This works well when entering a line for
the job in Vim while displaying (possibly filtered) output from the job.
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 one line of text at the very last line of the
buffer. When pressing Enter in the prompt line the callback set with
|prompt_setcallback()| is invoked. 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 in the last line, after the 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
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
can start typing a line.
The text of the prompt can be set with the |prompt_setprompt()| function. If
no prompt is set with |prompt_setprompt()|, "% " is used. You can get the
effective prompt text for a buffer, with |prompt_getprompt()|.
The user can go to Normal mode and navigate through the buffer. This can be
useful to see older output or copy text.
Any command that starts Insert mode, such as "a", "i", "A" and "I", will move
the cursor to the last line. "A" will move to the end of the line, "I" to the
start of the line.
Here is an example for Unix. It starts a shell in the background and prompts
for the next shell command. Output from the shell is displayed above the
prompt. >
" Function handling a line of text that has been typed.
func TextEntered(text)
" Send the text to a shell with Enter appended.
call chansend(g:shell_job, [a:text, ''])
" Function handling output from the shell: Added above the prompt.
func GotOutput(channel, msg, name)
call append(line("$") - 1, a:msg)
" Function handling the shell exit: close the window.
func JobExit(job, status, event)
" Start a shell in the background.
let shell_job = jobstart(["/bin/sh"], #{
\ on_stdout: function('GotOutput'),
\ on_stderr: function('GotOutput'),
\ on_exit: function('JobExit'),
\ })
set buftype=prompt
let buf = bufnr('')
call prompt_setcallback(buf, function("TextEntered"))
call prompt_setprompt(buf, "shell command: ")
" start accepting shell commands