Mercurial > vim

annotate runtime/doc/terminal.txt @ 19584:3aaaa407d308

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added tag v8.2.0348 for changeset ba35daca6553840791b5a4470cf24e1c3fd6cff6
author Bram Moolenaar <Bram@vim.org>
date Mon, 02 Mar 2020 23:00:06 +0100
parents 51bc26d4a393
children d73d982499ae
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
19303
51bc26d4a393 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 19099
diff changeset
1 *terminal.txt* For Vim version 8.2. Last change: 2020 Jan 30
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
2
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
3
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
4 VIM REFERENCE MANUAL by Bram Moolenaar
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
5
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
6
13963
1174611ad715 Vim 8.1 release
Christian Brabandt <cb@256bit.org>
parents: 13912
diff changeset
7 Terminal window support *terminal* *terminal-window*
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
8
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
9
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
10 The terminal feature is optional, use this to check if your Vim has it: >
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
11 echo has('terminal')
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
12 If the result is "1" you have it.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
13
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
14
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
15 1. Basic use |terminal-use|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
16 Typing |terminal-typing|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
17 Size and color |terminal-size-color|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
18 Command syntax |:terminal|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
19 Resizing |terminal-resizing|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
20 Terminal Modes |Terminal-mode|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
21 Cursor style |terminal-cursor-style|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
22 Session |terminal-session|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
23 Special keys |terminal-special-keys|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
24 Unix |terminal-unix|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
25 MS-Windows |terminal-ms-windows|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
26 2. Terminal functions |terminal-function-details|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
27 3. Terminal communication |terminal-communication|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
28 Vim to job: term_sendkeys() |terminal-to-job|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
29 Job to Vim: JSON API |terminal-api|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
30 Using the client-server feature |terminal-client-server|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
31 4. Remote testing |terminal-testing|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
32 5. Diffing screen dumps |terminal-diff|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
33 Writing a screen dump test for Vim |terminal-dumptest|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
34 Creating a screen dump |terminal-screendump|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
35 Comparing screen dumps |terminal-diffscreendump|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
36 6. Debugging |terminal-debug|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
37 Starting |termdebug-starting|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
38 Example session |termdebug-example|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
39 Stepping through code |termdebug-stepping|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
40 Inspecting variables |termdebug-variables|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
41 Other commands |termdebug-commands|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
42 Prompt mode |termdebug-prompt|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
43 Communication |termdebug-communication|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
44 Customizing |termdebug-customizing|
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
45
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
46 {only available when compiled with the |+terminal| feature}
15878
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15844
diff changeset
47 The terminal feature requires the |+job| and |+channel| features.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
48
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
49 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
50 1. Basic use *terminal-use*
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
51
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
52 This feature is for running a terminal emulator in a Vim window. A job can be
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
53 started connected to the terminal emulator. For example, to run a shell: >
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
54 :term bash
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
55
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
56 Or to run build command: >
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
57 :term make myprogram
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
58
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
59 The job runs asynchronously from Vim, the window will be updated to show
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
60 output from the job, also while editing in another window.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
61
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
62
11814
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents: 11774
diff changeset
63 Typing ~
12457
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents: 12455
diff changeset
64 *terminal-typing*
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
65 When the keyboard focus is in the terminal window, typed keys will be sent to
11814
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents: 11774
diff changeset
66 the job. This uses a pty when possible. You can click outside of the
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents: 11774
diff changeset
67 terminal window to move keyboard focus elsewhere.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
68
16023
dc766e1b0c95 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15937
diff changeset
69 *t_CTRL-W_CTRL-W* *t_CTRL-W_:*
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
70 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
12833
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
71 CTRL-W CTRL-W move focus to the next window
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
72 CTRL-W : enter an Ex command
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
73 See |CTRL-W| for more commands.
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
74
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18719
diff changeset
75 Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N*
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
76 CTRL-W . send a CTRL-W to the job in the terminal
13668
6a84e3d2b810 patch 8.0.1706: cannot sent CTRL- to a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13626
diff changeset
77 CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
78 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode|
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
79 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode|
16023
dc766e1b0c95 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15937
diff changeset
80 CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote*
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
81 Also works with the = register to insert the result of
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
82 evaluating an expression.
12160
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
83 CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C|
16023
dc766e1b0c95 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15937
diff changeset
84 CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt*
dc766e1b0c95 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15937
diff changeset
85 CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT*
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
86
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
87 See option 'termwinkey' for specifying another key instead of CTRL-W that
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
88 will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey'
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
89 to the job. For example:
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
90 'termwinkey' CTRL-W move focus to the next window
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
91 'termwinkey' : enter an Ex command
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
92 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal
14109
279465096a16 patch 8.1.0072: use of 'termwinkey' is inconsistent
Christian Brabandt <cb@256bit.org>
parents: 14107
diff changeset
93 'termwinkey' . send 'termwinkey' to the job in the terminal
279465096a16 patch 8.1.0072: use of 'termwinkey' is inconsistent
Christian Brabandt <cb@256bit.org>
parents: 14107
diff changeset
94 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
95 'termwinkey' N go to terminal Normal mode, see below
16023
dc766e1b0c95 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15937
diff changeset
96 'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N|
dc766e1b0c95 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15937
diff changeset
97 'termwinkey' CTRL-C same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C|
11965
a932d3da41c8 patch 8.0.0863: a remote command does not work in the terminal window
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
98 *t_CTRL-\_CTRL-N*
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
99 The special key combination CTRL-\ CTRL-N can be used to switch to Normal
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
100 mode, just like this works in any other mode.
12160
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
101 *t_CTRL-W_CTRL-C*
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
102 CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
103 CTRL-BREAK will also kill the job.
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
104
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
105 If you type CTRL-C the effect depends on what the pty has been configured to
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
106 do. For simple commands this causes a SIGINT to be sent to the job, which
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
107 would end it. Other commands may ignore the SIGINT or handle the CTRL-C
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
108 themselves (like Vim does).
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
109
12457
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents: 12455
diff changeset
110 To change the keys you type use terminal mode mappings, see |:tmap|.
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents: 12455
diff changeset
111 These are defined like any mapping, but apply only when typing keys that are
13482
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
112 sent to the job running in the terminal. For example, to make F1 switch
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
113 to Terminal-Normal mode: >
13482
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
114 tnoremap <F1> <C-W>N
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
115 You can use Esc, but you need to make sure it won't cause other keys to
15131
bc1a8d21c811 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14952
diff changeset
116 break (cursor keys start with an Esc, so they may break): >
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
117 tnoremap <Esc> <C-W>N
13482
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
118 set notimeout ttimeout timeoutlen=100
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
119
14952
405309f9dd13 patch 8.1.0487: no menus specifically for the terminal window
Bram Moolenaar <Bram@vim.org>
parents: 14695
diff changeset
120 You can also create menus similar to terminal mode mappings, but you have to
405309f9dd13 patch 8.1.0487: no menus specifically for the terminal window
Bram Moolenaar <Bram@vim.org>
parents: 14695
diff changeset
121 use |:tlmenu| instead of |:tmenu|.
405309f9dd13 patch 8.1.0487: no menus specifically for the terminal window
Bram Moolenaar <Bram@vim.org>
parents: 14695
diff changeset
122
12756
3b26420fc639 Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents: 12559
diff changeset
123 < *options-in-terminal*
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
124 After opening the terminal window and setting 'buftype' to "terminal" the
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14109
diff changeset
125 TerminalOpen autocommand event is triggered. This makes it possible to set
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
126 options specifically for the window and buffer. Example: >
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14109
diff changeset
127 au TerminalOpen * if &buftype == 'terminal' | setlocal bufhidden=hide | endif
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14109
diff changeset
128 The <abuf> is set to the terminal buffer, but if there is no window (hidden
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14109
diff changeset
129 terminal) then setting options will happen in the wrong buffer, therefore the
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14109
diff changeset
130 check for &buftype in the example.
12457
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents: 12455
diff changeset
131
12907
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim
Christian Brabandt <cb@256bit.org>
parents: 12833
diff changeset
132 Mouse events (click and drag) are passed to the terminal. Mouse move events
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim
Christian Brabandt <cb@256bit.org>
parents: 12833
diff changeset
133 are only passed when Vim itself is receiving them. For a terminal that is
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim
Christian Brabandt <cb@256bit.org>
parents: 12833
diff changeset
134 when 'balloonevalterm' is enabled.
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim
Christian Brabandt <cb@256bit.org>
parents: 12833
diff changeset
135
11814
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents: 11774
diff changeset
136
12160
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
137 Size and color ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
138 *terminal-size-color*
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
139 See option 'termwinsize' for controlling the size of the terminal window.
11659
49c12c93abf3 Updated runtime files and translations.
Christian Brabandt <cb@256bit.org>
parents: 11621
diff changeset
140 (TODO: scrolling when the terminal is larger than the window)
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
141
12455
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
142 The job running in the terminal can change the colors. The default foreground
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
143 and background colors are taken from Vim, the Normal highlight group.
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
144
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
145 For a color terminal the 'background' option is used to decide whether the
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
146 terminal window will start with a white or black background.
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
147
13100
656ab57d1ddc update a few runtime files
Christian Brabandt <cb@256bit.org>
parents: 13051
diff changeset
148 To use a different color the Terminal highlight group can be used, for
656ab57d1ddc update a few runtime files
Christian Brabandt <cb@256bit.org>
parents: 13051
diff changeset
149 example: >
12455
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
150 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
13626
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
151 <
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
152 *g:terminal_ansi_colors*
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
153 In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
13626
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
154 terminal windows may be configured using the variable
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
155 `g:terminal_ansi_colors`, which should be a list of 16 color names or
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
156 hexadecimal color codes, similar to those accepted by |highlight-guifg|. When
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
157 not using GUI colors, the terminal window always uses the 16 ANSI colors of
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
158 the underlying terminal.
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
159 The |term_setansicolors()| function can be used to change the colors, and
ab89131d30e0 patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents: 13592
diff changeset
160 |term_getansicolors()| to get the currently used colors.
12160
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
161
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
162
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
163 Command syntax ~
11774
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
164
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
165 :[range]ter[minal] [options] [command] *:ter* *:terminal*
11774
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
166 Open a new terminal window.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
167
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
168 If [command] is provided run it as a job and connect
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
169 the input and output to the terminal.
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
170 If [command] is not given the 'shell' option is used.
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
171 if [command] is NONE no job is started, the pty of the
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
172 terminal can be used by a command like gdb.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
173
13476
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
174 If [command] is missing the default behavior is to
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
175 close the terminal when the shell exits. This can be
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
176 changed with the ++noclose argument.
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
177 If [command] is present the default behavior is to
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
178 keep the terminal open in Terminal-Normal mode. This
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
179 can be changed with the ++close argument.
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
180
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
181 A new buffer will be created, using [command] or
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
182 'shell' as the name, prefixed with a "!". If a buffer
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
183 by this name already exists a number is added in
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
184 parentheses. E.g. if "gdb" exists the second terminal
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
185 buffer will use "!gdb (1)".
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
186
12192
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job
Christian Brabandt <cb@256bit.org>
parents: 12160
diff changeset
187 If [range] is given the specified lines are used as
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job
Christian Brabandt <cb@256bit.org>
parents: 12160
diff changeset
188 input for the job. It will not be possible to type
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
189 keys in the terminal window. For MS-Windows see the
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
190 ++eof argument below.
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
191
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
192 *term++close* *term++open*
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
193 Supported [options] are:
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
194 ++close The terminal window will close
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
195 automatically when the job terminates.
18402
527b7084c556 patch 8.1.2195: Vim does not exit when the terminal window is last window
Bram Moolenaar <Bram@vim.org>
parents: 18343
diff changeset
196 |terminal-close|
13476
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
197 ++noclose The terminal window will NOT close
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
198 automatically when the job terminates.
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
199 ++open When the job terminates and no window
12064
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
200 shows it, a window will be opened.
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
201 Note that this can be interruptive.
13476
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
202 The last of ++close, ++noclose and ++open
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
203 matters and rules out earlier arguments.
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents: 13438
diff changeset
204
12064
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
205 ++curwin Open the terminal in the current
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
206 window, do not split the current
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
207 window. Fails if the current buffer
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
208 cannot be |abandon|ed.
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
209 ++hidden Open the terminal in a hidden buffer,
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
210 no window will be used.
13437
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
211 ++norestore Do not include this terminal window
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
212 in a session file.
18514
39b0c28fe495 patch 8.1.2251: ":term command" may not work without a shell
Bram Moolenaar <Bram@vim.org>
parents: 18489
diff changeset
213 ++shell Instead of executing {command}
39b0c28fe495 patch 8.1.2251: ":term command" may not work without a shell
Bram Moolenaar <Bram@vim.org>
parents: 18489
diff changeset
214 directly, use a shell, like with
39b0c28fe495 patch 8.1.2251: ":term command" may not work without a shell
Bram Moolenaar <Bram@vim.org>
parents: 18489
diff changeset
215 `:!command` *E279*
39b0c28fe495 patch 8.1.2251: ":term command" may not work without a shell
Bram Moolenaar <Bram@vim.org>
parents: 18489
diff changeset
216 {only works on Unix currently}
13438
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
217 ++kill={how} When trying to close the terminal
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
218 window kill the job with {how}. See
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
219 |term_setkill()| for the values.
12192
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job
Christian Brabandt <cb@256bit.org>
parents: 12160
diff changeset
220 ++rows={height} Use {height} for the terminal window
13125
371ceeebbdaa Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13100
diff changeset
221 height. If the terminal uses the full
371ceeebbdaa Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13100
diff changeset
222 Vim height (no window above or below
14006
665fe1f419b0 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
223 the terminal window) the command line
13125
371ceeebbdaa Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13100
diff changeset
224 height will be reduced as needed.
12192
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job
Christian Brabandt <cb@256bit.org>
parents: 12160
diff changeset
225 ++cols={width} Use {width} for the terminal window
13125
371ceeebbdaa Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13100
diff changeset
226 width. If the terminal uses the full
371ceeebbdaa Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13100
diff changeset
227 Vim width (no window left or right of
371ceeebbdaa Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13100
diff changeset
228 the terminal window) this value is
371ceeebbdaa Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13100
diff changeset
229 ignored.
18170
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
230 ++eof={text} When using [range]: text to send after
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
231 the last line was written. Cannot
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
232 contain white space. A CR is
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
233 appended. For MS-Windows the default
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
234 is to send CTRL-D.
12311
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
235 E.g. for a shell use "++eof=exit" and
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
236 for Python "++eof=exit()". Special
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
237 codes can be used like with `:map`,
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
238 e.g. "<C-Z>" for CTRL-Z.
15746
c017195b121b patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents: 15729
diff changeset
239 ++type={pty} (MS-Windows only): Use {pty} as the
c017195b121b patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents: 15729
diff changeset
240 virtual console. See 'termwintype'
c017195b121b patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents: 15729
diff changeset
241 for the values.
18170
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
242 ++api={expr} Permit the function name starting with
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
243 {expr} to be called as |terminal-api|
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
244 function. If {expr} is empty then no
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
245 function can be called.
15746
c017195b121b patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents: 15729
diff changeset
246
12064
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
247 If you want to use more options use the |term_start()|
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
248 function.
14637
0ecb909e3249 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14519
diff changeset
249 If you want to split the window vertically, use: >
0ecb909e3249 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14519
diff changeset
250 :vertical terminal
0ecb909e3249 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14519
diff changeset
251 < Or short: >
0ecb909e3249 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14519
diff changeset
252 :vert ter
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
253
13438
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
254 When the buffer associated with the terminal is forcibly unloaded or wiped out
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
255 the job is killed, similar to calling `job_stop(job, "kill")` .
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
256 Closing the window normally results in |E947|. When a kill method was set
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
257 with "++kill={how}" or |term_setkill()| then closing the window will use that
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
258 way to kill or interrupt the job. For example: >
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents: 13437
diff changeset
259 :term ++kill=term tail -f /tmp/log
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
260
12267
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents: 12254
diff changeset
261 So long as the job is running the window behaves like it contains a modified
12311
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
262 buffer. Trying to close the window with `CTRL-W :quit` fails. When using
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
263 `CTRL-W :quit!` the job is ended. The text in the window is lost. The buffer
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
264 still exists, but getting it in a window with `:buffer` will show an empty
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
265 buffer.
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
266
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
267 Trying to close the window with `CTRL-W :close` also fails. Using
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 12267
diff changeset
268 `CTRL-W :close!` will close the window and make the buffer hidden.
12267
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents: 12254
diff changeset
269
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents: 12254
diff changeset
270 You can use `CTRL-W :hide` to close the terminal window and make the buffer
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents: 12254
diff changeset
271 hidden, the job keeps running. The `:buffer` command can be used to turn the
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents: 12254
diff changeset
272 current window into a terminal window. If there are unsaved changes this
14006
665fe1f419b0 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
273 fails, use ! to force, as usual.
12064
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
274
18402
527b7084c556 patch 8.1.2195: Vim does not exit when the terminal window is last window
Bram Moolenaar <Bram@vim.org>
parents: 18343
diff changeset
275 *terminal-close*
527b7084c556 patch 8.1.2195: Vim does not exit when the terminal window is last window
Bram Moolenaar <Bram@vim.org>
parents: 18343
diff changeset
276 When the terminal window is closed, e.g. when the shell exits and "++close"
527b7084c556 patch 8.1.2195: Vim does not exit when the terminal window is last window
Bram Moolenaar <Bram@vim.org>
parents: 18343
diff changeset
277 argument was used, and this is the last normal Vim window, then Vim will exit.
527b7084c556 patch 8.1.2195: Vim does not exit when the terminal window is last window
Bram Moolenaar <Bram@vim.org>
parents: 18343
diff changeset
278 This is like using |:quit| in a normal window. Help and preview windows are
527b7084c556 patch 8.1.2195: Vim does not exit when the terminal window is last window
Bram Moolenaar <Bram@vim.org>
parents: 18343
diff changeset
279 not counted.
527b7084c556 patch 8.1.2195: Vim does not exit when the terminal window is last window
Bram Moolenaar <Bram@vim.org>
parents: 18343
diff changeset
280
12064
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
281 To have a background job run without a window, and open the window when it's
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
282 done, use options like this: >
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
283 :term ++hidden ++open make
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
284 Note that the window will open at an unexpected moment, this will interrupt
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
285 what you are doing.
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents: 12031
diff changeset
286
12160
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
287 *E947* *E948*
11967
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents: 11965
diff changeset
288 So long as the job is running, the buffer is considered modified and Vim
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents: 11965
diff changeset
289 cannot be quit easily, see |abandon|.
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
290
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
291 When the job has finished and no changes were made to the buffer: closing the
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
292 window will wipe out the buffer.
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
293
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
294 Before changes can be made to a terminal buffer, the 'modifiable' option must
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
295 be set. This is only possible when the job has finished. At the first change
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
296 the buffer will become a normal buffer and the highlighting is removed.
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
297 You may want to change the buffer name with |:file| to be able to write, since
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
298 the buffer name will still be set to the command.
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
299
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
300
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
301 Resizing ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
302 *terminal-resizing*
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
303 The size of the terminal can be in one of three modes:
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
304
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
305 1. The 'termwinsize' option is empty: The terminal size follows the window
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
306 size. The minimal size is 2 screen lines with 10 cells.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
307
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
308 2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
309 of screen rows and "cols" is the minimal number of cells.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
310
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
311 3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
312 case). The terminal size is fixed to the specified number of screen lines
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
313 and cells. If the window is bigger there will be unused empty space.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
314
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
315 If the window is smaller than the terminal size, only part of the terminal can
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
316 be seen (the lower-left part).
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
317
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
318 The |term_getsize()| function can be used to get the current size of the
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
319 terminal. |term_setsize()| can be used only when in the first or second mode,
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
320 not when 'termwinsize' is "rowsXcols".
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
321
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
322
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
323 Terminal-Job and Terminal-Normal mode ~
13680
c32e9628dc30 patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents: 13668
diff changeset
324 *Terminal-mode* *Terminal-Job*
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
325 When the job is running the contents of the terminal is under control of the
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
326 job. That includes the cursor position. Typed keys are sent to the job.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
327 The terminal contents can change at any time. This is called Terminal-Job
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
328 mode.
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
329
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
330 Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
331 contents of the terminal window is under control of Vim, the job output is
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
332 suspended. CTRL-\ CTRL-N does the same.
12457
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents: 12455
diff changeset
333
12487
3f16cf18386c patch 8.0.1123: cannot define a toolbar for a window
Christian Brabandt <cb@256bit.org>
parents: 12457
diff changeset
334 Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by
12457
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents: 12455
diff changeset
335 |term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are.
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents: 12455
diff changeset
336
13680
c32e9628dc30 patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents: 13668
diff changeset
337 It is not possible to enter Insert mode from Terminal-Job mode.
c32e9628dc30 patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents: 13668
diff changeset
338
c32e9628dc30 patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents: 13668
diff changeset
339 *Terminal-Normal* *E946*
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
340 In Terminal-Normal mode you can move the cursor around with the usual Vim
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
341 commands, Visually mark text, yank text, etc. But you cannot change the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
342 contents of the buffer. The commands that would start insert mode, such as
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
343 'i' and 'a', return to Terminal-Job mode. The window will be updated to show
12487
3f16cf18386c patch 8.0.1123: cannot define a toolbar for a window
Christian Brabandt <cb@256bit.org>
parents: 12457
diff changeset
344 the contents of the terminal. |:startinsert| is ineffective.
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
345
12031
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
346 In Terminal-Normal mode the statusline and window title show "(Terminal)". If
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
347 the job ends while in Terminal-Normal mode this changes to
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents: 11967
diff changeset
348 "(Terminal-finished)".
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
349
13680
c32e9628dc30 patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents: 13668
diff changeset
350 When the job outputs lines in the terminal, such that the contents scrolls off
c32e9628dc30 patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents: 13668
diff changeset
351 the top, those lines are remembered and can be seen in Terminal-Normal mode.
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13706
diff changeset
352 The number of lines is limited by the 'termwinscroll' option. When going over
13912
a9fdf01085a8 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13857
diff changeset
353 this limit, the first 10% of the scrolled lines are deleted and are lost.
12160
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
354
11866
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents: 11814
diff changeset
355
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
356 Cursor style ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
357 *terminal-cursor-style*
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
358 By default the cursor in the terminal window uses a not blinking block. The
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
359 normal xterm escape sequences can be used to change the blinking state and the
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
360 shape. Once focus leaves the terminal window Vim will restore the original
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
361 cursor.
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
362
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
363 An exception is when xterm is started with the "-bc" argument, or another way
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
364 that causes the cursor to blink. This actually means that the blinking flag
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
365 is inverted. Since Vim cannot detect this, the terminal window cursor
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
366 blinking will also be inverted.
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
367
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
368
13437
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
369 Session ~
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
370 *terminal-session*
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
371 A terminal window will be restored when using a session file, if possible and
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
372 wanted.
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
373
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
374 If "terminal" was removed from 'sessionoptions' then no terminal windows will
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
375 be restored.
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
376
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
377 If the job in the terminal was finished the window will not be restored.
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
378
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
379 If the terminal can be restored, the command that was used to open it will be
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
380 used again. To change this use the |term_setrestore()| function. This can
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
381 also be used to not restore a specific terminal by setting the command to
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
382 "NONE".
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
383
02b3f719eacb Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13377
diff changeset
384
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
385 Special keys ~
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
386 *terminal-special-keys*
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
387 Since the terminal emulator simulates an xterm, only escape sequences that
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
388 both Vim and xterm recognize will be available in the terminal window. If you
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
389 want to pass on other escape sequences to the job running in the terminal you
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
390 need to set up forwarding. Example: >
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
391 tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
12833
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
392 func SendToTerm(what)
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
393 call term_sendkeys('', a:what)
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
394 return ''
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
395 endfunc
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
396
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
397
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
398 Unix ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
399 *terminal-unix*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
400 On Unix a pty is used to make it possible to run all kinds of commands. You
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
401 can even run Vim in the terminal! That's used for debugging, see below.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
402
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
403 Environment variables are used to pass information to the running job:
13585
03224283bafc patch 8.0.1665: when running a terminal from the GUI 'term' is not useful
Christian Brabandt <cb@256bit.org>
parents: 13575
diff changeset
404 TERM the name of the terminal, from the 'term' option or
03224283bafc patch 8.0.1665: when running a terminal from the GUI 'term' is not useful
Christian Brabandt <cb@256bit.org>
parents: 13575
diff changeset
405 $TERM in the GUI; falls back to "xterm" if it does not
03224283bafc patch 8.0.1665: when running a terminal from the GUI 'term' is not useful
Christian Brabandt <cb@256bit.org>
parents: 13575
diff changeset
406 start with "xterm"
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
407 ROWS number of rows in the terminal initially
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
408 LINES same as ROWS
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
409 COLUMNS number of columns in the terminal initially
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
410 COLORS number of colors, 't_Co' (256*256*256 in the GUI)
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
411 VIM_SERVERNAME v:servername
14063
f39150ec146e patch 8.1.0049: shell cannot tell running in a terminal window
Christian Brabandt <cb@256bit.org>
parents: 14006
diff changeset
412 VIM_TERMINAL v:version
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 11866
diff changeset
413
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
414
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
415 MS-Windows ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
416 *terminal-ms-windows*
11774
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
417 On MS-Windows winpty is used to make it possible to run all kind of commands.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
418 Obviously, they must be commands that run in a terminal, not open their own
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
419 window.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
420
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
421 You need the following two files from winpty:
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
422
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
423 winpty.dll
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
424 winpty-agent.exe
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
425
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
426 You can download them from the following page:
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
427
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
428 https://github.com/rprichard/winpty
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
429
12160
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
430 Just put the files somewhere in your PATH. You can set the 'winptydll' option
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
431 to point to the right file, if needed. If you have both the 32-bit and 64-bit
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
432 version, rename to winpty32.dll and winpty64.dll to match the way Vim was
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents: 12064
diff changeset
433 build.
15844
63e71d195cee patch 8.1.0929: no error when requesting ConPTY but it's not available
Bram Moolenaar <Bram@vim.org>
parents: 15746
diff changeset
434 *ConPTY* *E982*
15725
a3e2e7948ee4 patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents: 15131
diff changeset
435 On more recent versions of MS-Windows 10 (beginning with the "October 2018
a3e2e7948ee4 patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents: 15131
diff changeset
436 Update"), winpty is no longer required. On those versions, |:terminal| will use
a3e2e7948ee4 patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents: 15131
diff changeset
437 Windows' built-in support for hosting terminal applications, "ConPTY". When
a3e2e7948ee4 patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents: 15131
diff changeset
438 ConPTY is in use, there may be rendering artifacts regarding ambiguous-width
15844
63e71d195cee patch 8.1.0929: no error when requesting ConPTY but it's not available
Bram Moolenaar <Bram@vim.org>
parents: 15746
diff changeset
439 characters. If you encounter any such issues, install "winpty". Until the
63e71d195cee patch 8.1.0929: no error when requesting ConPTY but it's not available
Bram Moolenaar <Bram@vim.org>
parents: 15746
diff changeset
440 ConPTY problems have been fixed "winpty" will be preferred.
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
441
12907
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim
Christian Brabandt <cb@256bit.org>
parents: 12833
diff changeset
442 Environment variables are used to pass information to the running job:
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim
Christian Brabandt <cb@256bit.org>
parents: 12833
diff changeset
443 VIM_SERVERNAME v:servername
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim
Christian Brabandt <cb@256bit.org>
parents: 12833
diff changeset
444
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
445
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
446 ==============================================================================
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
447 2. Terminal functions *terminal-function-details*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
448
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
449 *term_dumpdiff()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
450 term_dumpdiff({filename}, {filename} [, {options}])
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
451 Open a new window displaying the difference between the two
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
452 files. The files must have been created with
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
453 |term_dumpwrite()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
454 Returns the buffer number or zero when the diff fails.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
455 Also see |terminal-diff|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
456 NOTE: this does not work with double-width characters yet.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
457
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
458 The top part of the buffer contains the contents of the first
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
459 file, the bottom part of the buffer contains the contents of
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
460 the second file. The middle part shows the differences.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
461 The parts are separated by a line of equals.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
462
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
463 If the {options} argument is present, it must be a Dict with
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
464 these possible members:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
465 "term_name" name to use for the buffer name, instead
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
466 of the first file name.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
467 "term_rows" vertical size to use for the terminal,
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
468 instead of using 'termwinsize'
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
469 "term_cols" horizontal size to use for the terminal,
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
470 instead of using 'termwinsize'
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
471 "vertical" split the window vertically
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
472 "curwin" use the current window, do not split the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
473 window; fails if the current buffer
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
474 cannot be |abandon|ed
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
475 "bufnr" do not create a new buffer, use the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
476 existing buffer "bufnr". This buffer
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
477 must have been previously created with
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
478 term_dumpdiff() or term_dumpload() and
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
479 visible in a window.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
480 "norestore" do not add the terminal window to a
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
481 session file
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
482
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
483 Each character in the middle part indicates a difference. If
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
484 there are multiple differences only the first in this list is
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
485 used:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
486 X different character
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
487 w different width
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
488 f different foreground color
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
489 b different background color
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
490 a different attribute
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
491 + missing position in first file
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
492 - missing position in second file
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
493
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
494 Using the "s" key the top and bottom parts are swapped. This
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
495 makes it easy to spot a difference.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
496
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
497 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
498 GetFilename()->term_dumpdiff(otherfile)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
499 <
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
500 *term_dumpload()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
501 term_dumpload({filename} [, {options}])
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
502 Open a new window displaying the contents of {filename}
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
503 The file must have been created with |term_dumpwrite()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
504 Returns the buffer number or zero when it fails.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
505 Also see |terminal-diff|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
506
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
507 For {options} see |term_dumpdiff()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
508
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
509 Can also be used as a |method|: >
18343
375a7ecdb351 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18170
diff changeset
510 GetFilename()->term_dumpload()
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
511 <
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
512 *term_dumpwrite()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
513 term_dumpwrite({buf}, {filename} [, {options}])
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
514 Dump the contents of the terminal screen of {buf} in the file
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
515 {filename}. This uses a format that can be used with
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
516 |term_dumpload()| and |term_dumpdiff()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
517 If the job in the terminal already finished an error is given:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
518 *E958*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
519 If {filename} already exists an error is given: *E953*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
520 Also see |terminal-diff|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
521
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
522 {options} is a dictionary with these optional entries:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
523 "rows" maximum number of rows to dump
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
524 "columns" maximum number of columns to dump
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
525
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
526 Can also be used as a |method|, the base is used for the file
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
527 name: >
18343
375a7ecdb351 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18170
diff changeset
528 GetFilename()->term_dumpwrite(bufnr)
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
529
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
530 term_getaltscreen({buf}) *term_getaltscreen()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
531 Returns 1 if the terminal of {buf} is using the alternate
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
532 screen.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
533 {buf} is used as with |term_getsize()|.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
534
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
535 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
536 GetBufnr()->term_getaltscreen()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
537
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
538
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
539 term_getansicolors({buf}) *term_getansicolors()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
540 Get the ANSI color palette in use by terminal {buf}.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
541 Returns a List of length 16 where each element is a String
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
542 representing a color in hexadecimal "#rrggbb" format.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
543 Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
544 If neither was used returns the default colors.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
545
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
546 {buf} is used as with |term_getsize()|. If the buffer does not
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
547 exist or is not a terminal window, an empty list is returned.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
548
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
549 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
550 GetBufnr()->term_getansicolors()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
551
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
552 < {only available when compiled with GUI enabled and/or the
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
553 |+termguicolors| feature}
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
554
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
555 term_getattr({attr}, {what}) *term_getattr()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
556 Given {attr}, a value returned by term_scrape() in the "attr"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
557 item, return whether {what} is on. {what} can be one of:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
558 bold
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
559 italic
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
560 underline
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
561 strike
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
562 reverse
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
563
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
564 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
565 GetAttr()->term_getattr()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
566
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
567
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
568 term_getcursor({buf}) *term_getcursor()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
569 Get the cursor position of terminal {buf}. Returns a list with
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
570 two numbers and a dictionary: [row, col, dict].
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
571
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
572 "row" and "col" are one based, the first screen cell is row
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
573 1, column 1. This is the cursor position of the terminal
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
574 itself, not of the Vim window.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
575
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
576 "dict" can have these members:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
577 "visible" one when the cursor is visible, zero when it
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
578 is hidden.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
579 "blink" one when the cursor is blinking, zero when it
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
580 is not blinking.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
581 "shape" 1 for a block cursor, 2 for underline and 3
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
582 for a vertical bar.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
583 "color" color of the cursor, e.g. "green"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
584
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
585 {buf} must be the buffer number of a terminal window. If the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
586 buffer does not exist or is not a terminal window, an empty
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
587 list is returned.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
588
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
589 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
590 GetBufnr()->term_getcursor()
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
591
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
592 term_getjob({buf}) *term_getjob()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
593 Get the Job associated with terminal window {buf}.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
594 {buf} is used as with |term_getsize()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
595 Returns |v:null| when there is no job.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
596
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
597 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
598 GetBufnr()->term_getjob()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
599
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
600
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
601 term_getline({buf}, {row}) *term_getline()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
602 Get a line of text from the terminal window of {buf}.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
603 {buf} is used as with |term_getsize()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
604
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
605 The first line has {row} one. When {row} is "." the cursor
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
606 line is used. When {row} is invalid an empty string is
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
607 returned.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
608
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
609 To get attributes of each character use |term_scrape()|.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
610
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
611 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
612 GetBufnr()->term_getline(row)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
613
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
614
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
615 term_getscrolled({buf}) *term_getscrolled()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
616 Return the number of lines that scrolled to above the top of
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
617 terminal {buf}. This is the offset between the row number
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
618 used for |term_getline()| and |getline()|, so that: >
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
619 term_getline(buf, N)
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
620 < is equal to: >
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
621 getline(N + term_getscrolled(buf))
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
622 < (if that line exists).
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
623
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
624 {buf} is used as with |term_getsize()|.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
625
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
626 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
627 GetBufnr()->term_getscrolled()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
628
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
629
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
630 term_getsize({buf}) *term_getsize()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
631 Get the size of terminal {buf}. Returns a list with two
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
632 numbers: [rows, cols]. This is the size of the terminal, not
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
633 the window containing the terminal.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
634
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
635 {buf} must be the buffer number of a terminal window. Use an
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
636 empty string for the current buffer. If the buffer does not
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
637 exist or is not a terminal window, an empty list is returned.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
638
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
639 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
640 GetBufnr()->term_getsize()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
641
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
642
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
643 term_getstatus({buf}) *term_getstatus()*
19099
1a951a4beee3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
644 Get the status of terminal {buf}. This returns a String with
1a951a4beee3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
645 a comma separated list of these items:
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
646 running job is running
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
647 finished job has finished
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
648 normal in Terminal-Normal mode
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
649 One of "running" or "finished" is always present.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
650
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
651 {buf} must be the buffer number of a terminal window. If the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
652 buffer does not exist or is not a terminal window, an empty
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
653 string is returned.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
654
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
655 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
656 GetBufnr()->term_getstatus()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
657
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
658
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
659 term_gettitle({buf}) *term_gettitle()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
660 Get the title of terminal {buf}. This is the title that the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
661 job in the terminal has set.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
662
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
663 {buf} must be the buffer number of a terminal window. If the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
664 buffer does not exist or is not a terminal window, an empty
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
665 string is returned.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
666
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
667 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
668 GetBufnr()->term_gettitle()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
669
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
670
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
671 term_gettty({buf} [, {input}]) *term_gettty()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
672 Get the name of the controlling terminal associated with
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
673 terminal window {buf}. {buf} is used as with |term_getsize()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
674
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
675 When {input} is omitted or 0, return the name for writing
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
676 (stdout). When {input} is 1 return the name for reading
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
677 (stdin). On UNIX, both return same name.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
678
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
679 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
680 GetBufnr()->term_gettty()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
681
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
682
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
683 term_list() *term_list()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
684 Return a list with the buffer numbers of all buffers for
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
685 terminal windows.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
686
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
687
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
688 term_scrape({buf}, {row}) *term_scrape()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
689 Get the contents of {row} of terminal screen of {buf}.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
690 For {buf} see |term_getsize()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
691
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
692 The first line has {row} one. When {row} is "." the cursor
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
693 line is used. When {row} is invalid an empty string is
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
694 returned.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
695
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
696 Return a List containing a Dict for each screen cell:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
697 "chars" character(s) at the cell
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
698 "fg" foreground color as #rrggbb
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
699 "bg" background color as #rrggbb
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
700 "attr" attributes of the cell, use |term_getattr()|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
701 to get the individual flags
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
702 "width" cell width: 1 or 2
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
703
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
704 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
705 GetBufnr()->term_scrape(row)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
706
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
707
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
708 term_sendkeys({buf}, {keys}) *term_sendkeys()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
709 Send keystrokes {keys} to terminal {buf}.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
710 {buf} is used as with |term_getsize()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
711
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
712 {keys} are translated as key sequences. For example, "\<c-x>"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
713 means the character CTRL-X.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
714
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
715 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
716 GetBufnr()->term_sendkeys(keys)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
717
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
718
18170
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
719 term_setapi({buf}, {expr}) *term_setapi()*
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
720 Set the function name prefix to be used for the |terminal-api|
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
721 function in terminal {buf}. For example: >
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
722 :call term_setapi(buf, "Myapi_")
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
723 :call term_setapi(buf, "")
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
724 <
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
725 The default is "Tapi_". When {expr} is an empty string then
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
726 no |terminal-api| function can be used for {buf}.
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
727
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
728 term_setansicolors({buf}, {colors}) *term_setansicolors()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
729 Set the ANSI color palette used by terminal {buf}.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
730 {colors} must be a List of 16 valid color names or hexadecimal
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
731 color codes, like those accepted by |highlight-guifg|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
732 Also see |term_getansicolors()| and |g:terminal_ansi_colors|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
733
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
734 The colors normally are:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
735 0 black
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
736 1 dark red
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
737 2 dark green
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
738 3 brown
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
739 4 dark blue
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
740 5 dark magenta
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
741 6 dark cyan
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
742 7 light grey
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
743 8 dark grey
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
744 9 red
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
745 10 green
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
746 11 yellow
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
747 12 blue
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
748 13 magenta
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
749 14 cyan
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
750 15 white
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
751
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
752 These colors are used in the GUI and in the terminal when
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
753 'termguicolors' is set. When not using GUI colors (GUI mode
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
754 or 'termguicolors'), the terminal window always uses the 16
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
755 ANSI colors of the underlying terminal.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
756
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
757 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
758 GetBufnr()->term_setansicolors(colors)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
759
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
760 < {only available with GUI enabled and/or the |+termguicolors|
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
761 feature}
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
762
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
763 term_setkill({buf}, {how}) *term_setkill()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
764 When exiting Vim or trying to close the terminal window in
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
765 another way, {how} defines whether the job in the terminal can
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
766 be stopped.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
767 When {how} is empty (the default), the job will not be
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
768 stopped, trying to exit will result in |E947|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
769 Otherwise, {how} specifies what signal to send to the job.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
770 See |job_stop()| for the values.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
771
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
772 After sending the signal Vim will wait for up to a second to
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
773 check that the job actually stopped.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
774
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
775 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
776 GetBufnr()->term_setkill(how)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
777
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
778
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
779 term_setrestore({buf}, {command}) *term_setrestore()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
780 Set the command to write in a session file to restore the job
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
781 in this terminal. The line written in the session file is: >
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
782 terminal ++curwin ++cols=%d ++rows=%d {command}
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
783 < Make sure to escape the command properly.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
784
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
785 Use an empty {command} to run 'shell'.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
786 Use "NONE" to not restore this window.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
787
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
788 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
789 GetBufnr()->term_setrestore(command)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
790
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
791
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
792 term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
793 Set the size of terminal {buf}. The size of the window
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
794 containing the terminal will also be adjusted, if possible.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
795 If {rows} or {cols} is zero or negative, that dimension is not
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
796 changed.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
797
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
798 {buf} must be the buffer number of a terminal window. Use an
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
799 empty string for the current buffer. If the buffer does not
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
800 exist or is not a terminal window, an error is given.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
801
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
802 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
803 GetBufnr()->term_setsize(rows, cols)
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
804
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
805
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
806 term_start({cmd} [, {options}]) *term_start()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
807 Open a terminal window and run {cmd} in it.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
808
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
809 {cmd} can be a string or a List, like with |job_start()|. The
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
810 string "NONE" can be used to open a terminal window without
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
811 starting a job, the pty of the terminal can be used by a
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
812 command like gdb.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
813
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
814 Returns the buffer number of the terminal window. If {cmd}
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
815 cannot be executed the window does open and shows an error
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
816 message.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
817 If opening the window fails zero is returned.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
818
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
819 {options} are similar to what is used for |job_start()|, see
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
820 |job-options|. However, not all options can be used. These
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
821 are supported:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
822 all timeout options
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
823 "stoponexit", "cwd", "env"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
824 "callback", "out_cb", "err_cb", "exit_cb", "close_cb"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
825 "in_io", "in_top", "in_bot", "in_name", "in_buf"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
826 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
827 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
828 However, at least one of stdin, stdout or stderr must be
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
829 connected to the terminal. When I/O is connected to the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
830 terminal then the callback function for that part is not used.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
831
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
832 There are extra options:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
833 "term_name" name to use for the buffer name, instead
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
834 of the command name.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
835 "term_rows" vertical size to use for the terminal,
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
836 instead of using 'termwinsize'
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
837 "term_cols" horizontal size to use for the terminal,
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
838 instead of using 'termwinsize'
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
839 "vertical" split the window vertically; note that
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
840 other window position can be defined with
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
841 command modifiers, such as |:belowright|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
842 "curwin" use the current window, do not split the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
843 window; fails if the current buffer
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
844 cannot be |abandon|ed
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
845 "hidden" do not open a window
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
846 "norestore" do not add the terminal window to a
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
847 session file
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
848 "term_kill" what to do when trying to close the
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
849 terminal window, see |term_setkill()|
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
850 "term_finish" What to do when the job is finished:
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
851 "close": close any windows
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
852 "open": open window if needed
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
853 Note that "open" can be interruptive.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
854 See |term++close| and |term++open|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
855 "term_opencmd" command to use for opening the window when
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
856 "open" is used for "term_finish"; must
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
857 have "%d" where the buffer number goes,
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
858 e.g. "10split|buffer %d"; when not
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
859 specified "botright sbuf %d" is used
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
860 "eof_chars" Text to send after all buffer lines were
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
861 written to the terminal. When not set
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
862 CTRL-D is used on MS-Windows. For Python
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
863 use CTRL-Z or "exit()". For a shell use
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
864 "exit". A CR is always added.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
865 "ansi_colors" A list of 16 color names or hex codes
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
866 defining the ANSI palette used in GUI
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
867 color modes. See |g:terminal_ansi_colors|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
868 "tty_type" (MS-Windows only): Specify which pty to
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
869 use. See 'termwintype' for the values.
18170
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
870 "term_api" function name prefix for the
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
871 |terminal-api| function. See
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
872 |term_setapi()|.
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
873
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
874 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
875 GetCommand()->term_start()
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
876
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
877
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
878 term_wait({buf} [, {time}]) *term_wait()*
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
879 Wait for pending updates of {buf} to be handled.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
880 {buf} is used as with |term_getsize()|.
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
881 {time} is how long to wait for updates to arrive in msec. If
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
882 not set then 10 msec will be used.
18033
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
883
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
884 Can also be used as a |method|: >
049a7481d737 patch 8.1.2012: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17259
diff changeset
885 GetBufnr()->term_wait()
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
886
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
887 ==============================================================================
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
888 3. Terminal communication *terminal-communication*
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
889
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
890 There are several ways to communicate with the job running in a terminal:
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
891 - Use |term_sendkeys()| to send text and escape sequences from Vim to the job.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
892 - Use the JSON API to send encoded commands from the job to Vim.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
893 - Use the |client-server| mechanism. This works on machines with an X server
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
894 and on MS-Windows.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
895
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
896
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
897 Vim to job: term_sendkeys() ~
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
898 *terminal-to-job*
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
899 This allows for remote controlling the job running in the terminal. It is a
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
900 one-way mechanism. The job can update the display to signal back to Vim.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
901 For example, if a shell is running in a terminal, you can do: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
902 call term_sendkeys(buf, "ls *.java\<CR>")
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
903
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
904 This requires for the job to be in the right state where it will do the right
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
905 thing when receiving the keys. For the above example, the shell must be
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
906 waiting for a command to be typed.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
907
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
908 For a job that was written for the purpose, you can use the JSON API escape
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
909 sequence in the other direction. E.g.: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
910 call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
911
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
912
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
913 Job to Vim: JSON API ~
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
914 *terminal-api*
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
915 The job can send JSON to Vim, using a special escape sequence. The JSON
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
916 encodes a command that Vim understands. Example of such a message: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
917 <Esc>]51;["drop", "README.md"]<07>
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
918
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
919 The body is always a list, making it easy to find the end: ]<07>.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
920 The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
921 similar to what we are doing here.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
922
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
923 Currently supported commands:
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
924
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
925 call {funcname} {argument}
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
926
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
927 Call a user defined function with {argument}.
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
928 The function is called with two arguments: the buffer number
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18719
diff changeset
929 of the terminal and {argument}, the decoded JSON argument.
18170
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
930 By default, the function name must start with "Tapi_" to avoid
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
931 accidentally calling a function not meant to be used for the
18170
4ac8161e92e0 patch 8.1.2080: the terminal API is limited and can't be disabled
Bram Moolenaar <Bram@vim.org>
parents: 18130
diff changeset
932 terminal API. This can be changed with |term_setapi()|.
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
933 The user function should sanity check the argument.
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
934 The function can use |term_sendkeys()| to send back a reply.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
935 Example in JSON: >
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
936 ["call", "Tapi_Impression", ["play", 14]]
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
937 < Calls a function defined like this: >
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
938 function Tapi_Impression(bufnum, arglist)
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
939 if len(a:arglist) == 2
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
940 echomsg "impression " . a:arglist[0]
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
941 echomsg "count " . a:arglist[1]
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
942 endif
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
943 endfunc
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
944 < Output from `:echo` may be erased by a redraw, use `:echomsg`
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
945 to be able to see it with `:messages`.
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
946
13575
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
947 drop {filename} [options]
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
948
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
949 Let Vim open a file, like the `:drop` command. If {filename}
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
950 is already open in a window, switch to that window. Otherwise
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
951 open a new window to edit {filename}.
13857
e751b5c9dff3 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13735
diff changeset
952 Note that both the job and Vim may change the current
e751b5c9dff3 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13735
diff changeset
953 directory, thus it's best to use the full path.
13575
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
954
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
955 [options] is only used when opening a new window. If present,
16808
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
956 it must be a Dict. Similarly to |++opt|, These entries are
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
957 recognized:
13575
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
958 "ff" file format: "dos", "mac" or "unix"
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
959 "fileformat" idem
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
960 "enc" overrides 'fileencoding'
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
961 "encoding" idem
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
962 "bin" sets 'binary'
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
963 "binary" idem
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
964 "nobin" resets 'binary'
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
965 "nobinary" idem
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
966 "bad" specifies behavior for bad characters, see
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
967 |++bad|
4df23d9bad47 patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents: 13563
diff changeset
968
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
969 Example in JSON: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
970 ["drop", "path/file.txt", {"ff": "dos"}]
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
971
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
972 A trick to have Vim send this escape sequence: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
973 exe "set t_ts=\<Esc>]51; t_fs=\x07"
13547
87a9c1be0ae3 patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents: 13535
diff changeset
974 let &titlestring = '["call","Tapi_TryThis",["hello",123]]'
13535
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
975 redraw
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
976 set t_ts& t_fs&
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
977
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
978 Rationale: Why not allow for any command or expression? Because that might
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
979 create a security problem.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
980
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
981
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
982 Using the client-server feature ~
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
983 *terminal-client-server*
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
984 This only works when v:servername is not empty. If needed you can set it,
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
985 before opening the terminal, with: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
986 call remote_startserver('vim-server')
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
987
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
988 $VIM_SERVERNAME is set in the terminal to pass on the server name.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
989
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
990 In the job you can then do something like: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
991 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
992 This will open the file "some_file.c" and put the cursor on line 123.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
993
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents: 13482
diff changeset
994 ==============================================================================
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
995 4. Remote testing *terminal-testing*
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
996
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
997 Most Vim tests execute a script inside Vim. For some tests this does not
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
998 work, running the test interferes with the code being tested. To avoid this
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
999 Vim is executed in a terminal window. The test sends keystrokes to it and
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1000 inspects the resulting screen state.
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1001
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1002 Functions ~
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1003
14249
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1004 |term_sendkeys()| send keystrokes to a terminal (not subject to tmap)
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1005 |term_wait()| wait for screen to be updated
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1006 |term_scrape()| inspect terminal screen
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1007
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1008
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1009 ==============================================================================
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
1010 5. Diffing screen dumps *terminal-diff*
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1011
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1012 In some cases it can be bothersome to test that Vim displays the right
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1013 characters on the screen. E.g. with syntax highlighting. To make this
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1014 simpler it is possible to take a screen dump of a terminal and compare it to
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1015 an expected screen dump.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1016
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1017 Vim uses the window size, text, color and other attributes as displayed. The
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1018 Vim screen size, font and other properties do not matter. Therefore this
13482
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
1019 mechanism is portable across systems. A conventional screenshot would reflect
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1020 all differences, including font size and family.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1021
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1022
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1023 Writing a screen dump test for Vim ~
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1024 *terminal-dumptest*
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1025 For an example see the Test_syntax_c() function in
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1026 src/testdir/test_syntax.vim. The main parts are:
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1027 - Write a file you want to test with. This is useful for testing syntax
19303
51bc26d4a393 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 19099
diff changeset
1028 highlighting. You can also start Vim with an empty buffer.
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1029 - Run Vim in a terminal with a specific size. The default is 20 lines of 75
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1030 characters. This makes sure the dump is always this size. The function
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1031 RunVimInTerminal() takes care of this. Pass it the arguments for the Vim
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1032 command.
14249
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1033 - Send any commands to Vim using |term_sendkeys()|. For example: >
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1034 call term_sendkeys(buf, ":echo &lines &columns\<CR>")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1035 - Check that the screen is now in the expected state, using
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1036 VerifyScreenDump(). This expects the reference screen dump to be in the
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1037 src/testdir/dumps/ directory. Pass the name without ".dump". It is
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1038 recommended to use the name of the test function and a sequence number, so
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1039 that we know what test is using the file.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1040 - Repeat sending commands and checking the state.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1041 - Finally stop Vim by calling StopVimInTerminal().
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1042
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1043 The first time you do this you won't have a screen dump yet. Create an empty
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1044 file for now, e.g.: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1045 touch src/testdir/dumps/Test_function_name_01.dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1046
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1047 The test will then fail, giving you the command to compare the reference dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1048 and the failed dump, e.g.: >
18719
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 18594
diff changeset
1049 call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump")
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1050
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1051 Use this command in Vim, with the current directory set to src/testdir.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1052 Once you are satisfied with the test, move the failed dump in place of the
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1053 reference: >
18719
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 18594
diff changeset
1054 :!mv failed/Test_func.dump dumps/Test_func.dump
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1055
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1056
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1057 Creating a screen dump ~
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1058 *terminal-screendump*
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1059
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1060 To create the screen dump, run Vim (or any other program) in a terminal and
14249
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1061 make it show the desired state. Then use the |term_dumpwrite()| function to
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1062 create a screen dump file. For example: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1063 :call term_dumpwrite(77, "mysyntax.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1064
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1065 Here "77" is the buffer number of the terminal. Use `:ls!` to see it.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1066
14249
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1067 You can view the screen dump with |term_dumpload()|: >
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1068 :call term_dumpload("mysyntax.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1069
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1070 To verify that Vim still shows exactly the same screen, run Vim again with
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1071 exactly the same way to show the desired state. Then create a screen dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1072 again, using a different file name: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1073 :call term_dumpwrite(88, "test.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1074
14249
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1075 To assert that the files are exactly the same use |assert_equalfile()|: >
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1076 call assert_equalfile("mysyntax.dump", "test.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1077
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1078 If there are differences then v:errors will contain the error message.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1079
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1080
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1081 Comparing screen dumps ~
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1082 *terminal-diffscreendump*
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1083
14249
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1084 |assert_equalfile()| does not make it easy to see what is different.
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1085 To spot the problem use |term_dumpdiff()|: >
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1086 call term_dumpdiff("mysyntax.dump", "test.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1087
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1088 This will open a window consisting of three parts:
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1089 1. The contents of the first dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1090 2. The difference between the first and second dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1091 3. The contents of the second dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1092
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1093 You can usually see what differs in the second part. Use the 'ruler' to
14695
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1094 relate it to the position in the first or second dump. Letters indicate the
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1095 kind of difference:
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1096 X different character
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1097 > cursor in first but not in second
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1098 < cursor in second but not in first
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1099 w character width differs (single vs double width)
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1100 f foreground color differs
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1101 b background color differs
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1102 a attribute differs (bold, underline, reverse, etc.)
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1103 ? character missing in both
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1104 + character missing in first
b178e2039b2d Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14637
diff changeset
1105 - character missing in second
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1106
13482
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
1107 Alternatively, press "s" to swap the first and second dump. Do this several
13304
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1108 times so that you can spot the difference in the context of the text.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1109
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents: 13125
diff changeset
1110 ==============================================================================
17259
6dbb9b3c53e2 patch 8.1.1629: terminal function help is in the wrong file
Bram Moolenaar <Bram@vim.org>
parents: 16871
diff changeset
1111 6. Debugging *terminal-debug* *terminal-debugger*
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1112
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1113 The Terminal debugging plugin can be used to debug a program with gdb and view
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1114 the source code in a Vim window. Since this is completely contained inside
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1115 Vim this also works remotely over an ssh connection.
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1116
14107
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1117 When the |+terminal| feature is missing, the plugin will use the "prompt"
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1118 buffer type, if possible. The running program will then use a newly opened
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1119 terminal window. See |termdebug-prompt| below for details.
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1120
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1121
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1122 Starting ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
1123 *termdebug-starting*
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
1124 Load the plugin with this command: >
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
1125 packadd termdebug
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1126 < *:Termdebug*
14519
5c5908e81e93 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1127 To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1128 command name, for example: >
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1129 :Termdebug vim
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1130
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
1131 This opens two windows:
13051
a6d3e2081544 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12907
diff changeset
1132
12425
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1133 gdb window A terminal window in which "gdb vim" is executed. Here you
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1134 can directly interact with gdb. The buffer name is "!gdb".
13051
a6d3e2081544 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12907
diff changeset
1135
12425
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1136 program window A terminal window for the executed program. When "run" is
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1137 used in gdb the program I/O will happen in this window, so
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1138 that it does not interfere with controlling gdb. The buffer
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1139 name is "gdb program".
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1140
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1141 The current window is used to show the source code. When gdb pauses the
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1142 source file location will be displayed, if possible. A sign is used to
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18719
diff changeset
1143 highlight the current position, using highlight group debugPC.
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1144
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1145 If the buffer in the current window is modified, another window will be opened
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1146 to display the current gdb position. You can use `:Winbar` to add a window
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1147 toolbar there.
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1148
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1149 Focus the terminal of the executed program to interact with it. This works
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1150 the same as any command running in a terminal window.
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
1151
12425
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1152 When the debugger ends, typically by typing "quit" in the gdb window, the two
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1153 opened windows are closed.
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1154
13682
fc660a6ef37d patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents: 13680
diff changeset
1155 Only one debugger can be active at a time.
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1156 *:TermdebugCommand*
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1157 If you want to give specific commands to the command being debugged, you can
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1158 use the `:TermdebugCommand` command followed by the command name and
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1159 additional parameters. >
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1160 :TermdebugCommand vim --clean -c ':set nu'
13682
fc660a6ef37d patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents: 13680
diff changeset
1161
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1162 Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1163 argument to start the command right away, without pausing at the gdb window
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1164 (and cursor will be in the debugged window). For example: >
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1165 :TermdebugCommand! vim --clean
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1166
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1167 To attach gdb to an already running executable or use a core file, pass extra
13682
fc660a6ef37d patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents: 13680
diff changeset
1168 arguments. E.g.: >
fc660a6ef37d patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents: 13680
diff changeset
1169 :Termdebug vim core
fc660a6ef37d patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents: 13680
diff changeset
1170 :Termdebug vim 98343
fc660a6ef37d patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents: 13680
diff changeset
1171
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1172 If no argument is given, you'll end up in a gdb window, in which you need to
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1173 specify which command to run using e.g. the gdb `file` command.
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1174
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
1175
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1176 Example session ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
1177 *termdebug-example*
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1178 Start in the Vim "src" directory and build Vim: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1179 % make
18489
1cd44535be32 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18456
diff changeset
1180 Make sure that debug symbols are present, usually that means that $CFLAGS
1cd44535be32 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18456
diff changeset
1181 includes "-g".
1cd44535be32 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18456
diff changeset
1182
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1183 Start Vim: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1184 % ./vim
18489
1cd44535be32 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18456
diff changeset
1185
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1186 Load the termdebug plugin and start debugging Vim: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1187 :packadd termdebug
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1188 :Termdebug vim
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1189 You should now have three windows:
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1190 source - where you started, has a window toolbar with buttons
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1191 gdb - you can type gdb commands here
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1192 program - the executed program will use this window
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1193
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1194 You can use CTRL-W CTRL-W or the mouse to move focus between windows.
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1195 Put focus on the gdb window and type: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1196 break ex_help
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1197 run
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1198 Vim will start running in the program window. Put focus there and type: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1199 :help gui
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18719
diff changeset
1200 Gdb will run into the ex_help breakpoint. The source window now shows the
14126
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1201 ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1202 breakpoint was set. The line where the debugger stopped is highlighted. You
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1203 can now step through the program. Let's use the mouse: click on the "Next"
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1204 button in the window toolbar. You will see the highlighting move as the
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1205 debugger executes a line of source code.
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1206
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1207 Click "Next" a few times until the for loop is highlighted. Put the cursor on
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1208 the end of "eap->arg", then click "Eval" in the toolbar. You will see this
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1209 displayed:
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1210 "eap->arg": 0x555555e68855 "gui" ~
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1211 This way you can inspect the value of local variables. You can also focus the
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1212 gdb window and use a "print" command, e.g.: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1213 print *eap
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1214 If mouse pointer movements are working, Vim will also show a balloon when the
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1215 mouse rests on text that can be evaluated by gdb.
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1216
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1217 Now go back to the source window and put the cursor on the first line after
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1218 the for loop, then type: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1219 :Break
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1220 You will see a ">>" marker appear, this indicates the new breakpoint. Now
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1221 click "Cont" in the toolbar and the code until the breakpoint will be
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1222 executed.
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1223
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1224 You can type more advanced commands in the gdb window. For example, type: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1225 watch curbuf
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1226 Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1227 will now continue until the value of "curbuf" changes, which is in do_ecmd().
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1228 To remove this watchpoint again type in the gdb window: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1229 delete 3
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1230
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1231 You can see the stack by typing in the gdb window: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1232 where
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1233 Move through the stack frames, e.g. with: >
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1234 frame 3
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1235 The source window will show the code, at the point where the call was made to
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1236 a deeper level.
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1237
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1238
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1239 Stepping through code ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
1240 *termdebug-stepping*
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1241 Put focus on the gdb window to type commands there. Some common ones are:
12833
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1242 - CTRL-C interrupt the program
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1243 - next execute the current line and stop at the next line
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1244 - step execute the current line and stop at the next statement,
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1245 entering functions
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1246 - finish execute until leaving the current function
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1247 - where show the stack
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1248 - frame N go to the Nth stack frame
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1249 - continue continue execution
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1250
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1251 *:Run* *:Arguments*
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1252 In the window showing the source code these commands can be used to control
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1253 gdb:
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1254 `:Run` [args] run the program with [args] or the previous arguments
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1255 `:Arguments` {args} set arguments for the next `:Run`
12833
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1256
18130
1e5672da6a69 Updte runtime files
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
1257 *:Break* set a breakpoint at the cursor position
1e5672da6a69 Updte runtime files
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
1258 :Break {position}
18343
375a7ecdb351 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 18170
diff changeset
1259 set a breakpoint at the specified position
18130
1e5672da6a69 Updte runtime files
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
1260 *:Clear* delete the breakpoint at the cursor position
12833
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents: 12826
diff changeset
1261
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1262 *:Step* execute the gdb "step" command
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1263 *:Over* execute the gdb "next" command (`:Next` is a Vim command)
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1264 *:Finish* execute the gdb "finish" command
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1265 *:Continue* execute the gdb "continue" command
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1266 *:Stop* interrupt the program
12425
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1267
13051
a6d3e2081544 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12907
diff changeset
1268 If 'mouse' is set the plugin adds a window toolbar with these entries:
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1269 Step `:Step`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1270 Next `:Over`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1271 Finish `:Finish`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1272 Cont `:Continue`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1273 Stop `:Stop`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1274 Eval `:Evaluate`
13051
a6d3e2081544 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12907
diff changeset
1275 This way you can use the mouse to perform the most common commands. You need
a6d3e2081544 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12907
diff changeset
1276 to have the 'mouse' option set to enable mouse clicks.
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1277 *:Winbar*
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1278 You can add the window toolbar in other windows you open with: >
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1279 :Winbar
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1280
13592
a64485061f75 patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents: 13589
diff changeset
1281 If gdb stops at a source line and there is no window currently showing the
a64485061f75 patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents: 13589
diff changeset
1282 source code, a new window will be created for the source code. This also
a64485061f75 patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents: 13589
diff changeset
1283 happens if the buffer in the source code window has been modified and can't be
a64485061f75 patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents: 13589
diff changeset
1284 abandoned.
a64485061f75 patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents: 13589
diff changeset
1285
14126
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1286 Gdb gives each breakpoint a number. In Vim the number shows up in the sign
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1287 column, with a red background. You can use these gdb commands:
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1288 - info break list breakpoints
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1289 - delete N delete breakpoint N
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1290 You can also use the `:Clear` command if the cursor is in the line with the
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1291 breakpoint, or use the "Clear breakpoint" right-click menu entry.
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1292
12425
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1293
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1294 Inspecting variables ~
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1295 *termdebug-variables* *:Evaluate*
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1296 `:Evaluate` evaluate the expression under the cursor
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1297 `K` same
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1298 `:Evaluate` {expr} evaluate {expr}
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1299 `:'<,'>Evaluate` evaluate the Visually selected text
12425
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1300
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1301 This is similar to using "print" in the gdb window.
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1302 You can usually shorten `:Evaluate` to `:Ev`.
12425
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1303
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1304
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents: 12411
diff changeset
1305 Other commands ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
1306 *termdebug-commands*
13706
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1307 *:Gdb* jump to the gdb window
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1308 *:Program* jump to the window with the running program
bfd9249f72e0 patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents: 13682
diff changeset
1309 *:Source* jump to the window with the source code, create it if there
13592
a64485061f75 patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents: 13589
diff changeset
1310 isn't one
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1311
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1312
14107
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1313 Prompt mode ~
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1314 *termdebug-prompt*
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1315 When the |+terminal| feature is not supported and on MS-Windows, gdb will run
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1316 in a buffer with 'buftype' set to "prompt". This works slightly differently:
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1317 - The gdb window will be in Insert mode while typing commands. Go to Normal
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1318 mode with <Esc>, then you can move around in the buffer, copy/paste, etc.
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1319 Go back to editing the gdb command with any command that starts Insert mode,
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1320 such as `a` or `i`.
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1321 - The program being debugged will run in a separate window. On MS-Windows
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1322 this is a new console window. On Unix, if the |+terminal| feature is
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1323 available a Terminal window will be opened to run the debugged program in.
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1324
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1325 *termdebug_use_prompt*
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1326 Prompt mode can be used even when the |+terminal| feature is present with: >
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1327 let g:termdebug_use_prompt = 1
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1328
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1329
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1330 Communication ~
12826
f690da1b3c04 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
1331 *termdebug-communication*
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1332 There is another, hidden, buffer, which is used for Vim to communicate with
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1333 gdb. The buffer name is "gdb communication". Do not delete this buffer, it
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1334 will break the debugger.
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1335
14126
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1336 Gdb has some weird behavior, the plugin does its best to work around that.
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1337 For example, after typing "continue" in the gdb window a CTRL-C can be used to
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1338 interrupt the running program. But after using the MI command
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1339 "-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1340 "continue" being used for the `:Continue` command, instead of using the
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1341 communication channel.
1ce45478cbf1 patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1342
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1343
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
1344 Customizing ~
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1345
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1346 GDB command *termdebug-customizing*
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1347
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1348 To change the name of the gdb command, set the "termdebugger" variable before
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1349 invoking `:Termdebug`: >
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1350 let termdebugger = "mygdb"
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1351 < *gdb-version*
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1352 Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI
13482
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
1353 interface. The "new-ui" command requires gdb version 7.12 or later. if you
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents: 13476
diff changeset
1354 get this error:
12756
3b26420fc639 Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents: 12559
diff changeset
1355 Undefined command: "new-ui". Try "help".~
3b26420fc639 Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents: 12559
diff changeset
1356 Then your gdb is too old.
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1357
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1358
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1359 Colors *hl-debugPC* *hl-debugBreakpoint*
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1360
12411
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1361 The color of the signs can be adjusted with these highlight groups:
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1362 - debugPC the current position
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1363 - debugBreakpoint a breakpoint
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1364
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1365 The defaults are, when 'background' is "light":
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1366 hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1367 hi debugBreakpoint term=reverse ctermbg=red guibg=red
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1368
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1369 When 'background' is "dark":
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1370 hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents: 12311
diff changeset
1371 hi debugBreakpoint term=reverse ctermbg=red guibg=red
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12192
diff changeset
1372
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1373
16871
e5dab34ded73 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1374 Shortcuts *termdebug_shortcuts*
14107
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1375
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1376 You can define your own shortcuts (mappings) to control gdb, that can work in
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1377 any window, using the TermDebugSendCommand() function. Example: >
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1378 map ,w :call TermDebugSendCommand('where')<CR>
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1379 The argument is the gdb command.
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1380
274c9f1fbfd2 patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents: 14063
diff changeset
1381
13377
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1382 Popup menu *termdebug_popup*
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1383
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1384 By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1385 these entries to the popup menu:
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1386 Set breakpoint `:Break`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1387 Clear breakpoint `:Clear`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1388 Evaluate `:Evaluate`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1389 If you don't want this then disable it with: >
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1390 let g:termdebug_popup = 0
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1391
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1392
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1393 Vim window width *termdebug_wide*
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse
Christian Brabandt <cb@256bit.org>
parents: 13304
diff changeset
1394
12455
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
1395 To change the width of the Vim window when debugging starts, and use a
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
1396 vertical split: >
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
1397 let g:termdebug_wide = 163
14249
4543777545a3 Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents: 14126
diff changeset
1398 This will set &columns to 163 when `:Termdebug` is used. The value is restored
12455
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
1399 when quitting the debugger.
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14109
diff changeset
1400 If g:termdebug_wide is set and &columns is already larger than
12559
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1401 g:termdebug_wide then a vertical split will be used without changing &columns.
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1402 Set it to 1 to get a vertical split without every changing &columns (useful
34c8ec888122 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12487
diff changeset
1403 for when the terminal can't be resized by Vim).
12455
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents: 12425
diff changeset
1404
11621
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1405
b8299e742f41 patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1406
14421
2f7e67dd088c Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14249
diff changeset
1407 vim:tw=78:ts=8:noet:ft=help:norl: