summaryrefslogtreecommitdiff
path: root/runtime/doc/terminal.txt
blob: 2484b73e9ae751a7ace9a0371f724c88f6737da7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
*terminal.txt*	For Vim version 8.1.  Last change: 2019 Jul 04


		  VIM REFERENCE MANUAL	  by Bram Moolenaar


Terminal window support				*terminal* *terminal-window*


The terminal feature is optional, use this to check if your Vim has it: >
	echo has('terminal')
If the result is "1" you have it.


1. Basic use				|terminal-use|
      Typing					|terminal-typing|
      Size and color				|terminal-size-color|
      Command syntax				|:terminal|
      Resizing					|terminal-resizing|
      Terminal Modes				|Terminal-mode|
      Cursor style				|terminal-cursor-style|
      Session					|terminal-session|
      Special keys				|terminal-special-keys|
      Unix					|terminal-unix|
      MS-Windows				|terminal-ms-windows|
2. Terminal functions			|terminal-function-details|
3. Terminal communication		|terminal-communication|
      Vim to job: term_sendkeys()		|terminal-to-job|
      Job to Vim: JSON API			|terminal-api|
      Using the client-server feature		|terminal-client-server|
4. Remote testing			|terminal-testing|
5. Diffing screen dumps			|terminal-diff|
      Writing a screen dump test for Vim  	|terminal-dumptest|
      Creating a screen dump		  	|terminal-screendump|
      Comparing screen dumps		  	|terminal-diffscreendump|
6. Debugging				|terminal-debug|
      Starting					|termdebug-starting|
      Example session				|termdebug-example|
      Stepping through code			|termdebug-stepping|
      Inspecting variables			|termdebug-variables|
      Other commands				|termdebug-commands|
      Prompt mode				|termdebug-prompt|
      Communication				|termdebug-communication|
      Customizing				|termdebug-customizing|

{only available when compiled with the |+terminal| feature}
The terminal feature requires the |+job| and |+channel| features.

==============================================================================
1. Basic use						*terminal-use*

This feature is for running a terminal emulator in a Vim window.  A job can be
started connected to the terminal emulator. For example, to run a shell: >
     :term bash

Or to run build command: >
     :term make myprogram

The job runs asynchronously from Vim, the window will be updated to show
output from the job, also while editing in another window.


Typing ~
							*terminal-typing*
When the keyboard focus is in the terminal window, typed keys will be sent to
the job.  This uses a pty when possible.  You can click outside of the
terminal window to move keyboard focus elsewhere.

						*t_CTRL-W_CTRL-W* *t_CTRL-W_:*
CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
	CTRL-W CTRL-W	move focus to the next window
	CTRL-W :	enter an Ex command
See |CTRL-W| for more commands.

Special in the terminal window:			*t_CTRL-W_.*  *t_CTRL-W_N* 
	CTRL-W .	send a CTRL-W to the job in the terminal
	CTRL-W CTRL-\	send a CTRL-\ to the job in the terminal
	CTRL-W N	go to Terminal-Normal mode, see |Terminal-mode|
	CTRL-\ CTRL-N   go to Terminal-Normal mode, see |Terminal-mode|
	CTRL-W " {reg}  paste register {reg}		*t_CTRL-W_quote*
			Also works with the = register to insert the result of
			evaluating an expression.
	CTRL-W CTRL-C	ends the job, see below |t_CTRL-W_CTRL-C|
	CTRL-W gt	go to next tabpage, same as `gt`	*t_CTRL-W_gt*
	CTRL-W gT	go to previous tabpage, same as `gT`	*t_CTRL-W_gT*

See option 'termwinkey' for specifying another key instead of CTRL-W that
will work like CTRL-W.  However, typing 'termwinkey' twice sends 'termwinkey'
to the job.  For example:
	'termwinkey' CTRL-W    move focus to the next window
	'termwinkey' :	       enter an Ex command
	'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal
	'termwinkey' .	       send 'termwinkey' to the job in the terminal
	'termwinkey' CTRL-\    send a CTRL-\ to the job in the terminal
	'termwinkey' N	       go to terminal Normal mode, see below
	'termwinkey' CTRL-N    same as CTRL-W N |t_CTRL-W_N|
	'termwinkey' CTRL-C    same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C|
							*t_CTRL-\_CTRL-N*
The special key combination CTRL-\ CTRL-N can be used to switch to Normal
mode, just like this works in any other mode.
							*t_CTRL-W_CTRL-C*
CTRL-W CTRL-C can be typed to forcefully end the job.  On MS-Windows a
CTRL-BREAK will also kill the job.

If you type CTRL-C the effect depends on what the pty has been configured to
do.  For simple commands this causes a SIGINT to be sent to the job, which
would end it.  Other commands may ignore the SIGINT or handle the CTRL-C
themselves (like Vim does).

To change the keys you type use terminal mode mappings, see |:tmap|.
These are defined like any mapping, but apply only when typing keys that are
sent to the job running in the terminal.  For example, to make F1 switch
to Terminal-Normal mode: >
   tnoremap <F1> <C-W>N
You can use Esc, but you need to make sure it won't cause other keys to
break (cursor keys start with an Esc, so they may break): >
   tnoremap <Esc> <C-W>N
   set notimeout ttimeout timeoutlen=100

You can also create menus similar to terminal mode mappings, but you have to
use |:tlmenu| instead of |:tmenu|.

<							*options-in-terminal*
After opening the terminal window and setting 'buftype' to "terminal" the
TerminalOpen autocommand event is triggered.  This makes it possible to set
options specifically for the window and buffer.  Example: >
   au TerminalOpen * if &buftype == 'terminal' | setlocal bufhidden=hide | endif
The <abuf> is set to the terminal buffer, but if there is no window (hidden
terminal) then setting options will happen in the wrong buffer, therefore the
check for &buftype in the example.

Mouse events (click and drag) are passed to the terminal.  Mouse move events
are only passed when Vim itself is receiving them.  For a terminal that is
when 'balloonevalterm' is enabled.


Size and color ~
							*terminal-size-color*
See option 'termwinsize' for controlling the size of the terminal window.
(TODO: scrolling when the terminal is larger than the window)

The job running in the terminal can change the colors.  The default foreground
and background colors are taken from Vim, the Normal highlight group.

For a color terminal the 'background' option is used to decide whether the
terminal window will start with a white or black background.

To use a different color the Terminal highlight group can be used, for
example: >
    hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
<
							*g:terminal_ansi_colors*
In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
terminal windows may be configured using the variable
`g:terminal_ansi_colors`, which should be a list of 16 color names or
hexadecimal color codes, similar to those accepted by |highlight-guifg|.  When
not using GUI colors, the terminal window always uses the 16 ANSI colors of
the underlying terminal.
The |term_setansicolors()| function can be used to change the colors, and
|term_getansicolors()| to get the currently used colors.


Command syntax ~

:[range]ter[minal] [options] [command]			*:ter* *:terminal*
			Open a new terminal window.

			If [command] is provided run it as a job and connect
			the input and output to the terminal.
			If [command] is not given the 'shell' option is used.
			if [command] is NONE no job is started, the pty of the
			terminal can be used by a command like gdb.

			If [command] is missing the default behavior is to
			close the terminal when the shell exits.  This can be
			changed with the ++noclose argument.
			If [command] is present the default behavior is to
			keep the terminal open in Terminal-Normal mode.  This
			can be changed with the ++close argument.

			A new buffer will be created, using [command] or
			'shell' as the name, prefixed with a "!".  If a buffer
			by this name already exists a number is added in
			parentheses.  E.g. if "gdb" exists the second terminal
			buffer will use "!gdb (1)".

			If [range] is given the specified lines are used as
			input for the job.  It will not be possible to type
			keys in the terminal window.  For MS-Windows see the
			++eof argument below.

						*term++close* *term++open*
			Supported [options] are:
			++close		The terminal window will close
					automatically when the job terminates.
			++noclose	The terminal window will NOT close
					automatically when the job terminates.
			++open		When the job terminates and no window
					shows it, a window will be opened.
					Note that this can be interruptive.
				The last of ++close, ++noclose and ++open
				matters and rules out earlier arguments.

			++curwin	Open the terminal in the current
					window, do not split the current
					window.  Fails if the current buffer
					cannot be |abandon|ed.
			++hidden	Open the terminal in a hidden buffer,
					no window will be used.
			++norestore	Do not include this terminal window
					in a session file.
			++kill={how}	When trying to close the terminal
					window kill the job with {how}.  See
					|term_setkill()| for the values.
			++rows={height} Use {height} for the terminal window
					height.  If the terminal uses the full
					Vim height (no window above or below
					the terminal window) the command line
					height will be reduced as needed.
			++cols={width}  Use {width} for the terminal window
					width. If the terminal uses the full
					Vim width (no window left or right of
					the terminal window) this value is
					ignored.
			++eof={text}	when using [range]: text to send after
					the last line was written. Cannot
					contain white space.  A CR is
					appended.  For MS-Windows the default
					is to send CTRL-D.
					E.g. for a shell use "++eof=exit" and
					for Python "++eof=exit()".  Special
					codes can be used like with `:map`,
					e.g. "<C-Z>" for CTRL-Z.
			++type={pty}	(MS-Windows only): Use {pty} as the
					virtual console.  See 'termwintype'
					for the values.

			If you want to use more options use the |term_start()|
			function.
			If you want to split the window vertically, use: >
				:vertical terminal
<			Or short: >
				:vert ter

When the buffer associated with the terminal is forcibly unloaded or wiped out
the job is killed, similar to calling `job_stop(job, "kill")` .
Closing the window normally results in |E947|.  When a kill method was set
with "++kill={how}" or |term_setkill()| then closing the window will use that
way to kill or interrupt the job.  For example: >
	:term ++kill=term tail -f /tmp/log

So long as the job is running the window behaves like it contains a modified
buffer.  Trying to close the window with `CTRL-W :quit` fails.  When using
`CTRL-W :quit!` the job is ended.  The text in the window is lost.  The buffer
still exists, but getting it in a window with `:buffer` will show an empty
buffer.

Trying to close the window with `CTRL-W :close` also fails.   Using
`CTRL-W :close!` will close the window and make the buffer hidden.

You can use `CTRL-W :hide` to close the terminal window and make the buffer
hidden, the job keeps running.  The `:buffer` command can be used to turn the
current window into a terminal window.  If there are unsaved changes this
fails, use ! to force, as usual.

To have a background job run without a window, and open the window when it's
done, use options like this: >
	:term ++hidden ++open make
Note that the window will open at an unexpected moment, this will interrupt
what you are doing.

							*E947* *E948*
So long as the job is running, the buffer is considered modified and Vim
cannot be quit easily, see |abandon|.

When the job has finished and no changes were made to the buffer: closing the
window will wipe out the buffer.

Before changes can be made to a terminal buffer, the 'modifiable' option must
be set.  This is only possible when the job has finished.  At the first change
the buffer will become a normal buffer and the highlighting is removed.
You may want to change the buffer name with |:file| to be able to write, since
the buffer name will still be set to the command.


Resizing ~
							*terminal-resizing*
The size of the terminal can be in one of three modes:

1. The 'termwinsize' option is empty: The terminal size follows the window
   size.  The minimal size is 2 screen lines with 10 cells.

2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number
   of screen rows and "cols" is the minimal number of cells.

3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower
   case).  The terminal size is fixed to the specified number of screen lines
   and cells.  If the window is bigger there will be unused empty space.

If the window is smaller than the terminal size, only part of the terminal can
be seen (the lower-left part).

The |term_getsize()| function can be used to get the current size of the
terminal.  |term_setsize()| can be used only when in the first or second mode,
not when 'termwinsize' is "rowsXcols".


Terminal-Job and Terminal-Normal mode ~
						*Terminal-mode* *Terminal-Job*
When the job is running the contents of the terminal is under control of the
job.  That includes the cursor position.  Typed keys are sent to the job.
The terminal contents can change at any time.  This is called Terminal-Job
mode.

Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode.  Now the
contents of the terminal window is under control of Vim, the job output is
suspended.  CTRL-\ CTRL-N does the same.

Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by
|term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are.

It is not possible to enter Insert mode from Terminal-Job mode.

						*Terminal-Normal* *E946*
In Terminal-Normal mode you can move the cursor around with the usual Vim
commands, Visually mark text, yank text, etc.  But you cannot change the
contents of the buffer.  The commands that would start insert mode, such as
'i' and 'a', return to Terminal-Job mode.  The window will be updated to show
the contents of the terminal. |:startinsert| is ineffective.

In Terminal-Normal mode the statusline and window title show "(Terminal)".  If
the job ends while in Terminal-Normal mode this changes to
"(Terminal-finished)".

When the job outputs lines in the terminal, such that the contents scrolls off
the top, those lines are remembered and can be seen in Terminal-Normal mode.
The number of lines is limited by the 'termwinscroll' option. When going over
this limit, the first 10% of the scrolled lines are deleted and are lost.


Cursor style ~
							*terminal-cursor-style*
By default the cursor in the terminal window uses a not blinking block.  The
normal xterm escape sequences can be used to change the blinking state and the
shape.  Once focus leaves the terminal window Vim will restore the original
cursor.

An exception is when xterm is started with the "-bc" argument, or another way
that causes the cursor to blink.  This actually means that the blinking flag
is inverted.  Since Vim cannot detect this, the terminal window cursor
blinking will also be inverted.


Session ~
							*terminal-session*
A terminal window will be restored when using a session file, if possible and
wanted.

If "terminal" was removed from 'sessionoptions' then no terminal windows will
be restored.

If the job in the terminal was finished the window will not be restored.

If the terminal can be restored, the command that was used to open it will be
used again.  To change this use the |term_setrestore()| function.  This can
also be used to not restore a specific terminal by setting the command to
"NONE".


Special keys ~
							*terminal-special-keys*
Since the terminal emulator simulates an xterm, only escape sequences that
both Vim and xterm recognize will be available in the terminal window.  If you
want to pass on other escape sequences to the job running in the terminal you
need to set up forwarding.  Example: >
	tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
	func SendToTerm(what)
	  call term_sendkeys('', a:what)
	  return ''
	endfunc


Unix ~
							*terminal-unix*
On Unix a pty is used to make it possible to run all kinds of commands.  You
can even run Vim in the terminal!  That's used for debugging, see below.

Environment variables are used to pass information to the running job:
    TERM		the name of the terminal, from the 'term' option or
			$TERM in the GUI; falls back to "xterm" if it does not
			start with "xterm"
    ROWS		number of rows in the terminal initially
    LINES		same as ROWS
    COLUMNS		number of columns in the terminal initially
    COLORS		number of colors, 't_Co' (256*256*256 in the GUI)
    VIM_SERVERNAME	v:servername
    VIM_TERMINAL	v:version


MS-Windows ~
							*terminal-ms-windows*
On MS-Windows winpty is used to make it possible to run all kind of commands.
Obviously, they must be commands that run in a terminal, not open their own
window.

You need the following two files from winpty:

    winpty.dll
    winpty-agent.exe

You can download them from the following page:

    https://github.com/rprichard/winpty

Just put the files somewhere in your PATH.  You can set the 'winptydll' option
to point to the right file, if needed.  If you have both the 32-bit and 64-bit
version, rename to winpty32.dll and winpty64.dll to match the way Vim was
build.
							*ConPTY* *E982*
On more recent versions of MS-Windows 10 (beginning with the "October 2018
Update"), winpty is no longer required. On those versions, |:terminal| will use
Windows' built-in support for hosting terminal applications, "ConPTY".  When
ConPTY is in use, there may be rendering artifacts regarding ambiguous-width
characters. If you encounter any such issues, install "winpty".  Until the
ConPTY problems have been fixed "winpty" will be preferred.

Environment variables are used to pass information to the running job:
    VIM_SERVERNAME	v:servername


==============================================================================
2. Terminal functions				 *terminal-function-details*

							*term_dumpdiff()*
term_dumpdiff({filename}, {filename} [, {options}])
		Open a new window displaying the difference between the two
		files.  The files must have been created with
		|term_dumpwrite()|.
		Returns the buffer number or zero when the diff fails.
		Also see |terminal-diff|.
		NOTE: this does not work with double-width characters yet.

		The top part of the buffer contains the contents of the first
		file, the bottom part of the buffer contains the contents of
		the second file.  The middle part shows the differences.
		The parts are separated by a line of equals.

		If the {options} argument is present, it must be a Dict with
		these possible members:
		   "term_name"	     name to use for the buffer name, instead
				     of the first file name.
		   "term_rows"	     vertical size to use for the terminal,
				     instead of using 'termwinsize'
		   "term_cols"	     horizontal size to use for the terminal,
				     instead of using 'termwinsize'
		   "vertical"	     split the window vertically
		   "curwin"	     use the current window, do not split the
				     window; fails if the current buffer
				     cannot be |abandon|ed
		   "bufnr"	     do not create a new buffer, use the
				     existing buffer "bufnr".  This buffer
				     must have been previously created with
				     term_dumpdiff() or term_dumpload() and
				     visible in a window.
		   "norestore"	     do not add the terminal window to a
				     session file

		Each character in the middle part indicates a difference. If
		there are multiple differences only the first in this list is
		used:
			X	different character
			w	different width
			f	different foreground color
			b	different background color
			a	different attribute
			+	missing position in first file
			-	missing position in second file

		Using the "s" key the top and bottom parts are swapped.  This
		makes it easy to spot a difference.

		Can also be used as a |method|: >
			GetFilename()->term_dumpdiff(otherfile)
<
							*term_dumpload()*
term_dumpload({filename} [, {options}])
		Open a new window displaying the contents of {filename}
		The file must have been created with |term_dumpwrite()|.
		Returns the buffer number or zero when it fails.
		Also see |terminal-diff|.

		For {options} see |term_dumpdiff()|.

		Can also be used as a |method|: >
			GetFilename()-> term_dumpload()
<
							*term_dumpwrite()*
term_dumpwrite({buf}, {filename} [, {options}])
		Dump the contents of the terminal screen of {buf} in the file
		{filename}.  This uses a format that can be used with
		|term_dumpload()| and |term_dumpdiff()|.
		If the job in the terminal already finished an error is given:
		*E958*
		If {filename} already exists an error is given:	*E953*
		Also see |terminal-diff|.

		{options} is a dictionary with these optional entries:
			"rows"		maximum number of rows to dump
			"columns"	maximum number of columns to dump

		Can also be used as a |method|, the base is used for the file
		name: >
			GetFilename()-> term_dumpwrite(bufnr)

term_getaltscreen({buf})				*term_getaltscreen()*
		Returns 1 if the terminal of {buf} is using the alternate
		screen.
		{buf} is used as with |term_getsize()|.

		Can also be used as a |method|: >
			GetBufnr()->term_getaltscreen()


term_getansicolors({buf})				*term_getansicolors()*
		Get the ANSI color palette in use by terminal {buf}.
		Returns a List of length 16 where each element is a String
		representing a color in hexadecimal "#rrggbb" format.
		Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
		If neither was used returns the default colors.

		{buf} is used as with |term_getsize()|.  If the buffer does not
		exist or is not a terminal window, an empty list is returned.

		Can also be used as a |method|: >
			GetBufnr()->term_getansicolors()

<		{only available when compiled with GUI enabled and/or the
		|+termguicolors| feature}

term_getattr({attr}, {what})				*term_getattr()*
		Given {attr}, a value returned by term_scrape() in the "attr"
		item, return whether {what} is on.  {what} can be one of:
			bold
			italic
			underline
			strike
			reverse

		Can also be used as a |method|: >
			GetAttr()->term_getattr()


term_getcursor({buf})					*term_getcursor()*
		Get the cursor position of terminal {buf}. Returns a list with
		two numbers and a dictionary: [row, col, dict].

		"row" and "col" are one based, the first screen cell is row
		1, column 1.  This is the cursor position of the terminal
		itself, not of the Vim window.

		"dict" can have these members:
		   "visible"	one when the cursor is visible, zero when it
				is hidden.
		   "blink"	one when the cursor is blinking, zero when it
				is not blinking.
		   "shape"	1 for a block cursor, 2 for underline and 3
				for a vertical bar.
		   "color"	color of the cursor, e.g. "green"

		{buf} must be the buffer number of a terminal window. If the
		buffer does not exist or is not a terminal window, an empty
		list is returned.

		Can also be used as a |method|: >
			GetBufnr()->term_getcursor()

term_getjob({buf})					*term_getjob()*
		Get the Job associated with terminal window {buf}.
		{buf} is used as with |term_getsize()|.
		Returns |v:null| when there is no job.

		Can also be used as a |method|: >
			GetBufnr()->term_getjob()


term_getline({buf}, {row})				*term_getline()*
		Get a line of text from the terminal window of {buf}.
		{buf} is used as with |term_getsize()|.

		The first line has {row} one.  When {row} is "." the cursor
		line is used.  When {row} is invalid an empty string is
		returned.

		To get attributes of each character use |term_scrape()|.

		Can also be used as a |method|: >
			GetBufnr()->term_getline(row)


term_getscrolled({buf})					*term_getscrolled()*
		Return the number of lines that scrolled to above the top of
		terminal {buf}.  This is the offset between the row number
		used for |term_getline()| and |getline()|, so that: >
			term_getline(buf, N)
<		is equal to: >
			getline(N + term_getscrolled(buf))
<		(if that line exists).

		{buf} is used as with |term_getsize()|.

		Can also be used as a |method|: >
			GetBufnr()->term_getscrolled()


term_getsize({buf})					*term_getsize()*
		Get the size of terminal {buf}. Returns a list with two
		numbers: [rows, cols].  This is the size of the terminal, not
		the window containing the terminal.

		{buf} must be the buffer number of a terminal window.  Use an
		empty string for the current buffer.  If the buffer does not
		exist or is not a terminal window, an empty list is returned.

		Can also be used as a |method|: >
			GetBufnr()->term_getsize()


term_getstatus({buf})					*term_getstatus()*
		Get the status of terminal {buf}. This returns a comma
		separated list of these items:
			running		job is running
			finished	job has finished
			normal		in Terminal-Normal mode
		One of "running" or "finished" is always present.

		{buf} must be the buffer number of a terminal window. If the
		buffer does not exist or is not a terminal window, an empty
		string is returned.

		Can also be used as a |method|: >
			GetBufnr()->term_getstatus()


term_gettitle({buf})					*term_gettitle()*
		Get the title of terminal {buf}. This is the title that the
		job in the terminal has set.

		{buf} must be the buffer number of a terminal window. If the
		buffer does not exist or is not a terminal window, an empty
		string is returned.

		Can also be used as a |method|: >
			GetBufnr()->term_gettitle()


term_gettty({buf} [, {input}])				*term_gettty()*
		Get the name of the controlling terminal associated with
		terminal window {buf}.  {buf} is used as with |term_getsize()|.

		When {input} is omitted or 0, return the name for writing
		(stdout). When {input} is 1 return the name for reading
		(stdin). On UNIX, both return same name.

		Can also be used as a |method|: >
			GetBufnr()->term_gettty()


term_list()						*term_list()*
		Return a list with the buffer numbers of all buffers for
		terminal windows.


term_scrape({buf}, {row})				*term_scrape()*
		Get the contents of {row} of terminal screen of {buf}.
		For {buf} see |term_getsize()|.

		The first line has {row} one.  When {row} is "." the cursor
		line is used.  When {row} is invalid an empty string is
		returned.

		Return a List containing a Dict for each screen cell:
		    "chars"	character(s) at the cell
		    "fg"	foreground color as #rrggbb
		    "bg"	background color as #rrggbb
		    "attr"	attributes of the cell, use |term_getattr()|
				to get the individual flags
		    "width"	cell width: 1 or 2

		Can also be used as a |method|: >
			GetBufnr()->term_scrape(row)


term_sendkeys({buf}, {keys})				*term_sendkeys()*
		Send keystrokes {keys} to terminal {buf}.
		{buf} is used as with |term_getsize()|.

		{keys} are translated as key sequences. For example, "\<c-x>"
		means the character CTRL-X.

		Can also be used as a |method|: >
			GetBufnr()->term_sendkeys(keys)


term_setansicolors({buf}, {colors})			*term_setansicolors()*
		Set the ANSI color palette used by terminal {buf}.
		{colors} must be a List of 16 valid color names or hexadecimal
		color codes, like those accepted by |highlight-guifg|.
		Also see |term_getansicolors()| and |g:terminal_ansi_colors|.

		The colors normally are:
			0    black
			1    dark red
			2    dark green
			3    brown
			4    dark blue
			5    dark magenta
			6    dark cyan
			7    light grey
			8    dark grey
			9    red
			10   green
			11   yellow
			12   blue
			13   magenta
			14   cyan
			15   white

		These colors are used in the GUI and in the terminal when
		'termguicolors' is set.  When not using GUI colors (GUI mode
		or 'termguicolors'), the terminal window always uses the 16
		ANSI colors of the underlying terminal.

		Can also be used as a |method|: >
			GetBufnr()->term_setansicolors(colors)

<		{only available with GUI enabled and/or the |+termguicolors|
		feature}

term_setkill({buf}, {how})				*term_setkill()*
		When exiting Vim or trying to close the terminal window in
		another way, {how} defines whether the job in the terminal can
		be stopped.
		When {how} is empty (the default), the job will not be
		stopped, trying to exit will result in |E947|.
		Otherwise, {how} specifies what signal to send to the job.
		See |job_stop()| for the values.

		After sending the signal Vim will wait for up to a second to
		check that the job actually stopped.

		Can also be used as a |method|: >
			GetBufnr()->term_setkill(how)


term_setrestore({buf}, {command})			*term_setrestore()*
		Set the command to write in a session file to restore the job
		in this terminal.  The line written in the session file is: >
			terminal ++curwin ++cols=%d ++rows=%d {command}
<		Make sure to escape the command properly.

		Use an empty {command} to run 'shell'.
		Use "NONE" to not restore this window.

		Can also be used as a |method|: >
			GetBufnr()->term_setrestore(command)


term_setsize({buf}, {rows}, {cols})		*term_setsize()* *E955*
		Set the size of terminal {buf}. The size of the window
		containing the terminal will also be adjusted, if possible.
		If {rows} or {cols} is zero or negative, that dimension is not
		changed.

		{buf} must be the buffer number of a terminal window.  Use an
		empty string for the current buffer.  If the buffer does not
		exist or is not a terminal window, an error is given.

		Can also be used as a |method|: >
			GetBufnr()->term_setsize(rows, cols)


term_start({cmd} [, {options}])			*term_start()*
		Open a terminal window and run {cmd} in it.

		{cmd} can be a string or a List, like with |job_start()|. The
		string "NONE" can be used to open a terminal window without
		starting a job, the pty of the terminal can be used by a
		command like gdb.

		Returns the buffer number of the terminal window.  If {cmd}
		cannot be executed the window does open and shows an error
		message.
		If opening the window fails zero is returned.

		{options} are similar to what is used for |job_start()|, see
		|job-options|.  However, not all options can be used.  These
		are supported:
		   all timeout options
		   "stoponexit", "cwd", "env"
		   "callback", "out_cb", "err_cb", "exit_cb", "close_cb"
		   "in_io", "in_top", "in_bot", "in_name", "in_buf"
		   "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
		   "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
		However, at least one of stdin, stdout or stderr must be
		connected to the terminal.  When I/O is connected to the
		terminal then the callback function for that part is not used.

		There are extra options:
		   "term_name"	     name to use for the buffer name, instead
				     of the command name.
		   "term_rows"	     vertical size to use for the terminal,
				     instead of using 'termwinsize'
		   "term_cols"	     horizontal size to use for the terminal,
				     instead of using 'termwinsize'
		   "vertical"	     split the window vertically; note that
				     other window position can be defined with
				     command modifiers, such as |:belowright|.
		   "curwin"	     use the current window, do not split the
				     window; fails if the current buffer
				     cannot be |abandon|ed
		   "hidden"	     do not open a window
		   "norestore"	     do not add the terminal window to a
				     session file
		   "term_kill"	     what to do when trying to close the
				     terminal window, see |term_setkill()|
		   "term_finish"     What to do when the job is finished:
					"close": close any windows
					"open": open window if needed
				     Note that "open" can be interruptive.
				     See |term++close| and |term++open|.
		   "term_opencmd"    command to use for opening the window when
				     "open" is used for "term_finish"; must
				     have "%d" where the buffer number goes,
				     e.g. "10split|buffer %d"; when not
				     specified "botright sbuf %d" is used
		   "eof_chars"	     Text to send after all buffer lines were
				     written to the terminal.  When not set
				     CTRL-D is used on MS-Windows. For Python
				     use CTRL-Z or "exit()". For a shell use
				     "exit".  A CR is always added.
		   "ansi_colors"     A list of 16 color names or hex codes
				     defining the ANSI palette used in GUI
				     color modes.  See |g:terminal_ansi_colors|.
		   "tty_type"	     (MS-Windows only): Specify which pty to
				     use.  See 'termwintype' for the values.

		Can also be used as a |method|: >
			GetCommand()->term_start()

<		{only available when compiled with the |+terminal| feature}


term_wait({buf} [, {time}])					*term_wait()*
		Wait for pending updates of {buf} to be handled.
		{buf} is used as with |term_getsize()|.
		{time} is how long to wait for updates to arrive in msec.  If
		not set then 10 msec will be used.

		Can also be used as a |method|: >
			GetBufnr()->term_wait()

==============================================================================
3. Terminal communication			 *terminal-communication*

There are several ways to communicate with the job running in a terminal:
- Use |term_sendkeys()| to send text and escape sequences from Vim to the job.
- Use the JSON API to send encoded commands from the job to Vim.
- Use the |client-server| mechanism. This works on machines with an X server
  and on MS-Windows.


Vim to job: term_sendkeys() ~
							*terminal-to-job*
This allows for remote controlling the job running in the terminal.  It is a
one-way mechanism.  The job can update the display to signal back to Vim.
For example, if a shell is running in a terminal, you can do: >
	call term_sendkeys(buf, "ls *.java\<CR>")

This requires for the job to be in the right state where it will do the right
thing when receiving the keys.  For the above example, the shell must be
waiting for a command to be typed.

For a job that was written for the purpose, you can use the JSON API escape
sequence in the other direction.  E.g.: >
	call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")


Job to Vim: JSON API ~
							*terminal-api*
The job can send JSON to Vim, using a special escape sequence.  The JSON
encodes a command that Vim understands.  Example of such a message: >
	<Esc>]51;["drop", "README.md"]<07>

The body is always a list, making it easy to find the end: ]<07>.
The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
similar to what we are doing here.

Currently supported commands:

	call {funcname} {argument}

		Call a user defined function with {argument}.
		The function is called with two arguments: the buffer number
		of the terminal and {argument}, the decoded JSON argument. 
		The function name must start with "Tapi_" to avoid
		accidentally calling a function not meant to be used for the
		terminal API.
		The user function should sanity check the argument.
		The function can use |term_sendkeys()| to send back a reply.
		Example in JSON: >
			["call", "Tapi_Impression", ["play", 14]]
<		Calls a function defined like this: >
			function Tapi_Impression(bufnum, arglist)
			  if len(a:arglist) == 2
			    echomsg "impression " . a:arglist[0]
			    echomsg "count " . a:arglist[1]
			  endif
			endfunc
<		Output from `:echo` may be erased by a redraw, use `:echomsg`
		to be able to see it with `:messages`.

	drop {filename} [options]

		Let Vim open a file, like the `:drop` command.  If {filename}
		is already open in a window, switch to that window.  Otherwise
		open a new window to edit {filename}.
		Note that both the job and Vim may change the current
		directory, thus it's best to use the full path.

		[options] is only used when opening a new window.  If present,
		it must be a Dict.  Similarly to |++opt|, These entries are
		recognized:
		  "ff"		file format: "dos", "mac" or "unix"
		  "fileformat"	idem
		  "enc"		overrides 'fileencoding'
		  "encoding"	idem
		  "bin"		sets 'binary'
		  "binary"	idem
		  "nobin"	resets 'binary'
		  "nobinary"	idem
		  "bad"		specifies behavior for bad characters, see
				|++bad|

		Example in JSON: >
			["drop", "path/file.txt", {"ff": "dos"}]

A trick to have Vim send this escape sequence: >
	exe "set t_ts=\<Esc>]51; t_fs=\x07"
	let &titlestring = '["call","Tapi_TryThis",["hello",123]]'
	redraw
	set t_ts& t_fs&

Rationale: Why not allow for any command or expression?  Because that might
create a security problem.


Using the client-server feature ~
						*terminal-client-server*
This only works when v:servername is not empty.  If needed you can set it,
before opening the terminal, with: >
	call remote_startserver('vim-server')

$VIM_SERVERNAME is set in the terminal to pass on the server name.

In the job you can then do something like: >
	vim --servername $VIM_SERVERNAME --remote +123 some_file.c
This will open the file "some_file.c" and put the cursor on line 123.

==============================================================================
4. Remote testing					*terminal-testing*

Most Vim tests execute a script inside Vim.  For some tests this does not
work, running the test interferes with the code being tested.  To avoid this
Vim is executed in a terminal window.  The test sends keystrokes to it and
inspects the resulting screen state.

Functions ~

|term_sendkeys()|	send keystrokes to a terminal (not subject to tmap)
|term_wait()|		wait for screen to be updated
|term_scrape()|		inspect terminal screen


==============================================================================
5. Diffing screen dumps					*terminal-diff*

In some cases it can be bothersome to test that Vim displays the right
characters on the screen.  E.g. with syntax highlighting.  To make this
simpler it is possible to take a screen dump of a terminal and compare it to
an expected screen dump.

Vim uses the window size, text, color and other attributes as displayed.  The
Vim screen size, font and other properties do not matter.  Therefore this
mechanism is portable across systems.  A conventional screenshot would reflect
all differences, including font size and family.


Writing a screen dump test for Vim ~
							*terminal-dumptest*
For an example see the Test_syntax_c() function in
src/testdir/test_syntax.vim.  The main parts are:
- Write a file you want to test with. This is useful for testing syntax
  highlighting.  You can also start Vim with en empty buffer.
- Run Vim in a terminal with a specific size.  The default is 20 lines of 75
  characters.  This makes sure the dump is always this size.  The function
  RunVimInTerminal() takes care of this.  Pass it the arguments for the Vim
  command.
- Send any commands to Vim using |term_sendkeys()|.  For example: >
	call term_sendkeys(buf, ":echo &lines &columns\<CR>")
- Check that the screen is now in the expected state, using
  VerifyScreenDump().  This expects the reference screen dump to be in the
  src/testdir/dumps/ directory.  Pass the name without ".dump".  It is
  recommended to use the name of the test function and a sequence number, so
  that we know what test is using the file.
- Repeat sending commands and checking the state.
- Finally stop Vim by calling StopVimInTerminal().

The first time you do this you won't have a screen dump yet.  Create an empty
file for now, e.g.: >
	touch src/testdir/dumps/Test_function_name_01.dump

The test will then fail, giving you the command to compare the reference dump
and the failed dump, e.g.: >
	call term_dumpdiff("Test_func.dump.failed", "dumps/Test_func.dump")

Use this command in Vim, with the current directory set to src/testdir.
Once you are satisfied with the test, move the failed dump in place of the
reference: >
	:!mv Test_func.dump.failed dumps/Test_func.dump


Creating a screen dump ~
							*terminal-screendump*

To create the screen dump, run Vim (or any other program) in a terminal and
make it show the desired state.  Then use the |term_dumpwrite()| function to
create a screen dump file.  For example: >
	:call term_dumpwrite(77, "mysyntax.dump")

Here "77" is the buffer number of the terminal.  Use `:ls!` to see it.

You can view the screen dump with |term_dumpload()|: >
	:call term_dumpload("mysyntax.dump")

To verify that Vim still shows exactly the same screen, run Vim again with
exactly the same way to show the desired state.  Then create a screen dump
again, using a different file name: >
	:call term_dumpwrite(88, "test.dump")

To assert that the files are exactly the same use |assert_equalfile()|: >
	call assert_equalfile("mysyntax.dump", "test.dump")

If there are differences then v:errors will contain the error message.


Comparing screen dumps ~
						*terminal-diffscreendump*

|assert_equalfile()| does not make it easy to see what is different.
To spot the problem use |term_dumpdiff()|: >
	call term_dumpdiff("mysyntax.dump", "test.dump")

This will open a window consisting of three parts:
1.  The contents of the first dump
2.  The difference between the first and second dump
3.  The contents of the second dump

You can usually see what differs in the second part.  Use the 'ruler' to
relate it to the position in the first or second dump.  Letters indicate the
kind of difference:
	X	different character
	>	cursor in first but not in second
	<	cursor in second but not in first
	w	character width differs (single vs double width)
	f	foreground color differs
	b	background color differs
	a	attribute differs (bold, underline, reverse, etc.)
	?	character missing in both
	+	character missing in first
	-	character missing in second

Alternatively, press "s" to swap the first and second dump. Do this several
times so that you can spot the difference in the context of the text.

==============================================================================
6. Debugging				*terminal-debug* *terminal-debugger*

The Terminal debugging plugin can be used to debug a program with gdb and view
the source code in a Vim window.  Since this is completely contained inside
Vim this also works remotely over an ssh connection.

When the |+terminal| feature is missing, the plugin will use the "prompt"
buffer type, if possible.  The running program will then use a newly opened
terminal window.  See |termdebug-prompt| below for details.


Starting ~
							*termdebug-starting*
Load the plugin with this command: >
	packadd termdebug
<							*:Termdebug*
To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
command name, for example: >
	:Termdebug vim

This opens two windows:

gdb window	A terminal window in which "gdb vim" is executed.  Here you
		can directly interact with gdb.  The buffer name is "!gdb".

program window	A terminal window for the executed program.  When "run" is
		used in gdb the program I/O will happen in this window, so
		that it does not interfere with controlling gdb.  The buffer
		name is "gdb program".

The current window is used to show the source code.  When gdb pauses the
source file location will be displayed, if possible.  A sign is used to
highlight the current position, using highlight group debugPC.	 

If the buffer in the current window is modified, another window will be opened
to display the current gdb position.  You can use `:Winbar` to add a window
toolbar there.

Focus the terminal of the executed program to interact with it.  This works
the same as any command running in a terminal window.

When the debugger ends, typically by typing "quit" in the gdb window, the two
opened windows are closed.

Only one debugger can be active at a time.
							*:TermdebugCommand*
If you want to give specific commands to the command being debugged, you can
use the `:TermdebugCommand` command followed by the command name and
additional parameters. >
	:TermdebugCommand vim --clean -c ':set nu'

Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
argument to start the command right away, without pausing at the gdb window
(and cursor will be in the debugged window).  For example: >
	:TermdebugCommand! vim --clean

To attach gdb to an already running executable or use a core file, pass extra
arguments.  E.g.: >
	:Termdebug vim core
	:Termdebug vim 98343

If no argument is given, you'll end up in a gdb window, in which you need to
specify which command to run using e.g. the gdb `file` command.


Example session ~
							*termdebug-example*
Start in the Vim "src" directory and build Vim: >
	% make
Start Vim: >
	% ./vim
Load the termdebug plugin and start debugging Vim: >
	:packadd termdebug
	:Termdebug vim
You should now have three windows:
    source  - where you started, has a window toolbar with buttons
    gdb	    - you can type gdb commands here
    program - the executed program will use this window

You can use CTRL-W CTRL-W or the mouse to move focus between windows.
Put focus on the gdb window and type: >
	break ex_help
	run
Vim will start running in the program window. Put focus there and type: >
	:help gui
Gdb will run into the ex_help breakpoint.  The source window now shows the 
ex_cmds.c file.  A red "1 " marker will appear in the signcolumn where the
breakpoint was set.  The line where the debugger stopped is highlighted.  You
can now step through the program.  Let's use the mouse: click on the "Next"
button in the window toolbar.  You will see the highlighting move as the
debugger executes a line of source code.

Click "Next" a few times until the for loop is highlighted.  Put the cursor on
the end of "eap->arg", then click "Eval" in the toolbar.  You will see this
displayed:
	"eap->arg": 0x555555e68855 "gui" ~
This way you can inspect the value of local variables.  You can also focus the
gdb window and use a "print" command, e.g.: >
	print *eap
If mouse pointer movements are working, Vim will also show a balloon when the
mouse rests on text that can be evaluated by gdb.

Now go back to the source window and put the cursor on the first line after
the for loop, then type: >
	:Break
You will see a ">>" marker appear, this indicates the new breakpoint.  Now
click "Cont" in the toolbar and the code until the breakpoint will be
executed.

You can type more advanced commands in the gdb window.  For example, type: >
	watch curbuf
Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
will now continue until the value of "curbuf" changes, which is in do_ecmd().
To remove this watchpoint again type in the gdb window: >
	delete 3

You can see the stack by typing in the gdb window: >
	where
Move through the stack frames, e.g. with: >
	frame 3
The source window will show the code, at the point where the call was made to
a deeper level.


Stepping through code ~
							*termdebug-stepping*
Put focus on the gdb window to type commands there.  Some common ones are:
- CTRL-C	interrupt the program
- next		execute the current line and stop at the next line
- step		execute the current line and stop at the next statement,
		entering functions
- finish	execute until leaving the current function
- where		show the stack
- frame N	go to the Nth stack frame
- continue	continue execution

						*:Run* *:Arguments*
In the window showing the source code these commands can be used to control
gdb:
 `:Run` [args]	    run the program with [args] or the previous arguments
 `:Arguments` {args}  set arguments for the next `:Run`

 *:Break*	set a breakpoint at the current line; a sign will be displayed
 *:Clear*	delete the breakpoint at the current line

 *:Step*	execute the gdb "step" command
 *:Over*	execute the gdb "next" command (`:Next` is a Vim command)
 *:Finish*	execute the gdb "finish" command
 *:Continue*	execute the gdb "continue" command
 *:Stop*	interrupt the program

If 'mouse' is set the plugin adds a window toolbar with these entries:
  Step		`:Step`
  Next		`:Over`
  Finish	`:Finish`
  Cont		`:Continue`
  Stop		`:Stop`
  Eval		`:Evaluate`
This way you can use the mouse to perform the most common commands.  You need
to have the 'mouse' option set to enable mouse clicks.
								*:Winbar*
You can add the window toolbar in other windows you open with: >
  :Winbar

If gdb stops at a source line and there is no window currently showing the
source code, a new window will be created for the source code.  This also
happens if the buffer in the source code window has been modified and can't be
abandoned.

Gdb gives each breakpoint a number.  In Vim the number shows up in the sign
column, with a red background.  You can use these gdb commands:
- info break	list breakpoints
- delete N	delete breakpoint N
You can also use the `:Clear` command if the cursor is in the line with the
breakpoint, or use the "Clear breakpoint" right-click menu entry.


Inspecting variables ~
					*termdebug-variables* *:Evaluate*
 `:Evaluate`	    evaluate the expression under the cursor
 `K`		    same
 `:Evaluate` {expr}   evaluate {expr}
 `:'<,'>Evaluate`     evaluate the Visually selected text

This is similar to using "print" in the gdb window.
You can usually shorten `:Evaluate` to `:Ev`.


Other commands ~
							*termdebug-commands*
 *:Gdb*	     jump to the gdb window
 *:Program*    jump to the window with the running program
 *:Source*     jump to the window with the source code, create it if there
	     isn't one


Prompt mode ~
						*termdebug-prompt*
When the |+terminal| feature is not supported and on MS-Windows, gdb will run
in a buffer with 'buftype' set to "prompt".  This works slightly differently:
- The gdb window will be in Insert mode while typing commands.  Go to Normal
  mode with <Esc>, then you can move around in the buffer, copy/paste, etc.
  Go back to editing the gdb command with any command that starts Insert mode,
  such as `a` or `i`.
- The program being debugged will run in a separate window.  On MS-Windows
  this is a new console window.  On Unix, if the |+terminal| feature is
  available a Terminal window will be opened to run the debugged program in.

						*termdebug_use_prompt*
Prompt mode can be used even when the |+terminal| feature is present with: >
	let g:termdebug_use_prompt = 1


Communication ~
						*termdebug-communication*
There is another, hidden, buffer, which is used for Vim to communicate with
gdb.  The buffer name is "gdb communication".  Do not delete this buffer, it
will break the debugger.

Gdb has some weird behavior, the plugin does its best to work around that.
For example, after typing "continue" in the gdb window a CTRL-C can be used to
interrupt the running program.  But after using the MI command
"-exec-continue"  pressing CTRL-C does not interrupt.  Therefore you will see
"continue" being used for the `:Continue` command, instead of using the
communication channel.


Customizing ~

GDB command						 *termdebug-customizing*

To change the name of the gdb command, set the "termdebugger" variable before
invoking `:Termdebug`: >
	let termdebugger = "mygdb"
<							*gdb-version*
Only debuggers fully compatible with gdb will work.  Vim uses the GDB/MI
interface.  The "new-ui" command  requires gdb version 7.12 or later.  if you
get this error:
	Undefined command: "new-ui". Try "help".~
Then your gdb is too old.


Colors						*hl-debugPC* *hl-debugBreakpoint*

The color of the signs can be adjusted with these highlight groups:
- debugPC		the current position
- debugBreakpoint	a breakpoint

The defaults are, when 'background' is "light":
  hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
  hi debugBreakpoint term=reverse ctermbg=red guibg=red

When 'background' is "dark":
  hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
  hi debugBreakpoint term=reverse ctermbg=red guibg=red


Shortcuts						*termdebug_shortcuts*

You can define your own shortcuts (mappings) to control gdb, that can work in
any window, using the TermDebugSendCommand() function.  Example: >
	map ,w :call TermDebugSendCommand('where')<CR>
The argument is the gdb command.


Popup menu						*termdebug_popup*

By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
these entries to the popup menu:
	Set breakpoint		`:Break`
	Clear breakpoint	`:Clear`
	Evaluate		`:Evaluate`
If you don't want this then disable it with: >
	let g:termdebug_popup = 0


Vim window width						*termdebug_wide*

To change the width of the Vim window when debugging starts, and use a
vertical split: >
  let g:termdebug_wide = 163
This will set &columns to 163 when `:Termdebug` is used.  The value is restored
when quitting the debugger.
If g:termdebug_wide is set and &columns is already larger than
g:termdebug_wide then a vertical split will be used without changing &columns.
Set it to 1 to get a vertical split without every changing &columns (useful
for when the terminal can't be resized by Vim).



 vim:tw=78:ts=8:noet:ft=help:norl: