diff options
Diffstat (limited to 'runtime/doc/terminal.txt')
| -rw-r--r-- | runtime/doc/terminal.txt | 1443 |
1 files changed, 1443 insertions, 0 deletions
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt new file mode 100644 index 0000000..5885cb1 --- /dev/null +++ b/runtime/doc/terminal.txt @@ -0,0 +1,1443 @@ +*terminal.txt* For Vim version 8.2. Last change: 2021 Jan 04 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Terminal window support *terminal* *terminal-window* + + +The terminal feature is optional, use this to check if your Vim has it: > + echo has('terminal') +If the result is "1" you have it. + + +1. Basic use |terminal-use| + Typing |terminal-typing| + Size and color |terminal-size-color| + Command syntax |:terminal| + Resizing |terminal-resizing| + Terminal Modes |Terminal-mode| + Cursor style |terminal-cursor-style| + Session |terminal-session| + Special keys |terminal-special-keys| + Unix |terminal-unix| + MS-Windows |terminal-ms-windows| +2. Terminal functions |terminal-function-details| +3. Terminal communication |terminal-communication| + Vim to job: term_sendkeys() |terminal-to-job| + Job to Vim: JSON API |terminal-api| + Using the client-server feature |terminal-client-server| +4. Remote testing |terminal-testing| +5. Diffing screen dumps |terminal-diff| + Writing a screen dump test for Vim |terminal-dumptest| + Creating a screen dump |terminal-screendump| + Comparing screen dumps |terminal-diffscreendump| +6. Debugging |terminal-debug| + Starting |termdebug-starting| + Example session |termdebug-example| + Stepping through code |termdebug-stepping| + Inspecting variables |termdebug-variables| + Other commands |termdebug-commands| + Prompt mode |termdebug-prompt| + Communication |termdebug-communication| + Customizing |termdebug-customizing| + +{only available when compiled with the |+terminal| feature} +The terminal feature requires the |+job| and |+channel| features. + +============================================================================== +1. Basic use *terminal-use* + +This feature is for running a terminal emulator in a Vim window. A job can be +started connected to the terminal emulator. For example, to run a shell: > + :term bash + +Or to run build command: > + :term make myprogram + +The job runs asynchronously from Vim, the window will be updated to show +output from the job, also while editing in another window. + + +Typing ~ + *terminal-typing* +When the keyboard focus is in the terminal window, typed keys will be sent to +the job. This uses a pty when possible. You can click outside of the +terminal window to move keyboard focus elsewhere. + + *t_CTRL-W_CTRL-W* *t_CTRL-W_:* +CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: + CTRL-W CTRL-W move focus to the next window + CTRL-W : enter an Ex command +See |CTRL-W| for more commands. + +Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N* + CTRL-W . send a CTRL-W to the job in the terminal + CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal + CTRL-W N go to Terminal-Normal mode, see |Terminal-mode| + CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| + CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote* + Also works with the = register to insert the result of + evaluating an expression. + CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C| + CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt* + CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT* + +See option 'termwinkey' for specifying another key instead of CTRL-W that +will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey' +to the job. For example: + 'termwinkey' CTRL-W move focus to the next window + 'termwinkey' : enter an Ex command + 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal + 'termwinkey' . send 'termwinkey' to the job in the terminal + 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal + 'termwinkey' N go to terminal Normal mode, see below + 'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N| + 'termwinkey' CTRL-C same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C| + *t_CTRL-\_CTRL-N* +The special key combination CTRL-\ CTRL-N can be used to switch to Normal +mode, just like this works in any other mode. + *t_CTRL-W_CTRL-C* +CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a +CTRL-BREAK will also kill the job. + +If you type CTRL-C the effect depends on what the pty has been configured to +do. For simple commands this causes a SIGINT to be sent to the job, which +would end it. Other commands may ignore the SIGINT or handle the CTRL-C +themselves (like Vim does). + +To change the keys you type use terminal mode mappings, see |:tmap|. +These are defined like any mapping, but apply only when typing keys that are +sent to the job running in the terminal. For example, to make F1 switch +to Terminal-Normal mode: > + tnoremap <F1> <C-W>N +You can use Esc, but you need to make sure it won't cause other keys to +break (cursor keys start with an Esc, so they may break), this probably only +works in the GUI: > + tnoremap <Esc> <C-W>N + set notimeout ttimeout timeoutlen=100 + +You can also create menus similar to terminal mode mappings, but you have to +use |:tlmenu| instead of |:tmenu|. + + *options-in-terminal* +After opening the terminal window and setting 'buftype' to "terminal" the +|TerminalWinOpen| autocommand event is triggered. This makes it possible to set +options specifically for the terminal window and buffer. Example: > + au TerminalWinOpen * setlocal bufhidden=hide + +There is also the |TerminalOpen| event, but this may be triggered for a hidden +terminal, and the current window and buffer may not be for the new terminal. +You need to use <abuf>, which is set to the terminal buffer. Example: > + au TerminalOpen * call setbufvar(+expand('<abuf>'), '&colorcolumn', 123) + +Mouse events (click and drag) are passed to the terminal. Mouse move events +are only passed when Vim itself is receiving them. For a terminal that is +when 'balloonevalterm' is enabled. + + +Size and color ~ + *terminal-size-color* +See option 'termwinsize' for controlling the size of the terminal window. +(TODO: scrolling when the terminal is larger than the window) + +The job running in the terminal can change the colors. The default foreground +and background colors are taken from Vim, the Normal highlight group. + +For a color terminal the 'background' option is used to decide whether the +terminal window will start with a white or black background. + +To use a different color the Terminal highlight group can be used, for +example: > + hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue +The highlight needs to be defined before the terminal is created. Doing it +later, or setting 'wincolor', will only have effect when the program running +in the terminal displays text or clears the terminal. +Instead of Terminal another group can be specified with the "term_highlight" +option for `term_start()`. + + *g:terminal_ansi_colors* +In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new +terminal windows may be configured using the variable +`g:terminal_ansi_colors`, which should be a list of 16 color names or +hexadecimal color codes, similar to those accepted by |highlight-guifg|. When +not using GUI colors, the terminal window always uses the 16 ANSI colors of +the underlying terminal. +When using `term_start()` the colors can be set with the "ansi_colors" option. +The |term_setansicolors()| function can be used to change the colors, and +|term_getansicolors()| to get the currently used colors. + + +Command syntax ~ + +:[range]ter[minal] [options] [command] *:ter* *:terminal* + Open a new terminal window. + + If [command] is provided run it as a job and connect + the input and output to the terminal. + If [command] is not given the 'shell' option is used. + if [command] is NONE no job is started, the pty of the + terminal can be used by a command like gdb. + + If [command] is missing the default behavior is to + close the terminal when the shell exits. This can be + changed with the ++noclose argument. + If [command] is present the default behavior is to + keep the terminal open in Terminal-Normal mode. This + can be changed with the ++close argument. + + No Vim command can follow, any | is included in + [command]. Use `:execute` if you must have a Vim + command following in the same line. + + A new buffer will be created, using [command] or + 'shell' as the name, prefixed with a "!". If a buffer + by this name already exists a number is added in + parentheses. E.g. if "gdb" exists the second terminal + buffer will use "!gdb (1)". + + If [range] is given the specified lines are used as + input for the job. It will not be possible to type + keys in the terminal window. For MS-Windows see the + ++eof argument below. + + *term++close* *term++open* + Supported [options] are: + ++close The terminal window will close + automatically when the job terminates. + |terminal-close| + ++noclose The terminal window will NOT close + automatically when the job terminates. + ++open When the job terminates and no window + shows it, a window will be opened. + Note that this can be interruptive. + The last of ++close, ++noclose and ++open + matters and rules out earlier arguments. + + ++curwin Open the terminal in the current + window, do not split the current + window. Fails if the current buffer + cannot be |abandon|ed. + ++hidden Open the terminal in a hidden buffer, + no window will be used. + ++norestore Do not include this terminal window + in a session file. + ++shell Instead of executing {command} + directly, use a shell, like with + `:!command` *E279* + {only works on Unix currently} + ++kill={how} When trying to close the terminal + window kill the job with {how}. See + |term_setkill()| for the values. + ++rows={height} Use {height} for the terminal window + height. If the terminal uses the full + Vim height (no window above or below + the terminal window) the command line + height will be reduced as needed. + ++cols={width} Use {width} for the terminal window + width. If the terminal uses the full + Vim width (no window left or right of + the terminal window) this value is + ignored. + ++eof={text} When using [range]: text to send after + the last line was written. Cannot + contain white space. A CR is + appended. For MS-Windows the default + is to send CTRL-D. + E.g. for a shell use "++eof=exit" and + for Python "++eof=exit()". Special + codes can be used like with `:map`, + e.g. "<C-Z>" for CTRL-Z. + ++type={pty} (MS-Windows only): Use {pty} as the + virtual console. See 'termwintype' + for the values. + ++api={expr} Permit the function name starting with + {expr} to be called as |terminal-api| + function. If {expr} is empty then no + function can be called. + + If you want to use more options use the |term_start()| + function. + If you want to split the window vertically, use: > + :vertical terminal +< Or short: > + :vert ter + +When the buffer associated with the terminal is forcibly unloaded or wiped out +the job is killed, similar to calling `job_stop(job, "kill")` . +Closing the window normally results in |E947|. When a kill method was set +with "++kill={how}" or |term_setkill()| then closing the window will use that +way to kill or interrupt the job. For example: > + :term ++kill=term tail -f /tmp/log + +So long as the job is running the window behaves like it contains a modified +buffer. Trying to close the window with `CTRL-W :quit` fails. When using +`CTRL-W :quit!` the job is ended. The text in the window is lost. The buffer +still exists, but getting it in a window with `:buffer` will show an empty +buffer. + +Trying to close the window with `CTRL-W :close` also fails. Using +`CTRL-W :close!` will close the window and make the buffer hidden. + +You can use `CTRL-W :hide` to close the terminal window and make the buffer +hidden, the job keeps running. The `:buffer` command can be used to turn the +current window into a terminal window. If there are unsaved changes this +fails, use ! to force, as usual. + + *terminal-close* +When the terminal window is closed, e.g. when the shell exits and "++close" +argument was used, and this is the last normal Vim window, then Vim will exit. +This is like using |:quit| in a normal window. Help and preview windows are +not counted. + +To have a background job run without a window, and open the window when it's +done, use options like this: > + :term ++hidden ++open make +Note that the window will open at an unexpected moment, this will interrupt +what you are doing. + + *E947* *E948* +So long as the job is running, the buffer is considered modified and Vim +cannot be quit easily, see |abandon|. + +When the job has finished and no changes were made to the buffer: closing the +window will wipe out the buffer. + +Before changes can be made to a terminal buffer, the 'modifiable' option must +be set. This is only possible when the job has finished. At the first change +the buffer will become a normal buffer and the highlighting is removed. +You may want to change the buffer name with |:file| to be able to write, since +the buffer name will still be set to the command. + + +Resizing ~ + *terminal-resizing* +The size of the terminal can be in one of three modes: + +1. The 'termwinsize' option is empty: The terminal size follows the window + size. The minimal size is 2 screen lines with 10 cells. + +2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number + of screen rows and "cols" is the minimal number of cells. + +3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower + case). The terminal size is fixed to the specified number of screen lines + and cells. If the window is bigger there will be unused empty space. + +If the window is smaller than the terminal size, only part of the terminal can +be seen (the lower-left part). + +The |term_getsize()| function can be used to get the current size of the +terminal. |term_setsize()| can be used only when in the first or second mode, +not when 'termwinsize' is "rowsXcols". + + +Terminal-Job and Terminal-Normal mode ~ + *Terminal-mode* *Terminal-Job* +When the job is running the contents of the terminal is under control of the +job. That includes the cursor position. Typed keys are sent to the job. +The terminal contents can change at any time. This is called Terminal-Job +mode. + +Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the +contents of the terminal window is under control of Vim, the job output is +suspended. CTRL-\ CTRL-N does the same. + +Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by +|term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are. + +It is not possible to enter Insert mode from Terminal-Job mode. + + *Terminal-Normal* *E946* +In Terminal-Normal mode you can move the cursor around with the usual Vim +commands, Visually mark text, yank text, etc. But you cannot change the +contents of the buffer. The commands that would start insert mode, such as +'i' and 'a', return to Terminal-Job mode. The window will be updated to show +the contents of the terminal. |:startinsert| is ineffective. + +In Terminal-Normal mode the statusline and window title show "(Terminal)". If +the job ends while in Terminal-Normal mode this changes to +"(Terminal-finished)". + +When the job outputs lines in the terminal, such that the contents scrolls off +the top, those lines are remembered and can be seen in Terminal-Normal mode. +The number of lines is limited by the 'termwinscroll' option. When going over +this limit, the first 10% of the scrolled lines are deleted and are lost. + + +Cursor style ~ + *terminal-cursor-style* +By default the cursor in the terminal window uses a not blinking block. The +normal xterm escape sequences can be used to change the blinking state and the +shape. Once focus leaves the terminal window Vim will restore the original +cursor. + +An exception is when xterm is started with the "-bc" argument, or another way +that causes the cursor to blink. This actually means that the blinking flag +is inverted. Since Vim cannot detect this, the terminal window cursor +blinking will also be inverted. + + +Session ~ + *terminal-session* +A terminal window will be restored when using a session file, if possible and +wanted. + +If "terminal" was removed from 'sessionoptions' then no terminal windows will +be restored. + +If the job in the terminal was finished the window will not be restored. + +If the terminal can be restored, the command that was used to open it will be +used again. To change this use the |term_setrestore()| function. This can +also be used to not restore a specific terminal by setting the command to +"NONE". + + +Special keys ~ + *terminal-special-keys* +Since the terminal emulator simulates an xterm, only escape sequences that +both Vim and xterm recognize will be available in the terminal window. If you +want to pass on other escape sequences to the job running in the terminal you +need to set up forwarding. Example: > + tmap <expr> <Esc>]b SendToTerm("\<Esc>]b") + func SendToTerm(what) + call term_sendkeys('', a:what) + return '' + endfunc + + +Unix ~ + *terminal-unix* +On Unix a pty is used to make it possible to run all kinds of commands. You +can even run Vim in the terminal! That's used for debugging, see below. + +Environment variables are used to pass information to the running job: + TERM the name of the terminal, from the 'term' option or + $TERM in the GUI; falls back to "xterm" if it does not + start with "xterm" + ROWS number of rows in the terminal initially + LINES same as ROWS + COLUMNS number of columns in the terminal initially + COLORS number of colors, 't_Co' (256*256*256 in the GUI) + VIM_SERVERNAME v:servername + VIM_TERMINAL v:version + + +MS-Windows ~ + *terminal-ms-windows* +On MS-Windows winpty is used to make it possible to run all kind of commands. +Obviously, they must be commands that run in a terminal, not open their own +window. + +You need the following two files from winpty: + + winpty.dll + winpty-agent.exe + +You can download them from the following page: + + https://github.com/rprichard/winpty + +Just put the files somewhere in your PATH. You can set the 'winptydll' option +to point to the right file, if needed. If you have both the 32-bit and 64-bit +version, rename to winpty32.dll and winpty64.dll to match the way Vim was +build. + *ConPTY* *E982* +On more recent versions of MS-Windows 10 (beginning with the "October 2018 +Update"), winpty is no longer required. On those versions, |:terminal| will use +Windows' built-in support for hosting terminal applications, "ConPTY". When +ConPTY is in use, there may be rendering artifacts regarding ambiguous-width +characters. If you encounter any such issues, install "winpty". Until the +ConPTY problems have been fixed "winpty" will be preferred. + +Environment variables are used to pass information to the running job: + VIM_SERVERNAME v:servername + + +============================================================================== +2. Terminal functions *terminal-function-details* + + *term_dumpdiff()* +term_dumpdiff({filename}, {filename} [, {options}]) + Open a new window displaying the difference between the two + files. The files must have been created with + |term_dumpwrite()|. + Returns the buffer number or zero when the diff fails. + Also see |terminal-diff|. + NOTE: this does not work with double-width characters yet. + + The top part of the buffer contains the contents of the first + file, the bottom part of the buffer contains the contents of + the second file. The middle part shows the differences. + The parts are separated by a line of equals. + + If the {options} argument is present, it must be a Dict with + these possible members: + "term_name" name to use for the buffer name, instead + of the first file name. + "term_rows" vertical size to use for the terminal, + instead of using 'termwinsize', but + respecting the minimal size + "term_cols" horizontal size to use for the terminal, + instead of using 'termwinsize', but + respecting the minimal size + "vertical" split the window vertically + "curwin" use the current window, do not split the + window; fails if the current buffer + cannot be |abandon|ed + "bufnr" do not create a new buffer, use the + existing buffer "bufnr". This buffer + must have been previously created with + term_dumpdiff() or term_dumpload() and + visible in a window. + "norestore" do not add the terminal window to a + session file + + Each character in the middle part indicates a difference. If + there are multiple differences only the first in this list is + used: + X different character + w different width + f different foreground color + b different background color + a different attribute + + missing position in first file + - missing position in second file + > cursor position in first file, not in second + < cursor position in second file, not in first + + Using the "s" key the top and bottom parts are swapped. This + makes it easy to spot a difference. + + Can also be used as a |method|: > + GetFilename()->term_dumpdiff(otherfile) +< + *term_dumpload()* +term_dumpload({filename} [, {options}]) + Open a new window displaying the contents of {filename} + The file must have been created with |term_dumpwrite()|. + Returns the buffer number or zero when it fails. + Also see |terminal-diff|. + + For {options} see |term_dumpdiff()|. + + Can also be used as a |method|: > + GetFilename()->term_dumpload() +< + *term_dumpwrite()* +term_dumpwrite({buf}, {filename} [, {options}]) + Dump the contents of the terminal screen of {buf} in the file + {filename}. This uses a format that can be used with + |term_dumpload()| and |term_dumpdiff()|. + If the job in the terminal already finished an error is given: + *E958* + If {filename} already exists an error is given: *E953* + Also see |terminal-diff|. + + {options} is a dictionary with these optional entries: + "rows" maximum number of rows to dump + "columns" maximum number of columns to dump + + Can also be used as a |method|, the base is used for the file + name: > + GetFilename()->term_dumpwrite(bufnr) + +term_getaltscreen({buf}) *term_getaltscreen()* + Returns 1 if the terminal of {buf} is using the alternate + screen. + {buf} is used as with |term_getsize()|. + + Can also be used as a |method|: > + GetBufnr()->term_getaltscreen() + + +term_getansicolors({buf}) *term_getansicolors()* + Get the ANSI color palette in use by terminal {buf}. + Returns a List of length 16 where each element is a String + representing a color in hexadecimal "#rrggbb" format. + Also see |term_setansicolors()| and |g:terminal_ansi_colors|. + If neither was used returns the default colors. + + {buf} is used as with |term_getsize()|. If the buffer does not + exist or is not a terminal window, an empty list is returned. + + Can also be used as a |method|: > + GetBufnr()->term_getansicolors() + +< {only available when compiled with GUI enabled and/or the + |+termguicolors| feature} + +term_getattr({attr}, {what}) *term_getattr()* + Given {attr}, a value returned by term_scrape() in the "attr" + item, return whether {what} is on. {what} can be one of: + bold + italic + underline + strike + reverse + + Can also be used as a |method|: > + GetAttr()->term_getattr() + + +term_getcursor({buf}) *term_getcursor()* + Get the cursor position of terminal {buf}. Returns a list with + two numbers and a dictionary: [row, col, dict]. + + "row" and "col" are one based, the first screen cell is row + 1, column 1. This is the cursor position of the terminal + itself, not of the Vim window. + + "dict" can have these members: + "visible" one when the cursor is visible, zero when it + is hidden. + "blink" one when the cursor is blinking, zero when it + is not blinking. + "shape" 1 for a block cursor, 2 for underline and 3 + for a vertical bar. + "color" color of the cursor, e.g. "green" + + {buf} must be the buffer number of a terminal window. If the + buffer does not exist or is not a terminal window, an empty + list is returned. + + Can also be used as a |method|: > + GetBufnr()->term_getcursor() + +term_getjob({buf}) *term_getjob()* + Get the Job associated with terminal window {buf}. + {buf} is used as with |term_getsize()|. + Returns |v:null| when there is no job. + + Can also be used as a |method|: > + GetBufnr()->term_getjob() + + +term_getline({buf}, {row}) *term_getline()* + Get a line of text from the terminal window of {buf}. + {buf} is used as with |term_getsize()|. + + The first line has {row} one. When {row} is "." the cursor + line is used. When {row} is invalid an empty string is + returned. + + To get attributes of each character use |term_scrape()|. + + Can also be used as a |method|: > + GetBufnr()->term_getline(row) + + +term_getscrolled({buf}) *term_getscrolled()* + Return the number of lines that scrolled to above the top of + terminal {buf}. This is the offset between the row number + used for |term_getline()| and |getline()|, so that: > + term_getline(buf, N) +< is equal to: > + getline(N + term_getscrolled(buf)) +< (if that line exists). + + {buf} is used as with |term_getsize()|. + + Can also be used as a |method|: > + GetBufnr()->term_getscrolled() + + +term_getsize({buf}) *term_getsize()* + Get the size of terminal {buf}. Returns a list with two + numbers: [rows, cols]. This is the size of the terminal, not + the window containing the terminal. + + {buf} must be the buffer number of a terminal window. Use an + empty string for the current buffer. If the buffer does not + exist or is not a terminal window, an empty list is returned. + + Can also be used as a |method|: > + GetBufnr()->term_getsize() + + +term_getstatus({buf}) *term_getstatus()* + Get the status of terminal {buf}. This returns a String with + a comma separated list of these items: + running job is running + finished job has finished + normal in Terminal-Normal mode + One of "running" or "finished" is always present. + + {buf} must be the buffer number of a terminal window. If the + buffer does not exist or is not a terminal window, an empty + string is returned. + + Can also be used as a |method|: > + GetBufnr()->term_getstatus() + + +term_gettitle({buf}) *term_gettitle()* + Get the title of terminal {buf}. This is the title that the + job in the terminal has set. + + {buf} must be the buffer number of a terminal window. If the + buffer does not exist or is not a terminal window, an empty + string is returned. + + Can also be used as a |method|: > + GetBufnr()->term_gettitle() + + +term_gettty({buf} [, {input}]) *term_gettty()* + Get the name of the controlling terminal associated with + terminal window {buf}. {buf} is used as with |term_getsize()|. + + When {input} is omitted or 0, return the name for writing + (stdout). When {input} is 1 return the name for reading + (stdin). On UNIX, both return same name. + + Can also be used as a |method|: > + GetBufnr()->term_gettty() + + +term_list() *term_list()* + Return a list with the buffer numbers of all buffers for + terminal windows. + + +term_scrape({buf}, {row}) *term_scrape()* + Get the contents of {row} of terminal screen of {buf}. + For {buf} see |term_getsize()|. + + The first line has {row} one. When {row} is "." the cursor + line is used. When {row} is invalid an empty string is + returned. + + Return a List containing a Dict for each screen cell: + "chars" character(s) at the cell + "fg" foreground color as #rrggbb + "bg" background color as #rrggbb + "attr" attributes of the cell, use |term_getattr()| + to get the individual flags + "width" cell width: 1 or 2 + + Can also be used as a |method|: > + GetBufnr()->term_scrape(row) + + +term_sendkeys({buf}, {keys}) *term_sendkeys()* + Send keystrokes {keys} to terminal {buf}. + {buf} is used as with |term_getsize()|. + + {keys} are translated as key sequences. For example, "\<c-x>" + means the character CTRL-X. + + Can also be used as a |method|: > + GetBufnr()->term_sendkeys(keys) + + +term_setapi({buf}, {expr}) *term_setapi()* + Set the function name prefix to be used for the |terminal-api| + function in terminal {buf}. For example: > + :call term_setapi(buf, "Myapi_") + :call term_setapi(buf, "") +< + The default is "Tapi_". When {expr} is an empty string then + no |terminal-api| function can be used for {buf}. + + When used as a method the base is used for {buf}: > + GetBufnr()->term_setapi({expr}) + +term_setansicolors({buf}, {colors}) *term_setansicolors()* + Set the ANSI color palette used by terminal {buf}. + {colors} must be a List of 16 valid color names or hexadecimal + color codes, like those accepted by |highlight-guifg|. + Also see |term_getansicolors()| and |g:terminal_ansi_colors|. + + The colors normally are: + 0 black + 1 dark red + 2 dark green + 3 brown + 4 dark blue + 5 dark magenta + 6 dark cyan + 7 light grey + 8 dark grey + 9 red + 10 green + 11 yellow + 12 blue + 13 magenta + 14 cyan + 15 white + + These colors are used in the GUI and in the terminal when + 'termguicolors' is set. When not using GUI colors (GUI mode + or 'termguicolors'), the terminal window always uses the 16 + ANSI colors of the underlying terminal. + + Can also be used as a |method|: > + GetBufnr()->term_setansicolors(colors) + +< {only available with GUI enabled and/or the |+termguicolors| + feature} + +term_setkill({buf}, {how}) *term_setkill()* + When exiting Vim or trying to close the terminal window in + another way, {how} defines whether the job in the terminal can + be stopped. + When {how} is empty (the default), the job will not be + stopped, trying to exit will result in |E947|. + Otherwise, {how} specifies what signal to send to the job. + See |job_stop()| for the values. + + After sending the signal Vim will wait for up to a second to + check that the job actually stopped. + + Can also be used as a |method|: > + GetBufnr()->term_setkill(how) + + +term_setrestore({buf}, {command}) *term_setrestore()* + Set the command to write in a session file to restore the job + in this terminal. The line written in the session file is: > + terminal ++curwin ++cols=%d ++rows=%d {command} +< Make sure to escape the command properly. + + Use an empty {command} to run 'shell'. + Use "NONE" to not restore this window. + + Can also be used as a |method|: > + GetBufnr()->term_setrestore(command) + + +term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955* + Set the size of terminal {buf}. The size of the window + containing the terminal will also be adjusted, if possible. + If {rows} or {cols} is zero or negative, that dimension is not + changed. + + {buf} must be the buffer number of a terminal window. Use an + empty string for the current buffer. If the buffer does not + exist or is not a terminal window, an error is given. + + Can also be used as a |method|: > + GetBufnr()->term_setsize(rows, cols) + + +term_start({cmd} [, {options}]) *term_start()* + Open a terminal window and run {cmd} in it. + + {cmd} can be a string or a List, like with |job_start()|. The + string "NONE" can be used to open a terminal window without + starting a job, the pty of the terminal can be used by a + command like gdb. + + Returns the buffer number of the terminal window. If {cmd} + cannot be executed the window does open and shows an error + message. + If opening the window fails zero is returned. + + {options} are similar to what is used for |job_start()|, see + |job-options|. However, not all options can be used. These + are supported: + all timeout options + "stoponexit", "cwd", "env" + "callback", "out_cb", "err_cb", "exit_cb", "close_cb" + "in_io", "in_top", "in_bot", "in_name", "in_buf" + "out_io", "out_name", "out_buf", "out_modifiable", "out_msg" + "err_io", "err_name", "err_buf", "err_modifiable", "err_msg" + However, at least one of stdin, stdout or stderr must be + connected to the terminal. When I/O is connected to the + terminal then the callback function for that part is not used. + + There are extra options: + "term_name" name to use for the buffer name, instead + of the command name. + "term_rows" vertical size to use for the terminal, + instead of using 'termwinsize' + "term_cols" horizontal size to use for the terminal, + instead of using 'termwinsize' + "vertical" split the window vertically; note that + other window position can be defined with + command modifiers, such as |:belowright|. + "curwin" use the current window, do not split the + window; fails if the current buffer + cannot be |abandon|ed + "hidden" do not open a window + "norestore" do not add the terminal window to a + session file + "term_kill" what to do when trying to close the + terminal window, see |term_setkill()| + "term_finish" What to do when the job is finished: + "close": close any windows + "open": open window if needed + Note that "open" can be interruptive. + See |term++close| and |term++open|. + "term_opencmd" command to use for opening the window when + "open" is used for "term_finish"; must + have "%d" where the buffer number goes, + e.g. "10split|buffer %d"; when not + specified "botright sbuf %d" is used + "term_highlight" highlight group to use instead of + "Terminal" + "eof_chars" Text to send after all buffer lines were + written to the terminal. When not set + CTRL-D is used on MS-Windows. For Python + use CTRL-Z or "exit()". For a shell use + "exit". A CR is always added. + "ansi_colors" A list of 16 color names or hex codes + defining the ANSI palette used in GUI + color modes. See |g:terminal_ansi_colors|. + "tty_type" (MS-Windows only): Specify which pty to + use. See 'termwintype' for the values. + "term_api" function name prefix for the + |terminal-api| function. See + |term_setapi()|. + + Can also be used as a |method|: > + GetCommand()->term_start() + + +term_wait({buf} [, {time}]) *term_wait()* + Wait for pending updates of {buf} to be handled. + {buf} is used as with |term_getsize()|. + {time} is how long to wait for updates to arrive in msec. If + not set then 10 msec will be used. + + Can also be used as a |method|: > + GetBufnr()->term_wait() + +============================================================================== +3. Terminal communication *terminal-communication* + +There are several ways to communicate with the job running in a terminal: +- Use |term_sendkeys()| to send text and escape sequences from Vim to the job. +- Use the JSON API to send encoded commands from the job to Vim. +- Use the |client-server| mechanism. This works on machines with an X server + and on MS-Windows. + + +Vim to job: term_sendkeys() ~ + *terminal-to-job* +This allows for remote controlling the job running in the terminal. It is a +one-way mechanism. The job can update the display to signal back to Vim. +For example, if a shell is running in a terminal, you can do: > + call term_sendkeys(buf, "ls *.java\<CR>") + +This requires for the job to be in the right state where it will do the right +thing when receiving the keys. For the above example, the shell must be +waiting for a command to be typed. + +For a job that was written for the purpose, you can use the JSON API escape +sequence in the other direction. E.g.: > + call term_sendkeys(buf, "\<Esc>]51;["response"]\x07") + + +Job to Vim: JSON API ~ + *terminal-api* +The job can send JSON to Vim, using a special escape sequence. The JSON +encodes a command that Vim understands. Example of such a message: > + <Esc>]51;["drop", "README.md"]<07> + +The body is always a list, making it easy to find the end: ]<07>. +The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is +similar to what we are doing here. + +Currently supported commands: + + call {funcname} {argument} + + Call a user defined function with {argument}. + The function is called with two arguments: the buffer number + of the terminal and {argument}, the decoded JSON argument. + By default, the function name must start with "Tapi_" to avoid + accidentally calling a function not meant to be used for the + terminal API. This can be changed with |term_setapi()|. + The user function should sanity check the argument. + The function can use |term_sendkeys()| to send back a reply. + Example in JSON: > + ["call", "Tapi_Impression", ["play", 14]] +< Calls a function defined like this: > + function Tapi_Impression(bufnum, arglist) + if len(a:arglist) == 2 + echomsg "impression " . a:arglist[0] + echomsg "count " . a:arglist[1] + endif + endfunc +< Output from `:echo` may be erased by a redraw, use `:echomsg` + to be able to see it with `:messages`. + + drop {filename} [options] + + Let Vim open a file, like the `:drop` command. If {filename} + is already open in a window, switch to that window. Otherwise + open a new window to edit {filename}. + Note that both the job and Vim may change the current + directory, thus it's best to use the full path. + + [options] is only used when opening a new window. If present, + it must be a Dict. Similarly to |++opt|, these entries are + recognized: + "ff" file format: "dos", "mac" or "unix" + "fileformat" idem + "enc" overrides 'fileencoding' + "encoding" idem + "bin" sets 'binary' + "binary" idem + "nobin" resets 'binary' + "nobinary" idem + "bad" specifies behavior for bad characters, see + |++bad| + + Example in JSON: > + ["drop", "path/file.txt", {"ff": "dos"}] + +A trick to have Vim send this escape sequence: > + exe "set t_ts=\<Esc>]51; t_fs=\x07" + let &titlestring = '["call","Tapi_TryThis",["hello",123]]' + redraw + set t_ts& t_fs& + +Rationale: Why not allow for any command or expression? Because that might +create a security problem. + + +Using the client-server feature ~ + *terminal-client-server* +This only works when v:servername is not empty. If needed you can set it, +before opening the terminal, with: > + call remote_startserver('vim-server') + +$VIM_SERVERNAME is set in the terminal to pass on the server name. + +In the job you can then do something like: > + vim --servername $VIM_SERVERNAME --remote +123 some_file.c +This will open the file "some_file.c" and put the cursor on line 123. + +============================================================================== +4. Remote testing *terminal-testing* + +Most Vim tests execute a script inside Vim. For some tests this does not +work, running the test interferes with the code being tested. To avoid this +Vim is executed in a terminal window. The test sends keystrokes to it and +inspects the resulting screen state. + +Functions ~ + +|term_sendkeys()| send keystrokes to a terminal (not subject to tmap) +|term_wait()| wait for screen to be updated +|term_scrape()| inspect terminal screen + + +============================================================================== +5. Diffing screen dumps *terminal-diff* + +In some cases it can be bothersome to test that Vim displays the right +characters on the screen. E.g. with syntax highlighting. To make this +simpler it is possible to take a screen dump of a terminal and compare it to +an expected screen dump. + +Vim uses the window size, text, color and other attributes as displayed. The +Vim screen size, font and other properties do not matter. Therefore this +mechanism is portable across systems. A conventional screenshot would reflect +all differences, including font size and family. + + +Writing a screen dump test for Vim ~ + *terminal-dumptest* +For an example see the Test_syntax_c() function in +src/testdir/test_syntax.vim. The main parts are: +- Write a file you want to test with. This is useful for testing syntax + highlighting. You can also start Vim with an empty buffer. +- Run Vim in a terminal with a specific size. The default is 20 lines of 75 + characters. This makes sure the dump is always this size. The function + RunVimInTerminal() takes care of this. Pass it the arguments for the Vim + command. +- Send any commands to Vim using |term_sendkeys()|. For example: > + call term_sendkeys(buf, ":echo &lines &columns\<CR>") +- Check that the screen is now in the expected state, using + VerifyScreenDump(). This expects the reference screen dump to be in the + src/testdir/dumps/ directory. Pass the name without ".dump". It is + recommended to use the name of the test function and a sequence number, so + that we know what test is using the file. +- Repeat sending commands and checking the state. +- Finally stop Vim by calling StopVimInTerminal(). + +The first time you do this you won't have a screen dump yet. Create an empty +file for now, e.g.: > + touch src/testdir/dumps/Test_function_name_01.dump + +The test will then fail, giving you the command to compare the reference dump +and the failed dump, e.g.: > + call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump") + +Use this command in Vim, with the current directory set to src/testdir. +Once you are satisfied with the test, move the failed dump in place of the +reference: > + :!mv failed/Test_func.dump dumps/Test_func.dump + + +Creating a screen dump ~ + *terminal-screendump* + +To create the screen dump, run Vim (or any other program) in a terminal and +make it show the desired state. Then use the |term_dumpwrite()| function to +create a screen dump file. For example: > + :call term_dumpwrite(77, "mysyntax.dump") + +Here "77" is the buffer number of the terminal. Use `:ls!` to see it. + +You can view the screen dump with |term_dumpload()|: > + :call term_dumpload("mysyntax.dump") + +To verify that Vim still shows exactly the same screen, run Vim again with +exactly the same way to show the desired state. Then create a screen dump +again, using a different file name: > + :call term_dumpwrite(88, "test.dump") + +To assert that the files are exactly the same use |assert_equalfile()|: > + call assert_equalfile("mysyntax.dump", "test.dump") + +If there are differences then v:errors will contain the error message. + + +Comparing screen dumps ~ + *terminal-diffscreendump* + +|assert_equalfile()| does not make it easy to see what is different. +To spot the problem use |term_dumpdiff()|: > + call term_dumpdiff("mysyntax.dump", "test.dump") + +This will open a window consisting of three parts: +1. The contents of the first dump +2. The difference between the first and second dump +3. The contents of the second dump + +You can usually see what differs in the second part. Use the 'ruler' to +relate it to the position in the first or second dump. Letters indicate the +kind of difference: + X different character + > cursor in first but not in second + < cursor in second but not in first + w character width differs (single vs double width) + f foreground color differs + b background color differs + a attribute differs (bold, underline, reverse, etc.) + ? character missing in both + + character missing in first + - character missing in second + +Alternatively, press "s" to swap the first and second dump. Do this several +times so that you can spot the difference in the context of the text. + +============================================================================== +6. Debugging *terminal-debug* *terminal-debugger* + +The Terminal debugging plugin can be used to debug a program with gdb and view +the source code in a Vim window. Since this is completely contained inside +Vim this also works remotely over an ssh connection. + +When the |+terminal| feature is missing, the plugin will use the "prompt" +buffer type, if possible. The running program will then use a newly opened +terminal window. See |termdebug-prompt| below for details. + + +Starting ~ + *termdebug-starting* +Load the plugin with this command: > + packadd termdebug +< *:Termdebug* +To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the +command name, for example: > + :Termdebug vim + +This opens two windows: + +gdb window A terminal window in which "gdb vim" is executed. Here you + can directly interact with gdb. The buffer name is "!gdb". + +program window A terminal window for the executed program. When "run" is + used in gdb the program I/O will happen in this window, so + that it does not interfere with controlling gdb. The buffer + name is "gdb program". + +The current window is used to show the source code. When gdb pauses the +source file location will be displayed, if possible. A sign is used to +highlight the current position, using highlight group debugPC. + +If the buffer in the current window is modified, another window will be opened +to display the current gdb position. You can use `:Winbar` to add a window +toolbar there. + +Focus the terminal of the executed program to interact with it. This works +the same as any command running in a terminal window. + +When the debugger ends, typically by typing "quit" in the gdb window, the two +opened windows are closed. + +Only one debugger can be active at a time. + *:TermdebugCommand* +If you want to give specific commands to the command being debugged, you can +use the `:TermdebugCommand` command followed by the command name and +additional parameters. > + :TermdebugCommand vim --clean -c ':set nu' + +Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang +argument to start the command right away, without pausing at the gdb window +(and cursor will be in the debugged window). For example: > + :TermdebugCommand! vim --clean + +To attach gdb to an already running executable or use a core file, pass extra +arguments. E.g.: > + :Termdebug vim core + :Termdebug vim 98343 + +If no argument is given, you'll end up in a gdb window, in which you need to +specify which command to run using e.g. the gdb `file` command. + + +Example session ~ + *termdebug-example* +Start in the Vim "src" directory and build Vim: > + % make +Make sure that debug symbols are present, usually that means that $CFLAGS +includes "-g". + +Start Vim: > + % ./vim + +Load the termdebug plugin and start debugging Vim: > + :packadd termdebug + :Termdebug vim +You should now have three windows: + source - where you started, has a window toolbar with buttons + gdb - you can type gdb commands here + program - the executed program will use this window + +You can use CTRL-W CTRL-W or the mouse to move focus between windows. +Put focus on the gdb window and type: > + break ex_help + run +Vim will start running in the program window. Put focus there and type: > + :help gui +Gdb will run into the ex_help breakpoint. The source window now shows the +ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the +breakpoint was set. The line where the debugger stopped is highlighted. You +can now step through the program. Let's use the mouse: click on the "Next" +button in the window toolbar. You will see the highlighting move as the +debugger executes a line of source code. + +Click "Next" a few times until the for loop is highlighted. Put the cursor on +the end of "eap->arg", then click "Eval" in the toolbar. You will see this +displayed: + "eap->arg": 0x555555e68855 "gui" ~ +This way you can inspect the value of local variables. You can also focus the +gdb window and use a "print" command, e.g.: > + print *eap +If mouse pointer movements are working, Vim will also show a balloon when the +mouse rests on text that can be evaluated by gdb. + +Now go back to the source window and put the cursor on the first line after +the for loop, then type: > + :Break +You will see a ">>" marker appear, this indicates the new breakpoint. Now +click "Cont" in the toolbar and the code until the breakpoint will be +executed. + +You can type more advanced commands in the gdb window. For example, type: > + watch curbuf +Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution +will now continue until the value of "curbuf" changes, which is in do_ecmd(). +To remove this watchpoint again type in the gdb window: > + delete 3 + +You can see the stack by typing in the gdb window: > + where +Move through the stack frames, e.g. with: > + frame 3 +The source window will show the code, at the point where the call was made to +a deeper level. + + +Stepping through code ~ + *termdebug-stepping* +Put focus on the gdb window to type commands there. Some common ones are: +- CTRL-C interrupt the program +- next execute the current line and stop at the next line +- step execute the current line and stop at the next statement, + entering functions +- finish execute until leaving the current function +- where show the stack +- frame N go to the Nth stack frame +- continue continue execution + + *:Run* *:Arguments* +In the window showing the source code these commands can be used to control +gdb: + `:Run` [args] run the program with [args] or the previous arguments + `:Arguments` {args} set arguments for the next `:Run` + + *:Break* set a breakpoint at the cursor position + :Break {position} + set a breakpoint at the specified position + *:Clear* delete the breakpoint at the cursor position + + *:Step* execute the gdb "step" command + *:Over* execute the gdb "next" command (`:Next` is a Vim command) + *:Finish* execute the gdb "finish" command + *:Continue* execute the gdb "continue" command + *:Stop* interrupt the program + +If 'mouse' is set the plugin adds a window toolbar with these entries: + Step `:Step` + Next `:Over` + Finish `:Finish` + Cont `:Continue` + Stop `:Stop` + Eval `:Evaluate` +This way you can use the mouse to perform the most common commands. You need +to have the 'mouse' option set to enable mouse clicks. + *:Winbar* +You can add the window toolbar in other windows you open with: > + :Winbar + +If gdb stops at a source line and there is no window currently showing the +source code, a new window will be created for the source code. This also +happens if the buffer in the source code window has been modified and can't be +abandoned. + +Gdb gives each breakpoint a number. In Vim the number shows up in the sign +column, with a red background. You can use these gdb commands: +- info break list breakpoints +- delete N delete breakpoint N +You can also use the `:Clear` command if the cursor is in the line with the +breakpoint, or use the "Clear breakpoint" right-click menu entry. + + +Inspecting variables ~ + *termdebug-variables* *:Evaluate* + `:Evaluate` evaluate the expression under the cursor + `K` same (see |termdebug_map_K| to disable) + `:Evaluate` {expr} evaluate {expr} + `:'<,'>Evaluate` evaluate the Visually selected text + +This is similar to using "print" in the gdb window. +You can usually shorten `:Evaluate` to `:Ev`. + + +Other commands ~ + *termdebug-commands* + *:Gdb* jump to the gdb window + *:Program* jump to the window with the running program + *:Source* jump to the window with the source code, create it if there + isn't one + *:Asm* jump to the window with the disassembly, create it if there + isn't one + + +Prompt mode ~ + *termdebug-prompt* +When the |+terminal| feature is not supported and on MS-Windows, gdb will run +in a buffer with 'buftype' set to "prompt". This works slightly differently: +- The gdb window will be in Insert mode while typing commands. Go to Normal + mode with <Esc>, then you can move around in the buffer, copy/paste, etc. + Go back to editing the gdb command with any command that starts Insert mode, + such as `a` or `i`. +- The program being debugged will run in a separate window. On MS-Windows + this is a new console window. On Unix, if the |+terminal| feature is + available a Terminal window will be opened to run the debugged program in. + + *termdebug_use_prompt* +Prompt mode can be used even when the |+terminal| feature is present with: > + let g:termdebug_use_prompt = 1 +< + *termdebug_map_K* +The K key is normally mapped to :Evaluate. If you do not want this use: > + let g:termdebug_map_K = 0 + +< + *termdebug_disasm_window* +If you want the Asm window shown by default, set this to 1. Setting to +any value greater than 1 will set the Asm window height to that value: > + let g:termdebug_disasm_window = 15 +< + +Communication ~ + *termdebug-communication* +There is another, hidden, buffer, which is used for Vim to communicate with +gdb. The buffer name is "gdb communication". Do not delete this buffer, it +will break the debugger. + +Gdb has some weird behavior, the plugin does its best to work around that. +For example, after typing "continue" in the gdb window a CTRL-C can be used to +interrupt the running program. But after using the MI command +"-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see +"continue" being used for the `:Continue` command, instead of using the +communication channel. + + +Customizing ~ + +GDB command *termdebug-customizing* + +To change the name of the gdb command, set the "termdebugger" variable before +invoking `:Termdebug`: > + let termdebugger = "mygdb" +< *gdb-version* +Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI +interface. The "new-ui" command requires gdb version 7.12 or later. if you +get this error: + Undefined command: "new-ui". Try "help".~ +Then your gdb is too old. + + +Colors *hl-debugPC* *hl-debugBreakpoint* + +The color of the signs can be adjusted with these highlight groups: +- debugPC the current position +- debugBreakpoint a breakpoint + +The defaults are, when 'background' is "light": + hi debugPC term=reverse ctermbg=lightblue guibg=lightblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + +When 'background' is "dark": + hi debugPC term=reverse ctermbg=darkblue guibg=darkblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + + +Shortcuts *termdebug_shortcuts* + +You can define your own shortcuts (mappings) to control gdb, that can work in +any window, using the TermDebugSendCommand() function. Example: > + map ,w :call TermDebugSendCommand('where')<CR> +The argument is the gdb command. + + +Popup menu *termdebug_popup* + +By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds +these entries to the popup menu: + Set breakpoint `:Break` + Clear breakpoint `:Clear` + Evaluate `:Evaluate` +If you don't want this then disable it with: > + let g:termdebug_popup = 0 + + +Vim window width *termdebug_wide* + +To change the width of the Vim window when debugging starts and use a vertical +split: > + let g:termdebug_wide = 163 + +This will set 'columns' to 163 when `:Termdebug` is used. The value is +restored when quitting the debugger. + +If g:termdebug_wide is set and 'columns' is already a greater value, then a +vertical split will be used without modifying 'columns'. + +Set g:termdebug_wide to 1 to use a vertical split without ever changing +'columns'. This is useful when the terminal can't be resized by Vim. + + + vim:tw=78:ts=8:noet:ft=help:norl: |