vim: runtime/doc/terminal.txt annotate

annotate runtime/doc/terminal.txt @ 35526:d785e0c59ca0

runtime(termdebug): Add Deprecation warnings Commit: https://github.com/vim/vim/commit/e54fd3f7d80502f31259c185798a21d9d1b55315 Author: Ubaldo Tiberi <ubaldo.tiberi@google.com> Date: Thu Jul 4 17:14:03 2024 +0200 runtime(termdebug): Add Deprecation warnings closes: https://github.com/vim/vim/issues/15091 Signed-off-by: Ubaldo Tiberi <ubaldo.tiberi@google.com> Signed-off-by: Christian Brabandt <cb@256bit.org>

author	Christian Brabandt <cb@256bit.org>
date	Thu, 04 Jul 2024 17:15:04 +0200
parents	5d823e880ed5
children	90c3b23f6475

rev	line source
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1 terminal.txt For Vim version 9.1. Last change: 2024 Jul 04
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	6
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	7 Terminal window support terminal terminal-window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	8
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	9
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	10 The terminal feature is optional, use this to check if your Vim has it: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	11 echo has('terminal')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	12 If the result is "1" you have it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	13
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	14
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	15 1. Basic use \|terminal-use\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	16 Typing \|terminal-typing\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	17 Size and color \|terminal-size-color\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	18 Command syntax \|:terminal\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	19 Resizing \|terminal-resizing\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	20 Terminal Modes \|Terminal-mode\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	21 Cursor style \|terminal-cursor-style\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	22 Session \|terminal-session\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	23 Special keys \|terminal-special-keys\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	24 Unix \|terminal-unix\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	25 MS-Windows \|terminal-ms-windows\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	26 2. Terminal functions \|terminal-function-details\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	27 3. Terminal communication \|terminal-communication\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	28 Vim to job: term_sendkeys() \|terminal-to-job\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	29 Job to Vim: JSON API \|terminal-api\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	30 Using the client-server feature \|terminal-client-server\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	31 4. Remote testing \|terminal-testing\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	32 5. Diffing screen dumps \|terminal-diff\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	33 Writing a screen dump test for Vim \|terminal-dumptest\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	34 Creating a screen dump \|terminal-screendump\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	35 Comparing screen dumps \|terminal-diffscreendump\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	36 6. Debugging \|terminal-debug\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	37 Starting \|termdebug-starting\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	38 Example session \|termdebug-example\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	39 Stepping through code \|termdebug-stepping\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	40 Inspecting variables \|termdebug-variables\|
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	41 Navigating stack frames \|termdebug-frames\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	42 Other commands \|termdebug-commands\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	43 Events \|termdebug-events\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	44 Prompt mode \|termdebug-prompt\|
33734 55e587f6b02f runtime(termdebug): handle buffer-local mappings properly Christian Brabandt <cb@256bit.org> parents: 33649 diff changeset	45 Mappings \|termdebug-mappings\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	46 Communication \|termdebug-communication\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	47 Customizing \|termdebug-customizing\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	48
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	49 {only available when compiled with the \|+terminal\| feature}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	50 The terminal feature requires the \|+job\| and \|+channel\| features.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	51
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	52 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	53 1. Basic use terminal-use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	54
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	55 This feature is for running a terminal emulator in a Vim window. A job can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	56 started connected to the terminal emulator. For example, to run a shell: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	57 :term bash
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	58
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	59 Or to run build command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	60 :term make myprogram
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	61
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	62 The job runs asynchronously from Vim, the window will be updated to show
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	63 output from the job, also while editing in another window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	64
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	65
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	66 Typing ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	67 terminal-typing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	68 When the keyboard focus is in the terminal window, typed keys will be sent to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	69 the job. This uses a pty when possible. You can click outside of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	70 terminal window to move keyboard focus elsewhere.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	71
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	72 t_CTRL-W_CTRL-W t_CTRL-W_:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	73 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	74 CTRL-W CTRL-W move focus to the next window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	75 CTRL-W : enter an Ex command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	76 See \|CTRL-W\| for more commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	77
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	78 Special in the terminal window: t_CTRL-W_. t_CTRL-W_N
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	79 CTRL-W . send a CTRL-W to the job in the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	80 CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	81 CTRL-W N go to Terminal-Normal mode, see \|Terminal-mode\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	82 CTRL-\ CTRL-N go to Terminal-Normal mode, see \|Terminal-mode\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	83 CTRL-W " {reg} paste register {reg} t_CTRL-W_quote
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	84 Also works with the = register to insert the result of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	85 evaluating an expression.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	86 CTRL-W CTRL-C ends the job, see below \|t_CTRL-W_CTRL-C\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	87 CTRL-W gt go to next tabpage, same as `gt` t_CTRL-W_gt
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	88 CTRL-W gT go to previous tabpage, same as `gT` t_CTRL-W_gT
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	89
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	90 See option 'termwinkey' for specifying another key instead of CTRL-W that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	91 will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	92 to the job. For example:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	93 'termwinkey' CTRL-W move focus to the next window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	94 'termwinkey' : enter an Ex command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	95 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	96 'termwinkey' . send 'termwinkey' to the job in the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	97 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	98 'termwinkey' N go to terminal Normal mode, see below
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	99 'termwinkey' CTRL-N same as CTRL-W N \|t_CTRL-W_N\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	100 'termwinkey' CTRL-C same as CTRL-W CTRL-C \|t_CTRL-W_CTRL-C\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	101 t_CTRL-\_CTRL-N
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	102 The special key combination CTRL-\ CTRL-N can be used to switch to Normal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	103 mode, just like this works in any other mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	104 t_CTRL-W_CTRL-C
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	105 CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	106 CTRL-Break will also kill the job.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	107
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	108 If you type CTRL-C the effect depends on what the pty has been configured to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	109 do. For simple commands this causes a SIGINT to be sent to the job, which
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	110 would end it. Other commands may ignore the SIGINT or handle the CTRL-C
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	111 themselves (like Vim does).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	112
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	113 To change the keys you type use terminal mode mappings, see \|:tmap\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	114 These are defined like any mapping, but apply only when typing keys that are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	115 sent to the job running in the terminal. For example, to make F1 switch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	116 to Terminal-Normal mode: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	117 tnoremap <F1> <C-W>N
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	118 You can use Esc, but you need to make sure it won't cause other keys to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	119 break (cursor keys start with an Esc, so they may break), this probably only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	120 works in the GUI: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	121 tnoremap <Esc> <C-W>N
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	122 set notimeout ttimeout timeoutlen=100
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	123
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	124 You can also create menus similar to terminal mode mappings, but you have to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	125 use \|:tlmenu\| instead of \|:tmenu\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	126
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	127 options-in-terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	128 After opening the terminal window and setting 'buftype' to "terminal" the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	129 \|TerminalWinOpen\| autocommand event is triggered. This makes it possible to set
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	130 options specifically for the terminal window and buffer. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	131 au TerminalWinOpen * setlocal bufhidden=hide
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	132 This only works properly if the terminal is not hidden.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	133
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	134 For both hidden and non-hidden terminals this works, both for buffer-local and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	135 window-local options: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	136 au TerminalWinOpen,BufWinEnter * if &buftype == 'terminal'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	137 \ \| setlocal bufhidden=hide colorcolumn=123
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	138 \ \| endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	139 Note that for a hidden terminal the options are not set until the terminal is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	140 no longer hidden.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	141
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	142 There is also the \|TerminalOpen\| event. Keep in mind this may be triggered
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	143 for a hidden terminal, then the current window and buffer are not that of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	144 new terminal.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	145 You need to use <abuf>, which is set to the terminal buffer. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	146 au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(),
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	147 \ '&termwinscroll', 1000)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	148 For a window-local option, you need to delay setting the option until the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	149 terminal window has been created (this only works for a hidden terminal): >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	150 au TerminalOpen * exe printf(
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	151 \ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d',
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	152 \ expand('<abuf>')->str2nr(), 123)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	153 For a non-hidden terminal use \|TerminalWinOpen\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	154
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	155 Mouse events (click and drag) are passed to the terminal. Mouse move events
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	156 are only passed when Vim itself is receiving them. For a terminal that is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	157 when 'balloonevalterm' is enabled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	158
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	159
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	160 Size and color ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	161 terminal-size-color
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	162 See option 'termwinsize' for controlling the size of the terminal window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	163 (TODO: scrolling when the terminal is larger than the window)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	164
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	165 The job running in the terminal can change the colors. The default foreground
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	166 and background colors are taken from Vim, the Normal highlight group.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	167
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	168 For a color terminal the 'background' option is used to decide whether the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	169 terminal window will start with a white or black background.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	170
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	171 To use a different color the Terminal highlight group can be used, for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	172 example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	173 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	174 Instead of Terminal another group can be specified with the "term_highlight"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	175 option for `term_start()`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	176
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	177 g:terminal_ansi_colors
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	178 In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	179 terminal windows may be configured using the variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	180 `g:terminal_ansi_colors`, which should be a list of 16 color names or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	181 hexadecimal color codes, similar to those accepted by \|highlight-guifg\|. When
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	182 not using GUI colors, the terminal window always uses the 16 ANSI colors of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	183 the underlying terminal.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	184 When using `term_start()` the colors can be set with the "ansi_colors" option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	185 The \|term_setansicolors()\| function can be used to change the colors, and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	186 \|term_getansicolors()\| to get the currently used colors.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	187
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	188
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	189 Command syntax ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	190
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	191 :[range]ter[minal] [options] [command] :ter :terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	192 Open a new terminal window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	193
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	194 If [command] is provided run it as a job and connect
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	195 the input and output to the terminal.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	196 If [command] is not given the 'shell' option is used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	197 if [command] is NONE no job is started, the pty of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	198 terminal can be used by a command like gdb.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	199
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	200 If [command] is missing the default behavior is to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	201 close the terminal when the shell exits. This can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	202 changed with the ++noclose argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	203 If [command] is present the default behavior is to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	204 keep the terminal open in Terminal-Normal mode. This
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	205 can be changed with the ++close argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	206
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	207 No Vim command can follow, any \| is included in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	208 [command]. Use `:execute` if you must have a Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	209 command following in the same line.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	210
34396 b0f19afada63 runtime(doc): clarify expand() for :terminal windows Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	211 terminal-bufname
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	212 A new buffer will be created, using [command] or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	213 'shell' as the name, prefixed with a "!". If a buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	214 by this name already exists a number is added in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	215 parentheses. E.g. if "gdb" exists the second terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	216 buffer will use "!gdb (1)".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	217
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	218 If [range] is given the specified lines are used as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	219 input for the job. It will not be possible to type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	220 keys in the terminal window. For MS-Windows see the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	221 ++eof argument below.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	222
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	223 term++close term++open
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	224 Supported [options] are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	225 ++close The terminal window will close
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	226 automatically when the job terminates.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	227 \|terminal-close\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	228 ++noclose The terminal window will NOT close
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	229 automatically when the job terminates.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	230 ++open When the job terminates and no window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	231 shows it, a window will be opened.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	232 Note that this can be interruptive.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	233 The last of ++close, ++noclose and ++open
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	234 matters and rules out earlier arguments.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	235
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	236 ++curwin Open the terminal in the current
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	237 window, do not split the current
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	238 window. Fails if the current buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	239 cannot be \|abandon\|ed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	240 ++hidden Open the terminal in a hidden buffer,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	241 no window will be used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	242 ++norestore Do not include this terminal window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	243 in a session file.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	244 ++shell Instead of executing {command}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	245 directly, use a shell, like with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	246 `:!command` E279
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	247 {only works on Unix and MS-Windows}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	248 ++kill={how} When trying to close the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	249 window kill the job with {how}. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	250 \|term_setkill()\| for the values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	251 ++rows={height} Use {height} for the terminal window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	252 height. If the terminal uses the full
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	253 Vim height (no window above or below
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	254 the terminal window) the command line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	255 height will be reduced as needed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	256 ++cols={width} Use {width} for the terminal window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	257 width. If the terminal uses the full
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	258 Vim width (no window left or right of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	259 the terminal window) this value is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	260 ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	261 ++eof={text} When using [range]: text to send after
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	262 the last line was written. Cannot
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	263 contain white space. A CR is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	264 appended. For MS-Windows the default
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	265 is to send CTRL-D.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	266 E.g. for a shell use "++eof=exit" and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	267 for Python "++eof=exit()". Special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	268 codes can be used like with `:map`,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	269 e.g. "<C-Z>" for CTRL-Z.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	270 ++type={pty} (MS-Windows only): Use {pty} as the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	271 virtual console. See 'termwintype'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	272 for the values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	273 ++api={expr} Permit the function name starting with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	274 {expr} to be called as \|terminal-api\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	275 function. If {expr} is empty then no
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	276 function can be called.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	277
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	278 If you want to use more options use the \|term_start()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	279 function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	280 If you want to split the window vertically, use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	281 :vertical terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	282 < Or short: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	283 :vert ter
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	284
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	285 When the buffer associated with the terminal is forcibly unloaded or wiped out
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	286 the job is killed, similar to calling `job_stop(job, "kill")` .
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	287 Closing the window normally results in \|E947\|. When a kill method was set
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	288 with "++kill={how}" or \|term_setkill()\| then closing the window will use that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	289 way to kill or interrupt the job. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	290 :term ++kill=term tail -f /tmp/log
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	291
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	292 So long as the job is running the window behaves like it contains a modified
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	293 buffer. Trying to close the window with `CTRL-W :quit` fails. When using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	294 `CTRL-W :quit!` the job is ended. The text in the window is lost, the buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	295 is deleted. With `CTRL-W :bunload!` the buffer remains but will be empty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	296
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	297 Trying to close the window with `CTRL-W :close` also fails. Using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	298 `CTRL-W :close!` will close the window and make the buffer hidden.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	299
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	300 You can use `CTRL-W :hide` to close the terminal window and make the buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	301 hidden, the job keeps running. The `:buffer` command can be used to turn the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	302 current window into a terminal window. If there are unsaved changes this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	303 fails, use ! to force, as usual.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	304
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	305 terminal-close
34579 4ad44ed6719d runtime(doc): clarify close behaviour for :term Christian Brabandt <cb@256bit.org> parents: 34429 diff changeset	306 When the terminal job finishes and no [command] was given (e.g. the 'shell'
4ad44ed6719d runtime(doc): clarify close behaviour for :term Christian Brabandt <cb@256bit.org> parents: 34429 diff changeset	307 command was executed), the terminal window will be closed by default (unless
4ad44ed6719d runtime(doc): clarify close behaviour for :term Christian Brabandt <cb@256bit.org> parents: 34429 diff changeset	308 the buffer in next window receiving the space has the 'nobuflisted' option set,
4ad44ed6719d runtime(doc): clarify close behaviour for :term Christian Brabandt <cb@256bit.org> parents: 34429 diff changeset	309 in which case the terminal window would not be closed automatically, but a new
4ad44ed6719d runtime(doc): clarify close behaviour for :term Christian Brabandt <cb@256bit.org> parents: 34429 diff changeset	310 empty buffer would be opened in that window).
4ad44ed6719d runtime(doc): clarify close behaviour for :term Christian Brabandt <cb@256bit.org> parents: 34429 diff changeset	311
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	312 When the terminal window is closed, e.g. when the shell exits and "++close"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	313 argument was used, and this is the last normal Vim window, then Vim will exit.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	314 This is like using \|:quit\| in a normal window. Help and preview windows are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	315 not counted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	316
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	317 To have a background job run without a window, and open the window when it's
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	318 done, use options like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	319 :term ++hidden ++open make
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	320 Note that the window will open at an unexpected moment, this will interrupt
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	321 what you are doing.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	322
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	323 E947 E948
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	324 So long as the job is running, the buffer is considered modified and Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	325 cannot be quit easily, see \|abandon\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	326
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	327 When the job has finished and no changes were made to the buffer: closing the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	328 window will wipe out the buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	329
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	330 Before changes can be made to a terminal buffer, the 'modifiable' option must
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	331 be set. This is only possible when the job has finished. At the first change
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	332 the buffer will become a normal buffer and the highlighting is removed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	333 You may want to change the buffer name with \|:file\| to be able to write, since
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	334 the buffer name will still be set to the command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	335
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	336
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	337 Resizing ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	338 terminal-resizing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	339 The size of the terminal can be in one of three modes:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	340
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	341 1. The 'termwinsize' option is empty: The terminal size follows the window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	342 size. The minimal size is 2 screen lines with 10 cells.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	343
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	344 2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	345 of screen rows and "cols" is the minimal number of cells.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	346
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	347 3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	348 case). The terminal size is fixed to the specified number of screen lines
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	349 and cells. If the window is bigger there will be unused empty space.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	350
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	351 If the window is smaller than the terminal size, only part of the terminal can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	352 be seen (the lower-left part).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	353
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	354 The \|term_getsize()\| function can be used to get the current size of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	355 terminal. \|term_setsize()\| can be used only when in the first or second mode,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	356 not when 'termwinsize' is "rowsXcols".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	357
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	358
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	359 Terminal-Job and Terminal-Normal mode ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	360 Terminal-mode Terminal-Job
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	361 When the job is running the contents of the terminal is under control of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	362 job. That includes the cursor position. Typed keys are sent to the job.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	363 The terminal contents can change at any time. This is called Terminal-Job
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	364 mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	365
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	366 Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	367 contents of the terminal window is under control of Vim, the job output is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	368 suspended. CTRL-\ CTRL-N does the same.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	369
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	370 Terminal-Job mode is where \|:tmap\| mappings are applied. Keys sent by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	371 \|term_sendkeys()\| are not subject to tmap, but keys from \|feedkeys()\| are.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	372
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	373 It is not possible to enter Insert mode from Terminal-Job mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	374
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	375 Terminal-Normal E946
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	376 In Terminal-Normal mode you can move the cursor around with the usual Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	377 commands, Visually mark text, yank text, etc. But you cannot change the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	378 contents of the buffer. The commands that would start insert mode, such as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	379 'i' and 'a', return to Terminal-Job mode. The window will be updated to show
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	380 the contents of the terminal. \|:startinsert\| is ineffective.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	381
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	382 In Terminal-Normal mode the statusline and window title show "(Terminal)". If
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	383 the job ends while in Terminal-Normal mode this changes to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	384 "(Terminal-finished)".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	385
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	386 When the job outputs lines in the terminal, such that the contents scrolls off
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	387 the top, those lines are remembered and can be seen in Terminal-Normal mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	388 The number of lines is limited by the 'termwinscroll' option. When going over
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	389 this limit, the first 10% of the scrolled lines are deleted and are lost.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	390
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	391
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	392 Cursor style ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	393 terminal-cursor-style
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	394 By default the cursor in the terminal window uses a not blinking block. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	395 normal xterm escape sequences can be used to change the blinking state and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	396 shape. Once focus leaves the terminal window Vim will restore the original
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	397 cursor.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	398
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	399 An exception is when xterm is started with the "-bc" argument, or another way
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	400 that causes the cursor to blink. This actually means that the blinking flag
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	401 is inverted. Since Vim cannot detect this, the terminal window cursor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	402 blinking will also be inverted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	403
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	404
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	405 Session ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	406 terminal-session
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	407 A terminal window will be restored when using a session file, if possible and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	408 wanted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	409
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	410 If "terminal" was removed from 'sessionoptions' then no terminal windows will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	411 be restored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	412
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	413 If the job in the terminal was finished the window will not be restored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	414
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	415 If the terminal can be restored, the command that was used to open it will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	416 used again. To change this use the \|term_setrestore()\| function. This can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	417 also be used to not restore a specific terminal by setting the command to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	418 "NONE".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	419
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	420
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	421 Special keys ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	422 terminal-special-keys
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	423 Since the terminal emulator simulates an xterm, only escape sequences that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	424 both Vim and xterm recognize will be available in the terminal window. If you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	425 want to pass on other escape sequences to the job running in the terminal you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	426 need to set up forwarding. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	427 tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	428 func SendToTerm(what)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	429 call term_sendkeys('', a:what)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	430 return ''
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	431 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	432
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	433
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	434 Unix ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	435 terminal-unix
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	436 On Unix a pty is used to make it possible to run all kinds of commands. You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	437 can even run Vim in the terminal! That's used for debugging, see below.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	438
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	439 Environment variables are used to pass information to the running job:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	440 TERM the name of the terminal, from the 'term' option or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	441 $TERM in the GUI; falls back to "xterm" if it does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	442 start with "xterm"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	443 ROWS number of rows in the terminal initially
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	444 LINES same as ROWS
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	445 COLUMNS number of columns in the terminal initially
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	446 COLORS number of colors, 't_Co' (256256256 in the GUI)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	447 VIM_SERVERNAME v:servername
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	448 VIM_TERMINAL v:version
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	449
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	450
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	451 MS-Windows ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	452 terminal-ms-windows
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	453 On MS-Windows winpty is used to make it possible to run all kind of commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	454 Obviously, they must be commands that run in a terminal, not open their own
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	455 window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	456
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	457 You need the following two files from winpty:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	458
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	459 winpty.dll
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	460 winpty-agent.exe
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	461
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	462 You can download them from the following page:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	463
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	464 https://github.com/rprichard/winpty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	465
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	466 Just put the files somewhere in your PATH. You can set the 'winptydll' option
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	467 to point to the right file, if needed. If you have both the 32-bit and 64-bit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	468 version, rename to winpty32.dll and winpty64.dll to match the way Vim was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	469 build.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	470 ConPTY E982
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	471 On more recent versions of MS-Windows 10 (beginning with the "October 2018
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	472 Update"), winpty is no longer required. On those versions, \|:terminal\| will use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	473 Windows' built-in support for hosting terminal applications, "ConPTY". When
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	474 ConPTY is in use, there may be rendering artifacts regarding ambiguous-width
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	475 characters. If you encounter any such issues, install "winpty". Until the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	476 ConPTY problems have been fixed "winpty" will be preferred.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	477
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	478 Environment variables are used to pass information to the running job:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	479 VIM_SERVERNAME v:servername
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	480
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	481 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	482 2. Terminal functions terminal-function-details
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	483
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	484 term_dumpdiff()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	485 term_dumpdiff({filename}, {filename} [, {options}])
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	486 Open a new window displaying the difference between the two
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	487 files. The files must have been created with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	488 \|term_dumpwrite()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	489 Returns the buffer number or zero when the diff fails.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	490 Also see \|terminal-diff\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	491 NOTE: this does not work with double-width characters yet.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	492
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	493 The top part of the buffer contains the contents of the first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	494 file, the bottom part of the buffer contains the contents of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	495 the second file. The middle part shows the differences.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	496 The parts are separated by a line of equals.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	497
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	498 If the {options} argument is present, it must be a Dict with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	499 these possible members:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	500 "term_name" name to use for the buffer name, instead
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	501 of the first file name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	502 "term_rows" vertical size to use for the terminal,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	503 instead of using 'termwinsize', but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	504 respecting the minimal size
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	505 "term_cols" horizontal size to use for the terminal,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	506 instead of using 'termwinsize', but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	507 respecting the minimal size
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	508 "vertical" split the window vertically
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	509 "curwin" use the current window, do not split the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	510 window; fails if the current buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	511 cannot be \|abandon\|ed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	512 "bufnr" do not create a new buffer, use the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	513 existing buffer "bufnr". This buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	514 must have been previously created with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	515 term_dumpdiff() or term_dumpload() and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	516 visible in a window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	517 "norestore" do not add the terminal window to a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	518 session file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	519
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	520 Each character in the middle part indicates a difference. If
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	521 there are multiple differences only the first in this list is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	522 used:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	523 X different character
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	524 w different width
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	525 f different foreground color
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	526 b different background color
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	527 a different attribute
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	528 + missing position in first file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	529 - missing position in second file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	530 > cursor position in first file, not in second
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	531 < cursor position in second file, not in first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	532
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	533 Using the "s" key the top and bottom parts are swapped. This
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	534 makes it easy to spot a difference.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	535
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	536 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	537 GetFilename()->term_dumpdiff(otherfile)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	538 <
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	539 Return type: \|Number\|
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	540
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	541
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	542 term_dumpload({filename} [, {options}]) term_dumpload()
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	543 Open a new window displaying the contents of {filename}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	544 The file must have been created with \|term_dumpwrite()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	545 Returns the buffer number or zero when it fails.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	546 Also see \|terminal-diff\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	547
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	548 For {options} see \|term_dumpdiff()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	549
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	550 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	551 GetFilename()->term_dumpload()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	552 <
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	553 Return type: \|Number\|
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	554
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	555
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	556 term_dumpwrite({buf}, {filename} [, {options}]) term_dumpwrite()
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	557 Dump the contents of the terminal screen of {buf} in the file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	558 {filename}. This uses a format that can be used with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	559 \|term_dumpload()\| and \|term_dumpdiff()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	560 If the job in the terminal already finished an error is given:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	561 E958
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	562 If {filename} already exists an error is given: E953
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	563 Also see \|terminal-diff\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	564
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	565 {options} is a dictionary with these optional entries:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	566 "rows" maximum number of rows to dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	567 "columns" maximum number of columns to dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	568
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	569 Can also be used as a \|method\|, the base is used for the file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	570 name: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	571 GetFilename()->term_dumpwrite(bufnr)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	572 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	573 Return type: \|Number\|
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	574
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	575
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	576 term_getaltscreen({buf}) term_getaltscreen()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	577 Returns 1 if the terminal of {buf} is using the alternate
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	578 screen.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	579 {buf} is used as with \|term_getsize()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	580
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	581 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	582 GetBufnr()->term_getaltscreen()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	583 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	584 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	585
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	586
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	587 term_getansicolors({buf}) term_getansicolors()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	588 Get the ANSI color palette in use by terminal {buf}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	589 Returns a List of length 16 where each element is a String
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	590 representing a color in hexadecimal "#rrggbb" format.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	591 Also see \|term_setansicolors()\| and \|g:terminal_ansi_colors\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	592 If neither was used returns the default colors.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	593
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	594 {buf} is used as with \|term_getsize()\|. If the buffer does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	595 exist or is not a terminal window, an empty list is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	596
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	597 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	598 GetBufnr()->term_getansicolors()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	599 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	600 Return type: list<string> or list<any>
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	601
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	602 {only available when compiled with GUI enabled and/or the
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	603 \|+termguicolors\| feature}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	604
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	605 term_getattr({attr}, {what}) term_getattr()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	606 Given {attr}, a value returned by term_scrape() in the "attr"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	607 item, return whether {what} is on. {what} can be one of:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	608 bold
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	609 italic
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	610 underline
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	611 strike
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	612 reverse
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	613
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	614 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	615 GetAttr()->term_getattr()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	616 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	617 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	618
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	619
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	620 term_getcursor({buf}) term_getcursor()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	621 Get the cursor position of terminal {buf}. Returns a list with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	622 two numbers and a dictionary: [row, col, dict].
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	623
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	624 "row" and "col" are one based, the first screen cell is row
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	625 1, column 1. This is the cursor position of the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	626 itself, not of the Vim window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	627
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	628 "dict" can have these members:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	629 "visible" one when the cursor is visible, zero when it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	630 is hidden.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	631 "blink" one when the cursor is blinking, zero when it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	632 is not blinking.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	633 "shape" 1 for a block cursor, 2 for underline and 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	634 for a vertical bar.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	635 "color" color of the cursor, e.g. "green"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	636
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	637 {buf} must be the buffer number of a terminal window. If the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	638 buffer does not exist or is not a terminal window, an empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	639 list is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	640
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	641 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	642 GetBufnr()->term_getcursor()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	643 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	644 Return type: list<any>
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	645
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	646
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	647 term_getjob({buf}) term_getjob()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	648 Get the Job associated with terminal window {buf}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	649 {buf} is used as with \|term_getsize()\|.
35391 571a03ed0bb9 patch 9.1.0481: Vim9: term_getjob() throws an exception on error Christian Brabandt <cb@256bit.org> parents: 35350 diff changeset	650 Returns \|v:null\| when there is no job. In Vim9 script, return
35446 9d1bc7b46c10 runtime(doc): Fix typos in several documents Christian Brabandt <cb@256bit.org> parents: 35443 diff changeset	651 \|null_job\| when there is no job.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	652
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	653 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	654 GetBufnr()->term_getjob()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	655 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	656 Return type: \|job\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	657
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	658
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	659 term_getline({buf}, {row}) term_getline()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	660 Get a line of text from the terminal window of {buf}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	661 {buf} is used as with \|term_getsize()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	662
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	663 The first line has {row} one. When {row} is "." the cursor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	664 line is used. When {row} is invalid an empty string is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	665 returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	666
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	667 To get attributes of each character use \|term_scrape()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	668
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	669 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	670 GetBufnr()->term_getline(row)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	671 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	672 Return type: \|String\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	673
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	674
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	675 term_getscrolled({buf}) term_getscrolled()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	676 Return the number of lines that scrolled to above the top of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	677 terminal {buf}. This is the offset between the row number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	678 used for \|term_getline()\| and \|getline()\|, so that: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	679 term_getline(buf, N)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	680 < is equal to: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	681 getline(N + term_getscrolled(buf))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	682 < (if that line exists).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	683
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	684 {buf} is used as with \|term_getsize()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	685
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	686 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	687 GetBufnr()->term_getscrolled()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	688 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	689 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	690
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	691
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	692 term_getsize({buf}) term_getsize()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	693 Get the size of terminal {buf}. Returns a list with two
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	694 numbers: [rows, cols]. This is the size of the terminal, not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	695 the window containing the terminal.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	696
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	697 {buf} must be the buffer number of a terminal window. Use an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	698 empty string for the current buffer. If the buffer does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	699 exist or is not a terminal window, an empty list is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	700
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	701 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	702 GetBufnr()->term_getsize()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	703 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	704 Return type: list<number> or list<any>
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	705
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	706
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	707 term_getstatus({buf}) term_getstatus()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	708 Get the status of terminal {buf}. This returns a String with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	709 a comma-separated list of these items:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	710 running job is running
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	711 finished job has finished
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	712 normal in Terminal-Normal mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	713 One of "running" or "finished" is always present.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	714
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	715 {buf} must be the buffer number of a terminal window. If the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	716 buffer does not exist or is not a terminal window, an empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	717 string is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	718
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	719 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	720 GetBufnr()->term_getstatus()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	721 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	722 Return type: \|String\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	723
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	724
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	725 term_gettitle({buf}) term_gettitle()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	726 Get the title of terminal {buf}. This is the title that the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	727 job in the terminal has set.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	728
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	729 {buf} must be the buffer number of a terminal window. If the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	730 buffer does not exist or is not a terminal window, an empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	731 string is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	732
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	733 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	734 GetBufnr()->term_gettitle()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	735 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	736 Return type: \|String\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	737
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	738
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	739 term_gettty({buf} [, {input}]) term_gettty()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	740 Get the name of the controlling terminal associated with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	741 terminal window {buf}. {buf} is used as with \|term_getsize()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	742
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	743 When {input} is omitted or 0, return the name for writing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	744 (stdout). When {input} is 1 return the name for reading
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	745 (stdin). On UNIX, both return same name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	746
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	747 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	748 GetBufnr()->term_gettty()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	749 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	750 Return type: \|String\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	751
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	752
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	753 term_list() term_list()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	754 Return a list with the buffer numbers of all buffers for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	755 terminal windows.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	756
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	757 Return type: list<number> or list<any>
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	758
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	759
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	760 term_scrape({buf}, {row}) term_scrape()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	761 Get the contents of {row} of terminal screen of {buf}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	762 For {buf} see \|term_getsize()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	763
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	764 The first line has {row} one. When {row} is "." the cursor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	765 line is used. When {row} is invalid an empty string is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	766 returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	767
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	768 Return a List containing a Dict for each screen cell:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	769 "chars" character(s) at the cell
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	770 "fg" foreground color as #rrggbb
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	771 "bg" background color as #rrggbb
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	772 "attr" attributes of the cell, use \|term_getattr()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	773 to get the individual flags
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	774 "width" cell width: 1 or 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	775 For a double-width cell there is one item, thus the list can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	776 be shorter than the width of the terminal.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	777
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	778 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	779 GetBufnr()->term_scrape(row)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	780 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	781 Return type: list<dict<any>> or list<any>
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	782
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	783
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	784 term_sendkeys({buf}, {keys}) term_sendkeys()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	785 Send keystrokes {keys} to terminal {buf}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	786 {buf} is used as with \|term_getsize()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	787
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	788 {keys} are translated as key sequences. For example, "\<c-x>"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	789 means the character CTRL-X.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	790
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	791 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	792 GetBufnr()->term_sendkeys(keys)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	793 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	794 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	795
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	796
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	797 term_setansicolors({buf}, {colors}) term_setansicolors()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	798 Set the ANSI color palette used by terminal {buf}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	799 {colors} must be a List of 16 valid color names or hexadecimal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	800 color codes, like those accepted by \|highlight-guifg\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	801 Also see \|term_getansicolors()\| and \|g:terminal_ansi_colors\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	802
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	803 The colors normally are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	804 0 black
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	805 1 dark red
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	806 2 dark green
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	807 3 brown
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	808 4 dark blue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	809 5 dark magenta
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	810 6 dark cyan
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	811 7 light grey
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	812 8 dark grey
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	813 9 red
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	814 10 green
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	815 11 yellow
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	816 12 blue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	817 13 magenta
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	818 14 cyan
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	819 15 white
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	820
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	821 These colors are used in the GUI and in the terminal when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	822 'termguicolors' is set. When not using GUI colors (GUI mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	823 or 'termguicolors'), the terminal window always uses the 16
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	824 ANSI colors of the underlying terminal.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	825
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	826 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	827 GetBufnr()->term_setansicolors(colors)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	828 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	829 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	830
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	831 {only available with GUI enabled and/or the \|+termguicolors\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	832 feature}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	833
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	834
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	835 term_setapi({buf}, {expr}) term_setapi()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	836 Set the function name prefix to be used for the \|terminal-api\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	837 function in terminal {buf}. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	838 :call term_setapi(buf, "Myapi_")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	839 :call term_setapi(buf, "")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	840 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	841 The default is "Tapi_". When {expr} is an empty string then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	842 no \|terminal-api\| function can be used for {buf}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	843
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	844 When used as a method the base is used for {buf}: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	845 GetBufnr()->term_setapi({expr})
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	846 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	847 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	848
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	849
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	850 term_setkill({buf}, {how}) term_setkill()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	851 When exiting Vim or trying to close the terminal window in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	852 another way, {how} defines whether the job in the terminal can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	853 be stopped.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	854 When {how} is empty (the default), the job will not be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	855 stopped, trying to exit will result in \|E947\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	856 Otherwise, {how} specifies what signal to send to the job.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	857 See \|job_stop()\| for the values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	858
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	859 After sending the signal Vim will wait for up to a second to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	860 check that the job actually stopped.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	861
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	862 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	863 GetBufnr()->term_setkill(how)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	864 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	865 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	866
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	867
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	868 term_setrestore({buf}, {command}) term_setrestore()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	869 Set the command to write in a session file to restore the job
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	870 in this terminal. The line written in the session file is: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	871 terminal ++curwin ++cols=%d ++rows=%d {command}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	872 < Make sure to escape the command properly.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	873
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	874 Use an empty {command} to run 'shell'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	875 Use "NONE" to not restore this window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	876
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	877 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	878 GetBufnr()->term_setrestore(command)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	879 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	880 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	881
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	882
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	883 term_setsize({buf}, {rows}, {cols}) term_setsize() E955
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	884 Set the size of terminal {buf}. The size of the window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	885 containing the terminal will also be adjusted, if possible.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	886 If {rows} or {cols} is zero or negative, that dimension is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	887 changed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	888
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	889 {buf} must be the buffer number of a terminal window. Use an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	890 empty string for the current buffer. If the buffer does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	891 exist or is not a terminal window, an error is given.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	892
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	893 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	894 GetBufnr()->term_setsize(rows, cols)
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	895 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	896 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	897
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	898
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	899 term_start({cmd} [, {options}]) term_start()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	900 Open a terminal window and run {cmd} in it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	901
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	902 {cmd} can be a string or a List, like with \|job_start()\|. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	903 string "NONE" can be used to open a terminal window without
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	904 starting a job, the pty of the terminal can be used by a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	905 command like gdb.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	906
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	907 Returns the buffer number of the terminal window. If {cmd}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	908 cannot be executed the window does open and shows an error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	909 message.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	910 If opening the window fails zero is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	911
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	912 {options} are similar to what is used for \|job_start()\|, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	913 \|job-options\|. However, not all options can be used. These
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	914 are supported:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	915 all timeout options
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	916 "stoponexit", "cwd", "env"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	917 "callback", "out_cb", "err_cb", "exit_cb", "close_cb"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	918 "in_io", "in_top", "in_bot", "in_name", "in_buf"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	919 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	920 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	921 However, at least one of stdin, stdout or stderr must be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	922 connected to the terminal. When I/O is connected to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	923 terminal then the callback function for that part is not used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	924
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	925 There are extra options:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	926 "term_name" name to use for the buffer name, instead
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	927 of the command name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	928 "term_rows" vertical size to use for the terminal,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	929 instead of using 'termwinsize'; valid
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	930 range is from zero to 1000
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	931 "term_cols" horizontal size to use for the terminal,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	932 instead of using 'termwinsize'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	933 "vertical" split the window vertically; note that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	934 other window position can be defined with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	935 command modifiers, such as \|:belowright\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	936 "curwin" use the current window, do not split the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	937 window; fails if the current buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	938 cannot be \|abandon\|ed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	939 "hidden" do not open a window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	940 "norestore" do not add the terminal window to a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	941 session file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	942 "term_kill" what to do when trying to close the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	943 terminal window, see \|term_setkill()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	944 "term_finish" What to do when the job is finished:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	945 "close": close any windows
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	946 "open": open window if needed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	947 Note that "open" can be interruptive.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	948 See \|term++close\| and \|term++open\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	949 "term_opencmd" command to use for opening the window when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	950 "open" is used for "term_finish"; must
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	951 have "%d" where the buffer number goes,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	952 e.g. "10split\|buffer %d"; when not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	953 specified "botright sbuf %d" is used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	954 "term_highlight" highlight group to use instead of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	955 "Terminal"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	956 "eof_chars" Text to send after all buffer lines were
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	957 written to the terminal. When not set
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	958 CTRL-D is used on MS-Windows. For Python
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	959 use CTRL-Z or "exit()". For a shell use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	960 "exit". A CR is always added.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	961 "ansi_colors" A list of 16 color names or hex codes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	962 defining the ANSI palette used in GUI
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	963 color modes. See \|g:terminal_ansi_colors\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	964 "tty_type" (MS-Windows only): Specify which pty to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	965 use. See 'termwintype' for the values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	966 "term_api" function name prefix for the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	967 \|terminal-api\| function. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	968 \|term_setapi()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	969
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	970 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	971 GetCommand()->term_start()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	972 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	973 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	974
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	975
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	976 term_wait({buf} [, {time}]) term_wait()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	977 Wait for pending updates of {buf} to be handled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	978 {buf} is used as with \|term_getsize()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	979 {time} is how long to wait for updates to arrive in msec. If
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	980 not set then 10 msec will be used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	981
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	982 Can also be used as a \|method\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	983 GetBufnr()->term_wait()
35350 a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	984 <
a631a31adafd runtime(doc): add return type info for Vim function descriptions Christian Brabandt <cb@256bit.org> parents: 35344 diff changeset	985 Return type: \|Number\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	986
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	987 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	988 3. Terminal communication terminal-communication
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	989
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	990 There are several ways to communicate with the job running in a terminal:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	991 - Use \|term_sendkeys()\| to send text and escape sequences from Vim to the job.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	992 - Use the JSON API to send encoded commands from the job to Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	993 - Use the \|client-server\| mechanism. This works on machines with an X server
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	994 and on MS-Windows.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	995
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	996
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	997 Vim to job: term_sendkeys() ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	998 terminal-to-job
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	999 This allows for remote controlling the job running in the terminal. It is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1000 one-way mechanism. The job can update the display to signal back to Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1001 For example, if a shell is running in a terminal, you can do: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1002 call term_sendkeys(buf, "ls *.java\<CR>")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1003
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1004 This requires for the job to be in the right state where it will do the right
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1005 thing when receiving the keys. For the above example, the shell must be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1006 waiting for a command to be typed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1007
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1008 For a job that was written for the purpose, you can use the JSON API escape
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1009 sequence in the other direction. E.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1010 call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1011
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1012
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1013 Job to Vim: JSON API ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1014 terminal-api
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1015 The job can send JSON to Vim, using a special escape sequence. The JSON
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1016 encodes a command that Vim understands. Example of such a message: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1017 <Esc>]51;["drop", "README.md"]<07>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1018
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1019 The body is always a list, making it easy to find the end: ]<07>.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1020 The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1021 similar to what we are doing here.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1022
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1023 Currently supported commands:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1024
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1025 call {funcname} {argument}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1026
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1027 Call a user defined function with {argument}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1028 The function is called with two arguments: the buffer number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1029 of the terminal and {argument}, the decoded JSON argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1030 By default, the function name must start with "Tapi_" to avoid
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1031 accidentally calling a function not meant to be used for the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1032 terminal API. This can be changed with \|term_setapi()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1033 The user function should sanity check the argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1034 The function can use \|term_sendkeys()\| to send back a reply.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1035 Example in JSON: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1036 ["call", "Tapi_Impression", ["play", 14]]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1037 < Calls a function defined like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1038 function Tapi_Impression(bufnum, arglist)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1039 if len(a:arglist) == 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1040 echomsg "impression " .. a:arglist[0]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1041 echomsg "count " .. a:arglist[1]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1042 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1043 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1044 < Output from `:echo` may be erased by a redraw, use `:echomsg`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1045 to be able to see it with `:messages`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1046
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1047 drop {filename} [options]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1048
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1049 Let Vim open a file, like the `:drop` command. If {filename}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1050 is already open in a window, switch to that window. Otherwise
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1051 open a new window to edit {filename}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1052 Note that both the job and Vim may change the current
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1053 directory, thus it's best to use the full path.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1054
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1055 [options] is only used when opening a new window. If present,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1056 it must be a Dict. Similarly to \|++opt\|, these entries are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1057 recognized:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1058 "ff" file format: "dos", "mac" or "unix"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1059 "fileformat" idem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1060 "enc" overrides 'fileencoding'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1061 "encoding" idem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1062 "bin" sets 'binary'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1063 "binary" idem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1064 "nobin" resets 'binary'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1065 "nobinary" idem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1066 "bad" specifies behavior for bad characters, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1067 \|++bad\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1068
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1069 Example in JSON: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1070 ["drop", "path/file.txt", {"ff": "dos"}]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1071
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1072 A trick to have Vim send this escape sequence: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1073 exe "set t_ts=\<Esc>]51; t_fs=\x07"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1074 let &titlestring = '["call","Tapi_TryThis",["hello",123]]'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1075 redraw
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1076 set t_ts& t_fs&
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1077
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1078 Rationale: Why not allow for any command or expression? Because that might
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1079 create a security problem.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1080 terminal-autoshelldir
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1081 This can be used to pass the current directory from a shell to Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1082 Put this in your .vimrc: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1083 def g:Tapi_lcd(_, path: string)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1084 if isdirectory(path)
34429 a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1085 execute 'silent lcd ' .. fnameescape(path)
a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1086 endif
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1087 enddef
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1088 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1089 And, in a bash init file: >
34429 a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1090 if [[ -n "$VIM_TERMINAL" ]]; then
a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1091 PROMPT_COMMAND='_vim_sync_PWD'
a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1092 function _vim_sync_PWD() {
a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1093 printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD"
a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1094 }
a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1095 fi
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1096 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1097 Or, for zsh: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1098 if [[ -n "$VIM_TERMINAL" ]]; then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1099 autoload -Uz add-zsh-hook
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1100 add-zsh-hook -Uz chpwd _vim_sync_PWD
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1101 function _vim_sync_PWD() {
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1102 printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1103 }
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1104 fi
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1105 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1106 Or, for fish: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1107 if test -n "$VIM_TERMINAL"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1108 function _vim_sync_PWD --on-variable=PWD
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1109 printf '\033]51;["call", "Tapi_lcd", "%s"]\007' "$PWD"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1110 end
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1111 end
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1112
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1113
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1114 Using the client-server feature ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1115 terminal-client-server
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1116 This only works when v:servername is not empty. If needed you can set it,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1117 before opening the terminal, with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1118 call remote_startserver('vim-server')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1119
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1120 $VIM_SERVERNAME is set in the terminal to pass on the server name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1121
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1122 In the job you can then do something like: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1123 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1124 This will open the file "some_file.c" and put the cursor on line 123.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1125
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1126 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1127 4. Remote testing terminal-testing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1128
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1129 Most Vim tests execute a script inside Vim. For some tests this does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1130 work, running the test interferes with the code being tested. To avoid this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1131 Vim is executed in a terminal window. The test sends keystrokes to it and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1132 inspects the resulting screen state.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1133
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1134 Functions ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1135
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1136 \|term_sendkeys()\| send keystrokes to a terminal (not subject to tmap)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1137 \|term_wait()\| wait for screen to be updated
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1138 \|term_scrape()\| inspect terminal screen
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1139
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1140
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1141 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1142 5. Diffing screen dumps terminal-diff
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1143
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1144 In some cases it can be bothersome to test that Vim displays the right
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1145 characters on the screen. E.g. with syntax highlighting. To make this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1146 simpler it is possible to take a screen dump of a terminal and compare it to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1147 an expected screen dump.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1148
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1149 Vim uses the window size, text, color and other attributes as displayed. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1150 Vim screen size, font and other properties do not matter. Therefore this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1151 mechanism is portable across systems. A conventional screenshot would reflect
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1152 all differences, including font size and family.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1153
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1154
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1155 Writing a screen dump test for Vim ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1156 terminal-dumptest
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1157 For an example see the Test_syntax_c() function in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1158 src/testdir/test_syntax.vim. The main parts are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1159 - Write a file you want to test with. This is useful for testing syntax
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1160 highlighting. You can also start Vim with an empty buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1161 - Run Vim in a terminal with a specific size. The default is 20 lines of 75
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1162 characters. This makes sure the dump is always this size. The function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1163 RunVimInTerminal() takes care of this. Pass it the arguments for the Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1164 command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1165 - Send any commands to Vim using \|term_sendkeys()\|. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1166 call term_sendkeys(buf, ":echo &lines &columns\<CR>")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1167 - Check that the screen is now in the expected state, using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1168 VerifyScreenDump(). This expects the reference screen dump to be in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1169 src/testdir/dumps/ directory. Pass the name without ".dump". It is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1170 recommended to use the name of the test function and a sequence number, so
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1171 that we know what test is using the file.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1172 - Repeat sending commands and checking the state.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1173 - Finally stop Vim by calling StopVimInTerminal().
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1174
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1175 The first time you do this you won't have a screen dump yet. Create an empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1176 file for now, e.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1177 touch src/testdir/dumps/Test_function_name_01.dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1178
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1179 The test will then fail, giving you the command to compare the reference dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1180 and the failed dump, e.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1181 call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1182
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1183 Use this command in Vim, with the current directory set to src/testdir.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1184 Once you are satisfied with the test, move the failed dump in place of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1185 reference: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1186 :!mv failed/Test_func.dump dumps/Test_func.dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1187
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1188
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1189 Creating a screen dump ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1190 terminal-screendump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1191 To create the screen dump, run Vim (or any other program) in a terminal and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1192 make it show the desired state. Then use the \|term_dumpwrite()\| function to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1193 create a screen dump file. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1194 :call term_dumpwrite(77, "mysyntax.dump")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1195
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1196 Here "77" is the buffer number of the terminal. Use `:ls!` to see it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1197
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1198 You can view the screen dump with \|term_dumpload()\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1199 :call term_dumpload("mysyntax.dump")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1200
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1201 To verify that Vim still shows exactly the same screen, run Vim again with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1202 exactly the same way to show the desired state. Then create a screen dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1203 again, using a different file name: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1204 :call term_dumpwrite(88, "test.dump")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1205
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1206 To assert that the files are exactly the same use \|assert_equalfile()\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1207 call assert_equalfile("mysyntax.dump", "test.dump")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1208
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1209 If there are differences then v:errors will contain the error message.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1210
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1211
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1212 Comparing screen dumps ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1213 terminal-diffscreendump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1214 \|assert_equalfile()\| does not make it easy to see what is different.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1215 To spot the problem use \|term_dumpdiff()\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1216 call term_dumpdiff("mysyntax.dump", "test.dump")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1217
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1218 This will open a window consisting of three parts:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1219 1. The contents of the first dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1220 2. The difference between the first and second dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1221 3. The contents of the second dump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1222
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1223 You can usually see what differs in the second part. Use the 'ruler' to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1224 relate it to the position in the first or second dump. Letters indicate the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1225 kind of difference:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1226 X different character
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1227 > cursor in first but not in second
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1228 < cursor in second but not in first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1229 w character width differs (single vs double width)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1230 f foreground color differs
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1231 b background color differs
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1232 a attribute differs (bold, underline, reverse, etc.)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1233 ? character missing in both
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1234 + character missing in first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1235 - character missing in second
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1236
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1237 Alternatively, press "s" to swap the first and second dump. Do this several
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1238 times so that you can spot the difference in the context of the text.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1239
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1240 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1241 6. Debugging terminal-debug terminal-debugger
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1242
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1243 The Terminal debugging plugin can be used to debug a program with gdb and view
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1244 the source code in a Vim window. Since this is completely contained inside
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1245 Vim this also works remotely over an ssh connection.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1246
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1247 When the \|+terminal\| feature is missing, the plugin will use the "prompt"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1248 buffer type, if possible. The running program will then use a newly opened
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1249 terminal window. See \|termdebug-prompt\| below for details.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1250
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1251
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1252 Starting ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1253 termdebug-starting
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1254 Load the plugin with this command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1255 packadd termdebug
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1256 < :Termdebug
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1257 To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1258 command name, for example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1259 :Termdebug vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1260
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1261 This opens two windows:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1262
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1263 gdb window A terminal window in which "gdb vim" is executed. Here you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1264 can directly interact with gdb. The buffer name is "!gdb".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1265
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1266 program window A terminal window for the executed program. When "run" is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1267 used in gdb the program I/O will happen in this window, so
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1268 that it does not interfere with controlling gdb. The buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1269 name is "debugged program".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1270
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1271 The current window is used to show the source code. When gdb pauses the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1272 source file location will be displayed, if possible. A sign is used to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1273 highlight the current position, using highlight group debugPC.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1274
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1275 If the buffer in the current window is modified, another window will be opened
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1276 to display the current gdb position. You can use `:Winbar` to add a window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1277 toolbar there.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1278
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1279 Focus the terminal of the executed program to interact with it. This works
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1280 the same as any command running in a terminal window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1281
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1282 When the debugger ends, typically by typing "quit" in the gdb window, the two
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1283 opened windows are closed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1284
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1285 Only one debugger can be active at a time.
35482 5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1286
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1287 termdebug-timeout
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1288 Depending on how gdb is launched, termdebug startup time may vary.
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1289 To avoid termdebug to get stuck if the startup process of gdb takes too long,
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1290 a configurable timeout is included. Such time out is configurable in terms of
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1291 multiple of 10ms: >
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1292 let g:termdebug_config['timeout'] = 500 # 500 * 10ms = 5 seconds.
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1293
5d823e880ed5 patch 9.1.0508: termdebug plugin can be further improved Christian Brabandt <cb@256bit.org> parents: 35455 diff changeset	1294 The default timeout is 3000 ms.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1295 :TermdebugCommand
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1296 If you want to give specific commands to the command being debugged, you can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1297 use the `:TermdebugCommand` command followed by the command name and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1298 additional parameters. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1299 :TermdebugCommand vim --clean -c ':set nu'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1300
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1301 Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1302 argument to start the command right away, without pausing at the gdb window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1303 (and cursor will be in the debugged window). For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1304 :TermdebugCommand! vim --clean
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1305
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1306 To attach gdb to an already running executable or use a core file, pass extra
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1307 arguments. E.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1308 :Termdebug vim core
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1309 :Termdebug vim 98343
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1310
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1311 If no argument is given, you'll end up in a gdb window, in which you need to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1312 specify which command to run using e.g. the gdb `file` command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1313
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1314
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1315 Example session ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1316 termdebug-example
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1317 Start in the Vim "src" directory and build Vim: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1318 % make
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1319 Make sure that debug symbols are present, usually that means that $CFLAGS
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1320 includes "-g".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1321
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1322 Start Vim: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1323 % ./vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1324
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1325 Load the termdebug plugin and start debugging Vim: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1326 :packadd termdebug
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1327 :Termdebug vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1328 You should now have three windows:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1329 source - where you started, has a window toolbar with buttons
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1330 gdb - you can type gdb commands here
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1331 program - the executed program will use this window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1332
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1333 You can use CTRL-W CTRL-W or the mouse to move focus between windows.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1334 Put focus on the gdb window and type: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1335 break ex_help
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1336 run
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1337 Vim will start running in the program window. Put focus there and type: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1338 :help gui
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1339 Gdb will run into the ex_help breakpoint. The source window now shows the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1340 ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1341 breakpoint was set. The line where the debugger stopped is highlighted. You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1342 can now step through the program. Let's use the mouse: click on the "Next"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1343 button in the window toolbar. You will see the highlighting move as the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1344 debugger executes a line of source code.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1345
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1346 Click "Next" a few times until the for loop is highlighted. Put the cursor on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1347 the end of "eap->arg", then click "Eval" in the toolbar. You will see this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1348 displayed:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1349 "eap->arg": 0x555555e68855 "gui" ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1350 This way you can inspect the value of local variables. You can also focus the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1351 gdb window and use a "print" command, e.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1352 print *eap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1353 If mouse pointer movements are working, Vim will also show a balloon when the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1354 mouse rests on text that can be evaluated by gdb.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1355
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1356 Now go back to the source window and put the cursor on the first line after
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1357 the for loop, then type: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1358 :Break
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1359 You will see a ">>" marker appear, this indicates the new breakpoint. Now
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1360 click "Cont" in the toolbar and the code until the breakpoint will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1361 executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1362
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1363 You can type more advanced commands in the gdb window. For example, type: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1364 watch curbuf
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1365 Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1366 will now continue until the value of "curbuf" changes, which is in do_ecmd().
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1367 To remove this watchpoint again type in the gdb window: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1368 delete 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1369
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1370 You can see the stack by typing in the gdb window: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1371 where
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1372 Move through the stack frames, e.g. with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1373 frame 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1374 The source window will show the code, at the point where the call was made to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1375 a deeper level.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1376
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1377
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1378 Stepping through code ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1379 termdebug-stepping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1380 Put focus on the gdb window to type commands there. Some common ones are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1381 - CTRL-C interrupt the program
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1382 - next execute the current line and stop at the next line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1383 - step execute the current line and stop at the next statement,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1384 entering functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1385 - until execute until past the current cursor line or past a specified
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1386 position or the current stack frame returns
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1387 - finish execute until leaving the current function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1388 - where show the stack
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1389 - frame N go to the Nth stack frame
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1390 - continue continue execution
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1391
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1392 :Run :Arguments
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1393 In the window showing the source code these commands can be used to control
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1394 gdb:
35443 469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1395 `:Run` [args] run the program with [args] or the previous arguments
469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1396 `:Arguments` {args} set arguments for the next `:Run`
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1397
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1398 :Break set a breakpoint at the cursor position
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1399 :Break {position}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1400 set a breakpoint at the specified position
33944 4cacac1abdb8 runtime(termdebug): add Tbreak command Christian Brabandt <cb@256bit.org> parents: 33761 diff changeset	1401 :Tbreak set a temporary breakpoint at the cursor position
4cacac1abdb8 runtime(termdebug): add Tbreak command Christian Brabandt <cb@256bit.org> parents: 33761 diff changeset	1402 :Tbreak {position}
4cacac1abdb8 runtime(termdebug): add Tbreak command Christian Brabandt <cb@256bit.org> parents: 33761 diff changeset	1403 set a temporary breakpoint at the specified position
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1404 :Clear delete the breakpoint at the cursor position
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1405
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1406 :Step execute the gdb "step" command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1407 :Over execute the gdb "next" command (`:Next` is a Vim command)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1408 :Until execute the gdb "until" command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1409 :Finish execute the gdb "finish" command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1410 :Continue execute the gdb "continue" command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1411 :Stop interrupt the program
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1412
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1413 If 'mouse' is set the plugin adds a window toolbar with these entries:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1414 Step `:Step`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1415 Next `:Over`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1416 Finish `:Finish`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1417 Cont `:Continue`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1418 Stop `:Stop`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1419 Eval `:Evaluate`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1420 This way you can use the mouse to perform the most common commands. You need
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1421 to have the 'mouse' option set to enable mouse clicks.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1422 See \|termdebug_winbar\| for configuring this toolbar.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1423 :Winbar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1424 You can add the window toolbar in other windows you open with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1425 :Winbar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1426
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1427 If gdb stops at a source line and there is no window currently showing the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1428 source code, a new window will be created for the source code. This also
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1429 happens if the buffer in the source code window has been modified and can't be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1430 abandoned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1431
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1432 Gdb gives each breakpoint a number. In Vim the number shows up in the sign
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1433 column, with a red background. You can use these gdb commands:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1434 - info break list breakpoints
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1435 - delete N delete breakpoint N
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1436 You can also use the `:Clear` command if the cursor is in the line with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1437 breakpoint, or use the "Clear breakpoint" right-click menu entry.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1438
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1439
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1440 Inspecting variables ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1441 termdebug-variables :Evaluate
35443 469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1442 `:Evaluate` evaluate the expression under the cursor
469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1443 `K` same (see \|termdebug_map_K\| to disable)
469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1444 `:Evaluate` {expr} evaluate {expr}
469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1445 `:'<,'>Evaluate` evaluate the Visually selected text
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1446
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1447 This is similar to using "print" in the gdb window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1448 You can usually shorten `:Evaluate` to `:Ev`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1449
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1450
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1451 Navigating stack frames ~
ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1452 termdebug-frames :Frame :Up :Down
35443 469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1453 `:Frame` [frame] select frame [frame], which is a frame number,
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1454 address, or function name (default: current frame)
35443 469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1455 `:Up` [count] go up [count] frames (default: 1; the frame that
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1456 called the current)
35443 469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1457 `+` same (see \|termdebug_map_plus\| to disable)
469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1458 `:Down` [count] go down [count] frames (default: 1; the frame called
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1459 by the current)
35443 469c6fb5cb2d runtime(doc): revert unintended formatting changes for termdebug Christian Brabandt <cb@256bit.org> parents: 35391 diff changeset	1460 `-` same (see \|termdebug_map_minus\| to disable)
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1461
ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1462
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1463 Other commands ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1464 termdebug-commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1465 :Gdb jump to the gdb window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1466 :Program jump to the window with the running program
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1467 :Source jump to the window with the source code, create it if there
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1468 isn't one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1469 :Asm jump to the window with the disassembly, create it if there
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1470 isn't one
32921 0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1471 :Var jump to the window with the local and argument variables,
34429 a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1472 create it if there isn't one. This window updates whenever the
a0754587f167 runtime(doc): fix inconsistent indent (#14089) Christian Brabandt <cb@256bit.org> parents: 34396 diff changeset	1473 program is stopped
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1474
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1475 Events ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1476 termdebug-events
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1477 Four autocommands can be used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1478 au User TermdebugStartPre echomsg 'debugging starting'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1479 au User TermdebugStartPost echomsg 'debugging started'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1480 au User TermdebugStopPre echomsg 'debugging stopping'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1481 au User TermdebugStopPost echomsg 'debugging stopped'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1482 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1483 TermdebugStartPre
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1484 TermdebugStartPre Before starting debugging.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1485 Not triggered if the debugger is already
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1486 running or the debugger command cannot be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1487 executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1488 TermdebugStartPost
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1489 TermdebugStartPost After debugging has initialized.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1490 If a "!" bang is passed to `:Termdebug` or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1491 `:TermdebugCommand` the event is triggered
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1492 before running the provided command in gdb.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1493 TermdebugStopPre
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1494 TermdebugStopPre Before debugging ends, when gdb is terminated,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1495 most likely after issuing a "quit" command in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1496 the gdb window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1497 TermdebugStopPost
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1498 TermdebugStopPost After debugging has ended, gdb-related windows
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1499 are closed, debug buffers wiped out and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1500 the state before the debugging was restored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1501
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1502
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1503 Customizing ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1504 termdebug-customizing g:termdebug_config
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1505 In the past several global variables were used for configuration. These are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1506 deprecated and using the g:termdebug_config dictionary is preferred. When
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1507 g:termdebug_config exists the other global variables will NOT be used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1508 The recommended way is to start with an empty dictionary: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1509 let g:termdebug_config = {}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1510
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1511 Then you can add entries to the dictionary as mentioned below. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1512 deprecated global variable names are mentioned for completeness. If you are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1513 switching over to using g:termdebug_config you can find the old variable name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1514 and take over the value, then delete the deprecated variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1515
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1516
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1517 Prompt mode ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1518 termdebug-prompt
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1519 When the \|+terminal\| feature is not supported and on MS-Windows, gdb will run
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1520 in a buffer with 'buftype' set to "prompt". This works slightly differently:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1521 - The gdb window will be in Insert mode while typing commands. Go to Normal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1522 mode with <Esc>, then you can move around in the buffer, copy/paste, etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1523 Go back to editing the gdb command with any command that starts Insert mode,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1524 such as `a` or `i`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1525 - The program being debugged will run in a separate window. On MS-Windows
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1526 this is a new console window. On Unix, if the \|+terminal\| feature is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1527 available a Terminal window will be opened to run the debugged program in.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1528
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1529 termdebug_use_prompt
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1530 Prompt mode can be used even when the \|+terminal\| feature is present with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1531 let g:termdebug_config['use_prompt'] = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1532 If there is no g:termdebug_config you can use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1533 let g:termdebug_use_prompt = 1
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1534
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1535 <
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1536 However, the latter form will be deprecated in future releases.
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1537
33734 55e587f6b02f runtime(termdebug): handle buffer-local mappings properly Christian Brabandt <cb@256bit.org> parents: 33649 diff changeset	1538 Mappings ~
35455 527f6936234c patch 9.1.0497: termdebug can be further improved Christian Brabandt <cb@256bit.org> parents: 35446 diff changeset	1539 The termdebug plugin enables a few default mappings. All those mappings
527f6936234c patch 9.1.0497: termdebug can be further improved Christian Brabandt <cb@256bit.org> parents: 35446 diff changeset	1540 are reset to their original values once the termdebug session concludes.
527f6936234c patch 9.1.0497: termdebug can be further improved Christian Brabandt <cb@256bit.org> parents: 35446 diff changeset	1541
33734 55e587f6b02f runtime(termdebug): handle buffer-local mappings properly Christian Brabandt <cb@256bit.org> parents: 33649 diff changeset	1542 termdebug_map_K termdebug-mappings
33736 2b9192c31108 runtime(doc): fix grammar in termdebug doc, remove trailing spaces (#13505) Christian Brabandt <cb@256bit.org> parents: 33735 diff changeset	1543 The K key is normally mapped to \|:Evaluate\| unless a buffer local (\|:map-local\|)
2b9192c31108 runtime(doc): fix grammar in termdebug doc, remove trailing spaces (#13505) Christian Brabandt <cb@256bit.org> parents: 33735 diff changeset	1544 mapping to K already exists. If you do not want this use: >
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1545 let g:termdebug_config['map_K'] = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1546 If there is no g:termdebug_config you can use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1547 let g:termdebug_map_K = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1548 <
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1549 However, the latter form will be deprecated in future releases.
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1550
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1551 termdebug_map_minus
33736 2b9192c31108 runtime(doc): fix grammar in termdebug doc, remove trailing spaces (#13505) Christian Brabandt <cb@256bit.org> parents: 33735 diff changeset	1552 The - key is normally mapped to \|:Down\| unless a buffer local mapping to the -
2b9192c31108 runtime(doc): fix grammar in termdebug doc, remove trailing spaces (#13505) Christian Brabandt <cb@256bit.org> parents: 33735 diff changeset	1553 key already exists. If you do not want this use: >
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1554 let g:termdebug_config['map_minus'] = 0
ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1555 <
ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1556 termdebug_map_plus
33736 2b9192c31108 runtime(doc): fix grammar in termdebug doc, remove trailing spaces (#13505) Christian Brabandt <cb@256bit.org> parents: 33735 diff changeset	1557 The + key is normally mapped to \|:Up\| unless a buffer local mapping to the +
2b9192c31108 runtime(doc): fix grammar in termdebug doc, remove trailing spaces (#13505) Christian Brabandt <cb@256bit.org> parents: 33735 diff changeset	1558 key already exists. If you do not want this use: >
32971 ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1559 let g:termdebug_config['map_plus'] = 0
ccfca4f03a2b Some more missing changes :( Christian Brabandt <cb@256bit.org> parents: 32921 diff changeset	1560 <
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1561 termdebug_disasm_window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1562 If you want the Asm window shown by default, set the "disasm_window" flag to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1563 1. The "disasm_window_height" entry can be used to set the window height: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1564 let g:termdebug_config['disasm_window'] = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1565 let g:termdebug_config['disasm_window_height'] = 15
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1566 If there is no g:termdebug_config you can use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1567 let g:termdebug_disasm_window = 15
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1568
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1569 However, the latter form will be deprecated in future releases.
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1570
33736 2b9192c31108 runtime(doc): fix grammar in termdebug doc, remove trailing spaces (#13505) Christian Brabandt <cb@256bit.org> parents: 33735 diff changeset	1571 Any value greater than 1 will set the Asm window height to that value.
33735 c6e847116941 runtime(termdebug): improve window handling, shorten var types Christian Brabandt <cb@256bit.org> parents: 33734 diff changeset	1572 If the current window has enough horizontal space, it will be vertically split
c6e847116941 runtime(termdebug): improve window handling, shorten var types Christian Brabandt <cb@256bit.org> parents: 33734 diff changeset	1573 and the Asm window will be shown side by side with the source code window (and
c6e847116941 runtime(termdebug): improve window handling, shorten var types Christian Brabandt <cb@256bit.org> parents: 33734 diff changeset	1574 the height option won't be used).
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1575
32921 0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1576 termdebug_variables_window
33649 88cad94caef9 runtime(doc): Fix typos in several documents (#13420) Christian Brabandt <cb@256bit.org> parents: 33336 diff changeset	1577 If you want the Var window shown by default, set the "variables_window" flag
88cad94caef9 runtime(doc): Fix typos in several documents (#13420) Christian Brabandt <cb@256bit.org> parents: 33336 diff changeset	1578 to 1. The "variables_window_height" entry can be used to set the window
88cad94caef9 runtime(doc): Fix typos in several documents (#13420) Christian Brabandt <cb@256bit.org> parents: 33336 diff changeset	1579 height: >
32921 0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1580 let g:termdebug_config['variables_window'] = 1
0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1581 let g:termdebug_config['variables_window_height'] = 15
0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1582 If there is no g:termdebug_config you can use: >
0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1583 let g:termdebug_variables_window = 15
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1584
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1585 However, the latter form will be deprecated in future releases.
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1586
32921 0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1587 Any value greater than 1 will set the Var window height to that value.
33735 c6e847116941 runtime(termdebug): improve window handling, shorten var types Christian Brabandt <cb@256bit.org> parents: 33734 diff changeset	1588 If the current window has enough horizontal space, it will be vertically split
c6e847116941 runtime(termdebug): improve window handling, shorten var types Christian Brabandt <cb@256bit.org> parents: 33734 diff changeset	1589 and the Var window will be shown side by side with the source code window (and
c6e847116941 runtime(termdebug): improve window handling, shorten var types Christian Brabandt <cb@256bit.org> parents: 33734 diff changeset	1590 the height options won't be used).
32921 0305a7f2b874 Runtime(termdebug): Add support to view local and argument variables Christian Brabandt <cb@256bit.org> parents: 32681 diff changeset	1591
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1592 Communication ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1593 termdebug-communication
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1594 There is another, hidden, buffer, which is used for Vim to communicate with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1595 gdb. The buffer name is "gdb communication". Do not delete this buffer, it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1596 will break the debugger.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1597
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1598 Gdb has some weird behavior, the plugin does its best to work around that.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1599 For example, after typing "continue" in the gdb window a CTRL-C can be used to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1600 interrupt the running program. But after using the MI command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1601 "-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1602 "continue" being used for the `:Continue` command, instead of using the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1603 communication channel.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1604
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1605
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1606 GDB command ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1607 g:termdebugger
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1608 To change the name of the gdb command, set "debugger" entry in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1609 g:termdebug_config or the "g:termdebugger" variable before invoking
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1610 `:Termdebug`: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1611 let g:termdebug_config['command'] = "mygdb"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1612 If there is no g:termdebug_config you can use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1613 let g:termdebugger = "mygdb"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1614
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1615 However, the latter form will be deprecated in future releases.
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1616
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1617 If the command needs an argument use a List: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1618 let g:termdebug_config['command'] = ['rr', 'replay', '--']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1619 If there is no g:termdebug_config you can use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1620 let g:termdebugger = ['rr', 'replay', '--']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1621
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1622 Several arguments will be added to make gdb work well for the debugger.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1623 If you want to modify them, add a function to filter the argument list: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1624 let g:termdebug_config['command_filter'] = MyDebugFilter
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1625
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1626 If you do not want the arguments to be added, but you do need to set the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1627 "pty", use a function to add the necessary arguments: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1628 let g:termdebug_config['command_add_args'] = MyAddArguments
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1629 The function will be called with the list of arguments so far, and a second
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1630 argument that is the name of the pty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1631 gdb-version
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1632 Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI
33336 4541997c3638 runtime(doc): grammar fixes in doc (#13164) Christian Brabandt <cb@256bit.org> parents: 32971 diff changeset	1633 interface. The "new-ui" command requires gdb version 7.12 or later. If you
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1634 get this error:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1635 Undefined command: "new-ui". Try "help".~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1636 Then your gdb is too old.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1637
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1638
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1639 Colors ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1640 hl-debugPC hl-debugBreakpoint
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1641 The color of the signs can be adjusted with these highlight groups:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1642 - debugPC the current position
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1643 - debugBreakpoint a breakpoint
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1644
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1645 The defaults are, when 'background' is "light":
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1646 hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1647 hi debugBreakpoint term=reverse ctermbg=red guibg=red
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1648
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1649 When 'background' is "dark":
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1650 hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1651 hi debugBreakpoint term=reverse ctermbg=red guibg=red
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1652
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1653
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1654 Shortcuts ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1655 termdebug_shortcuts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1656 You can define your own shortcuts (mappings) to control gdb, that can work in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1657 any window, using the TermDebugSendCommand() function. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1658 map ,w :call TermDebugSendCommand('where')<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1659 The argument is the gdb command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1660
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1661
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1662 Popup menu ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1663 termdebug_popup
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1664 By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1665 these entries to the popup menu:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1666 Set breakpoint `:Break`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1667 Clear breakpoint `:Clear`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1668 Evaluate `:Evaluate`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1669 If you don't want this then disable it with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1670 let g:termdebug_config['popup'] = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1671 If there is no g:termdebug_config you can use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1672 let g:termdebug_popup = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1673
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1674 However, the latter form will be deprecated in future releases.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1675
32681 5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1676 Change default signs ~
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1677 termdebug_signs
33761 ffe9ffcb57e7 runtime(termdebug): improve the breakpoint sign label (#13525) Christian Brabandt <cb@256bit.org> parents: 33736 diff changeset	1678 Termdebug uses the hex number of the breakpoint ID in the signcolumn to
ffe9ffcb57e7 runtime(termdebug): improve the breakpoint sign label (#13525) Christian Brabandt <cb@256bit.org> parents: 33736 diff changeset	1679 represent breakpoints. if it is greater than "0xFF", then it will be displayed
ffe9ffcb57e7 runtime(termdebug): improve the breakpoint sign label (#13525) Christian Brabandt <cb@256bit.org> parents: 33736 diff changeset	1680 as "F+", due to we really only have two screen cells for the sign.
32681 5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1681
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1682 If you want to customize the breakpoint signs: >
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1683 let g:termdebug_config['sign'] = '>>'
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1684 If there is no g:terminal_config yet you can use: >
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1685 let g:termdebug_config = {'sign': '>>'}
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1686
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1687 After this, breakpoints will be displayed as `>>` in the signcolumn.
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1688
5a989f229d9b patch 9.0.1671: Termdebug: error with more than 99 breakpoints Bram Moolenaar <Bram@vim.org> parents: 32670 diff changeset	1689
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1690 Window toolbar ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1691 termdebug_winbar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1692 By default the Termdebug plugin creates a window toolbar if the mouse is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1693 enabled (see \|:Winbar\|). If you don't want this then disable it with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1694 let g:termdebug_config['winbar'] = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1695
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1696
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1697 Vim window width ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1698 termdebug_wide
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1699 To change the width of the Vim window when debugging starts and use a vertical
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1700 split: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1701 let g:termdebug_config['wide'] = 163
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1702 If there is no g:termdebug_config you can use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1703 let g:termdebug_wide = 163
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1704
35526 d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1705 However, the latter form will be deprecated in future releases.
d785e0c59ca0 runtime(termdebug): Add Deprecation warnings Christian Brabandt <cb@256bit.org> parents: 35482 diff changeset	1706
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1707 This will set 'columns' to 163 when `:Termdebug` is used. The value is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1708 restored when quitting the debugger.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1709
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1710 If the wide value is set and 'columns' is already a greater value, then a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1711 vertical split will be used without modifying 'columns'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1712
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1713 Set the wide value to 1 to use a vertical split without ever changing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1714 'columns'. This is useful when the terminal can't be resized by Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1715
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1716
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1717 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/terminal.txt @ 35526:d785e0c59ca0