-
Notifications
You must be signed in to change notification settings - Fork 33
/
Copy pathterminal.jax
1756 lines (1422 loc) · 83.5 KB
/
terminal.jax
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
*terminal.txt* For Vim バージョン 9.1. Last change: 2025 Feb 22
VIMリファレンスマニュアル by Bram Moolenaar
端末ウィンドウサポート *terminal* *terminal-window*
端末機能はオプションなので、あなたのVimが対応しているかは次のコマンドを使って
確認できる: >
echo has('terminal')
結果が "1" の場合、対応している。
1. 基本的な使い方 |terminal-use|
キー入力 |terminal-typing|
サイズと色 |terminal-size-color|
文法 |:terminal|
サイズ変更 |terminal-resizing|
端末モード |Terminal-mode|
カーソルスタイル |terminal-cursor-style|
セッション |terminal-session|
特別なキー |terminal-special-keys|
Unix |terminal-unix|
MS-Windows |terminal-ms-windows|
2. 端末関数 |terminal-function-details|
3. 端末通信 |terminal-communication|
Vim からジョブへ: term_sendkeys() |terminal-to-job|
ジョブから Vim へ: JSON API |terminal-api|
クライアントサーバー機能を使う |terminal-client-server|
4. リモートテスト |terminal-testing|
5. 画面ダンプの差分 |terminal-diff|
Vimの画面ダンプテストを書く |terminal-dumptest|
画面ダンプを作成する |terminal-screendump|
画面ダンプを比較する |terminal-diffscreendump|
6. デバッグ |terminal-debug|
はじめに |termdebug-starting|
セッション例 |termdebug-example|
コードをステップ実行する |termdebug-stepping|
変数を検査する |termdebug-variables|
スタックフレームの移動 |termdebug-frames|
その他のコマンド |termdebug-commands|
イベント |termdebug-events|
プロンプトモード |termdebug-prompt|
マッピング |termdebug-mappings|
通信 |termdebug-communication|
カスタマイズ |termdebug-customizing|
{Vimが |+terminal| 機能付きでコンパイルされたときのみ有効}
端末機能を使うには |+job| と |+channel| 機能が必要である。
==============================================================================
1. 基本的な使い方 *terminal-use*
これは Vim のウィンドウ内で端末エミュレーターを実行する機能である。端末エミュ
レーターに接続すると1つのジョブが開始される。例としてシェルを実行する場合は以
下のようになる: >
:term bash
またビルドコマンドを実行するにはこうなる: >
:term make myprogram
ジョブはVimとは非同期的に動作し、他のウィンドウで編集中であってもジョブからの
出力は随時端末ウィンドウに反映される。
キー入力 ~
*terminal-typing*
端末ウィンドウにキーボードのフォーカスがある時には、入力したキーはジョブに送ら
れる。これには可能ならば pty を使用する。端末ウィンドウ外をクリックすれば、キー
ボードフォーカスを外に動かせる。
*t_CTRL-W_CTRL-W* *t_CTRL-W_:*
ウィンドウや他の CTRL-W コマンドを操作するために CTRL-W を使える。例えば:
CTRL-W CTRL-W 次のウィンドウにフォーカスを移動する
CTRL-W : Exコマンドに入る
他のコマンドについては |CTRL-W| を参照。
端末ウィンドウでの特別な操作: *t_CTRL-W_.* *t_CTRL-W_N*
CTRL-W . 端末内のジョブに CTRL-W を送る
CTRL-W CTRL-\ 端末内のジョブに CTRL-\ を送る
CTRL-W N 端末ノーマルモードに移行、|Terminal-mode| を参照
CTRL-\ CTRL-N 端末ノーマルモードに移行、|Terminal-mode| を参照
CTRL-W " {reg} レジスタ {reg} の内容を貼り付け *t_CTRL-W_quote*
式の評価結果を挿入するためのレジスタ = も機能する
CTRL-W CTRL-C ジョブを停止する。下記の |t_CTRL-W_CTRL-C| を参照
CTRL-W gt 次のタブページに移動する。`gt` と同じ *t_CTRL-W_gt*
CTRL-W gT 前のタブページに移動する。`gT` と同じ *t_CTRL-W_gT*
CTRL-W の代わりに別のキーを使うにはオプション 'termwinkey' を参照。但し、
'termwinkey' を2回タイプすると 'termwinkey' がジョブへ送信される。例:
'termwinkey' CTRL-W 次のウィンドウにフォーカスを移動する
'termwinkey' : Exコマンドに入る
'termwinkey' 'termwinkey' 端末内のジョブに 'termwinkey' を送信する
'termwinkey' . 端末内のジョブに 'termwinkey' を送信する
'termwinkey' CTRL-\ 端末内のジョブに CTRL-\ を送信する
'termwinkey' N 端末ノーマルモードへ移行する。以下を参照
'termwinkey' CTRL-N CTRL-W N と同じ |t_CTRL-W_N|
'termwinkey' CTRL-C CTRL_W CTRL_C と同じ |t_CTRL-W_CTRL-C|
*t_CTRL-\_CTRL-N*
他のモードと同じように、ノーマルモードへ移行するための特別なキーの組み合わせで
ある CTRL-\ CTRL-N が使用できる。
*t_CTRL-W_CTRL-C*
ジョブを強制停止するのに CTRL-W CTRL-C を使える。MS-Windowsでは CTRL-Break で
も同様にジョブを停止できる。
CTRL-C を入力した場合、その効果は pty がどのように構成されているかに従う。シン
プルなコマンドにおいては SIGINT がジョブに送られ、結果的にジョブが停止するだろ
う。中には SIGINT を無視するコマンドもあるだろうし、また (Vim がそうしているよ
うに) CTRL-C をプログラム自身で取り扱うものもあるだろう。
入力したキーを別のものに読み替えさせるには端末モードマッピング、詳細は |:tmap|
を参照。これはどのようなマッピングでも定義できるが、端末内で実行されているジョ
ブに送信されるキー入力にのみ作用する。例えば、F1 キーで端末ノーマルモードに切
り替えるには: >
tnoremap <F1> <C-W>N
Esc を使うことができるが、他のキーが壊れないようにする必要がある (カーソルキー
は Esc で始まるので、それらは壊れるかもしれない)、これはおそらくGUIでしか動作
しない: >
tnoremap <Esc> <C-W>N
set notimeout ttimeout timeoutlen=100
端末モードマッピングと同様にメニューを作成することもできるが、|:tmenu| ではな
く |:tlmenu| を使用する必要がある。
*options-in-terminal*
端末ウィンドウを開いて 'buftype' を "terminal" に設定すると、TerminalWinOpen
自動コマンドイベントが発生する。これにより、端末ウィンドウとバッファ専用のオプ
ションを設定することが可能である。例: >
au TerminalWinOpen * setlocal bufhidden=hide
これが適切に動作するのは端末が隠れていない場合に限られる。
端末が隠れている場合と隠れていない場合両方で動作するのは、バッファローカルと
ウィンドウローカルのオプションである: >
au TerminalWinOpen,BufWinEnter * if &buftype == 'terminal'
\ | setlocal bufhidden=hide colorcolumn=123
\ | endif
Note この隠れている端末のオプションは端末が隠れている間は値が設定されない。
|TerminalOpen| イベントもある。これは隠れた端末で発生するかもしれず、その場合
は現在のウィンドウとバッファはこの新しい端末ではないことに注意。
端末バッファに設定する場合、<abuf> を使う必要がある。例: >
au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(),
\ '&termwinscroll', 1000)
ウィンドウローカルオプションは、端末ウィンドウが生成されるまで設定が遅延する必
要がある (これは隠れた端末だけで作用する): >
au TerminalOpen * exe printf(
\ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d',
\ expand('<abuf>')->str2nr(), 123)
隠れていない端末では |TerminalWinOpen| を使う。
マウスイベント (クリックやドラッグ) は端末に渡される。マウス移動イベントは Vim
自身が受け取ったときにのみ渡される。'balloonevalterm' が有効になっている端末の
場合。
サイズと色 ~
*terminal-size-color*
端末ウィンドウのサイズを制御するにはオプション 'termwinsize' を参照。
(TODO: 端末がウィンドウよりも大きい場合にはスクロールすることを記述する)
端末内のジョブは端末の色を変更できる。デフォルトの前景色及び背景色はVimの
Normal ハイライトグループにより決定される。
カラー端末を開始する際に、背景に白と黒どちらの系統の色を使用するかは、オプショ
ン 'background' を用いて決定する。
異なる色を使う場合には Terminal ハイライトグループを利用できる。例: >
hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
もしくは Terminal の代わりとして`term_start()` のオプション "term_highlight"
で別グループを設定できる。
*g:terminal_ansi_colors*
新しい端末ウィンドウでデフォルトで使用される 16 個の ANSI カラーは、変数
`g:terminal_ansi_colors` を使用して設定することができる。これは、16 個の色名ま
たは 16 進数の色コードのリストでなければならない。これは、|highlight-guifg| で
受け入れられるものと同様である。GUI カラーを使用しない場合、端末ウィンドウは常
に元の端末の 16 個の ANSI カラーを使用する。
`term_start()` を使う時、"ansi_colors" オプションにより色が設定できる。
|term_setansicolors()| 関数を使用して色を変更したり、|term_getansicolors()| を
使用して現在使用されている色を取得することができる。
コマンド文法 ~
:[range]ter[minal] [options] [command] *:ter* *:terminal*
新しい端末ウィンドウを開く。
[command] が指定された場合、それをジョブとして実行し、
端末の入出力を接続する。
[command] が指定されなかった場合、オプション 'shell'
を使用する。
[command] が NONE の場合ジョブは開始されず、端末の pty
は gdb のようなコマンドによって利用できる。
[command] が NUL バイト列を出力する場合、それらは NL
群に変換される |NL-used-for-Nul|。
*terminal-nospecial*
Vim 自体は [command] 内の |cmdline-special| 文字のみを
認識する。その他はすべてそのまま渡される。ワイルドカー
ド、環境変数、またはその他のシェル特殊文字を展開する必
要がある場合は、|term++shell| オプションを検討するこ
と。
[command] がない場合、デフォルトの動作はシェルが終了し
たときに端末を閉じる。この動作は ++noclose 引数で変更
できる。
[command] が指定されている場合、デフォルトの動作は端末
を端末ノーマルモードで開いたままにする。この動作は
++close 引数で変更できる。
Vimのコマンドを後ろに続けることはできず、どんな | も
[command] に含まれてしまう。
同じ行で Vim コマンドを続けたい場合、`:execute` を使用
する。
*terminal-bufname*
新しいバッファが作られ、[command] もしくは 'shell' に
"!" が前置された名前が与えられる。すでに同じ名前のバッ
ファが存在する場合には、カッコに囲まれた番号が付与され
る。例えば "gdb" が存在するなら2つ目の端末には
"!gdb (1)" という名前が使われる。
[range] が与えられた場合は、指定された範囲の行がジョブ
の入力として使われる。その際の端末ウィンドウではキー
入力ができなくなる。MS-Windows においては以下の ++eof
オプションも参照。
*term++close* *term++open*
サポートされる [options] は以下の通り:
++close ジョブが終了した際には自動的に端末ウィ
ンドウを閉じる。 |terminal-close|
++noclose ジョブが終了しても自動的に端末ウィンド
ウを閉じない。
++open ジョブが終了した際にウィンドウが表示さ
れていない場合に、ウィンドウを表示す
る。割り込み的に発生しうることに留意。
++close, ++noclose と ++open は最後に指定され
たものが有効である。
++curwin 現在のウィンドウで端末を開き、現在の
ウィンドウを分割しない。現在のバッファ
を放棄 (|abandon|) できない場合は失敗
する。
++hidden 端末を隠しバッファとして開く。ウィンド
ウは使用されない。
++norestore セッションファイルに端末ウィンドウを含
めない。
*term++shell*
++shell {command} を直接実行するのではなく、
`:!command` と同様にシェルを使用する。
*E279*
{Vim: UnixとMS-Windowsでのみ動作する}
結果のコマンドは次のようになる
'shell' 'shellcmdflag' [command]
`:!command` に関連するその他のオプショ
ンは効果がない。
++kill={how} 端末ウィンドウを閉じるときに {how} で
ジョブを終了させる。値については
|term_setkill()| を参照。
++rows={height} 端末ウィンドウの高さとして {height} を
使う。もし、端末がVimの完全な高さ(端末
ウィンドウの上や下にウィンドウがない)
を使用する場合、必要に応じてコマンドラ
インの高さが減少する。
++cols={width} 端末ウィンドウの幅として {width} を使
う。もし、端末がVimの完全な幅(端末ウィ
ンドウの左か右にウィンドウがない)を使
用する場合、この値は無視される。
++eof={text} [range] を使った場合: 最後の行を送信し
たあとに指定したテキストが送られる。空
白を含むことはできない。CR が 1 つ付け
加えられる。MS-Windows ではデフォルト
では CTRL-D が送られる。
例: シェルには "++eof=exit" を、Python
には "++eof=exit()" を指定する。特殊
コードが `:map` と同様に利用できる。
例: "<C-Z>" は CTRL-Z を示す。
++type={pty} (MS-Windowsのみ): 仮想コンソールとして
{pty} を使用する。値については
'termwintype' を参照。
++api={expr} {expr} で始まる関数名を |terminal-api|
機能として呼び出すことを許可する。
{expr} が空の場合、関数を呼び出すこと
はできない。
より詳細なオプションを使いたい場合は |term_start()| 関
数を使用する。
ウィンドウを縦分割するには、次のようにする: >
:vertical terminal
< または短縮形: >
:vert ter
端末に関連付けられたバッファが強制的にアンロードもしくは削除された場合には、
`job_stop(job, "kill")` を呼んだのと同じようにそのジョブが殺される。
普通にウィンドウを閉じると |E947| が返る。killメソッドが "++kill={how}" か
|term_setkill()| で設定されている時にウィンドウを閉じると、その方法でジョブを
強制終了または中断する。例: >
:term ++kill=term tail -f /tmp/log
ジョブが実行され続けるとウィンドウはそのバッファが変更されたかのように振る舞
う。`CTRL-W :quit` でウィンドウを閉じようとしても失敗する。`CTRL-W :quit!` を
使うとジョブは終了する。ウィンドウのテキストは失われ、バッファは削除される。
`CTRL-W :bunload!` はバッファは残るが、空になる。
`CTRL-W :close` で閉じようとしても失敗する。`CTRL-W :close!` はウィンドウを閉
じ、バッファを隠し状態にする。
`CTRL-W :hide` を使うとジョブを実行したまま、端末ウィンドウを閉じバッファを隠
し状態にできる。`:buffer` コマンドで現在のウィンドウを端末ウィンドウにすること
ができる。未保存の変更があった場合にはこれは失敗するが、通常と同じように ! で
強制できる。
*terminal-close*
端末ジョブが終了し、[commmand] が指定されなかった場合 (例えば、'shell' コマン
ドが実行された)、端末ウィンドウはデフォルトで閉じられる (ただし、空間を受け取
る次のウィンドウのバッファに 'nobuflisted' オプションが設定されている場合を除
く。その場合、端末ウィンドウは自動的に閉じられないが、そのウィンドウで新しい空
のバッファが開かれる)。
端末ウィンドウが閉じられるとき、例えば、シェルが終了し、"++close" 引数が使用さ
れ、これが最後の通常のVimウィンドウである場合、Vimは終了する。これは、通常の
ウィンドウで |:quit| を使用するようなものだ。ヘルプウィンドウとプレビューウィ
ンドウはカウントされない。
バックグラウンドジョブをウィンドウ無しで実行し、終了したらウィンドウに表示する
には、次のようにオプションを指定する: >
:term ++hidden ++open make
Note ウィンドウが予期せぬタイミングで開かれ、あなたが行っている操作に割り込む
可能性があることに注意。
*E947* *E948*
ジョブが実行され続けると、バッファが変更されたとみなされ Vim を簡単には終了で
きなくなる。|abandon| を参照。
ジョブが終了しバッファに何の変更も及ぼさなかった場合、そのウィンドウを閉じると
バッファは削除される。
端末バッファを変更するにはオプション 'modifiable' をセットする必要がある。これ
はジョブが終了した後にのみ行なえる。バッファを最初に変更した瞬間に普通のバッ
ファになりハイライトは削除される。バッファを保存可能にするために |:file| でバッ
ファの名前を、コマンド名から変更することもできる。
サイズ変更 ~
*terminal-resizing*
端末のサイズは3つのモードのいずれか1つで決まる:
1. オプション 'termwinsize' が空の場合: 端末サイズはウィンドウのサイズに従う。
最小で2行、10桁。
2. オプション 'termwinsize' が "rows*cols" の場合、"rows" を最小行数、"cols"
を最小桁数とする。
3. オプション 'termwinsize' が "rowsXcols" ("X" は大文字小文字を問わない) の場
合、端末サイズは指定された行数と桁数で固定される。もしもウィンドウがそれよ
りも大きい場合には、使用されない空の領域ができる。
ウィンドウサイズが端末サイズよりも小さい場合、端末の一部の領域(左下に相当する
部分)のみが描画される。
端末の現在のサイズを取得するのに関数 |term_getsize()| が使える。
|term_setsize()| は 1 か 2 のモードの時にだけ、すなわち 'termwinsize' が
"rowsXcols" 形式ではない時に使える。
端末ジョブモードと端末ノーマルモード ~
*Terminal-mode* *Terminal-Job*
ジョブが実行中には端末の内容はジョブの制御下にある。それにはカーソルの位置も含
まれる。入力したキーはジョブに送られる。端末の内容はいつでも更新されえる。これ
を端末ジョブモードと呼ぶ。
CTRL-W N (もしくは 'termwinkey' N) を入力すると 端末ノーマルモードに遷移する。
このモードでは端末ウィンドウのコンテンツはVimの制御下に置かれ、ジョブの出力は
一時保留される。CTRL-\ CTRL-N でも同様。
|:tmap| のマッピングは 端末ジョブモードにおいて作用する。|term_sendkeys()| で
送ったキーには tmap は適用されないが、|feedkeys()| で送ったキーには適用される。
端末ジョブモードから挿入モードに入ることはできない。
*Terminal-Normal* *E946*
端末ノーマルモードでは、Vimの普通のコマンドでカーソルを自由に動かせる。視覚的
にテキストをマークしたり、テキストをヤンクしたり思いのままである。しかしバッ
ファの内容を変更することはできない。'i' や 'a' など挿入モードを開始するコマン
ドを使うと 端末ジョブモードに戻る。結果としてウィンドウは端末のコンテンツを反
映させるために更新される。|:startinsert| は無効である。
端末ノーマルモードではステータスラインとウィンドウタイトルには "(Terminal)" と
表示される。端末ノーマルモード中にジョブが終了してしまった場合にはそれが
"(Terminal-finished)" に変わる。
ジョブが端末内で行を出力し内容が上からスクロールすると、それらの行は記憶され端
末ノーマルモードで表示される。行数は 'termwinscroll' オプションによって制限さ
れる。この制限を超えると、スクロールされた行の最初の10％が削除されて失われる。
カーソルスタイル ~
*terminal-cursor-style*
デフォルトでは端末ウィンドウのカーソルには点滅しないブロックが使われる。カーソ
ルの点滅状態や形を変更するのに、普通の xterm のエスケープシーケンスが使われる。
端末ウィンドウからフォーカスが外れる際に Vim は元々のカーソルを復元する。
xterm を "-bc" 引数で起動した場合、または他の方法でカーソルの点滅を発生させた
場合、が1つの例外となる。それらにより点滅フラグが逆転したことが問題の引き金と
なる。なぜなら Vim はその逆転を検出できず、端末ウィンドウのカーソルの点滅も逆
転する。
セッション ~
*terminal-session*
可能かつ必要であれば、セッションファイルを使用する際に端末ウィンドウが復元され
る。
"terminal" が 'sessionoptions' から削除された場合、端末ウィンドウは復元されな
い。
端末内のジョブが終了した場合、ウィンドウは復元されない。
端末を復元できる場合は、その端末を開くために使用されたコマンドが再び使われる。
これを変更するには |term_setrestore()| 関数を使用する。これは、コマンドを
"NONE" に設定して特定の端末を復元しない場合にも使用できる。
特別なキー ~
*terminal-special-keys*
端末エミュレータは xterm をシミュレートするため、端末ウィンドウでは Vim と
xterm の両方が認識するエスケープシーケンスのみを使用できる。端末で実行中のジョ
ブに他のエスケープシーケンスを渡したい場合は、転送を設定する必要がある。例: >
tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
func SendToTerm(what)
call term_sendkeys('', a:what)
return ''
endfunc
Unix ~
*terminal-unix*
UNIX ではすべての種類のコマンドを実行可能とするために pty を用いている。端末内
で Vim ですら実行できる! これは以下のようにデバッグに使用される。
実行中のジョブに情報を伝えるために以下の環境変数が使用される:
TERM 端末の名前、'term' オプションまたはGUIでは $TERM から。
"xterm" で始まらなければ "xterm" にフォールバックする
ROWS 端末の初期行数
LINES ROWS と同じ
COLUMNS 端末の初期桁数
COLORS 色数 't_Co' (GUIでは 256*256*256)
VIM_SERVERNAME v:servername
VIM_TERMINAL v:version
MS-Windows ~
*terminal-ms-windows*
MS-Windows ではすべての種類のコマンドを実行可能とするために winpty を用いてい
る。あたりまえのことだが、ここで実行するコマンドは端末の中で動くもので、独自の
ウィンドウを開くものであってはならない。
winpty 内の以下の2つのファイルが必要である:
winpty.dll
winpty-agent.exe
これらは以下のページからダウンロードできる:
https://github.com/rprichard/winpty
これらのファイルを環境変数 PATH のいずれかに置くだけだ。必要ならばオプション
'winptydll' でファイルの場所を指定できる。もしも32ビット版と64ビット版を同じ
ディレクトリに置きたいのであれば、Vimのビルドに合わせてそれぞれを winpty32.dll
もしくは winpty64.dll という名前に変更すること。
*ConPTY* *E982*
MS-Windows 10の最新バージョン("October 2018 Update" 以降)では、winpty は必要な
くなった。それらのバージョンでは、|:terminal| はターミナルアプリケーションをホ
ストするためのWindowsの組み込みサポート "ConPTY" を使用する。ConPTY が使用され
ている場合、あいまいな幅の文字に関するレンダリングアーティファクトが発生する可
能性がある。そのような問題に遭遇した場合は、"winpty" をインストールすること。
ConPTY の問題が修正されるまでは、"winpty" が優先される。
環境変数は実行中のジョブに情報を渡すために使用される:
VIM_SERVERNAME v:servername
*git-vimdumps*
`git-vimdumps` という git-difftool 拡張機能があり、これを使用するとスクリーン
ダンプファイルを簡単に検査して比較することができる。この git 拡張機能の作成方
法と使用方法については、Vim リポジトリのファイル `src/testdir/commondumps.vim`
を参照。
==============================================================================
2. 端末関数 *terminal-function-details*
*term_dumpdiff()*
term_dumpdiff({filename}, {filename} [, {options}])
2 つのファイルの差分を表示する新しいウィンドウを開く。これらの
ファイルは |term_dumpwrite()| で作られたものでなければならな
い。
差分の検出に失敗したときはバッファ番号もしくは 0 を返す。
|terminal-diff| も参照。
NOTE: これは 2 倍幅文字ではまだ機能しない。
バッファの先頭部分は 1 つ目のファイルの内容を含み、バッファの
末尾部分は 2 つ目のファイルの内容を含む。中央部分は差分を表示
する。
それぞれの部分はイコールの行で分割される。
引数 {options} は辞書でなければらなず、以下のメンバを含むこと
ができる:
"term_name" (1 つ目のファイル名の代わりに使用される)
バッファ名
"term_rows" ('termwinsize' の代わりに使用される) 端末
の垂直サイズ、ただし最小サイズは尊重する
"term_cols" ('termwinsize' の代わりに使用される) 端末
の水平サイズ、ただし最小サイズは尊重する
"vertical" ウィンドウを垂直に分割する
"curwin" ウィンドウを分割せず現在のウィンドウを使
用する、現在のバッファが放棄 (|abandon|)
不可の場合は失敗する
"bufnr" 新しいバッファを作成せずに、既存のバッファ
"bufnr" を使用する。このバッファは前もっ
て term_dumpdiff() または term_dumpload()
で作成され、ウィンドウに表示されていなけ
ればならない。
"norestore" 端末ウィンドウをセッションファイルに加え
ない
中央部分のそれぞれの文字は違いを表示している。複数の違いがあっ
た場合は以下のリスト内の最初のものだけが使用される:
X 異なる文字
w 異なる幅
f 異なる文字色
b 異なる背景色
a 異なる属性
+ 1 つ目のファイル内に存在しない位置
- 2 つ目のファイル内に存在しない位置
> 2 つ目のファイルにはなく1 つ目のファイルにある
現在のカーソル位置
< 1 つ目のファイルにはなく2 つ目のファイルにある
現在のカーソル位置
"s" キーを押すと、先頭部分と末尾部分が入れ替わる。これにより差
分を簡単に確認することができる。
|method| としても使用できる: >
GetFilename()->term_dumpdiff(otherfile)
<
戻り値の型: |Number|
term_dumpload({filename} [, {options}]) *term_dumpload()*
{filename} の内容を表示する新しいウィンドウを開く。このファイ
ルは |term_dumpwrite()| で作られたものでなければならない。
失敗したときはバッファ番号もしくは 0 を返す。
|terminal-diff| も参照。
{options} については |term_dumpdiff()| を参照。
|method| としても使用できる: >
GetFilename()->term_dumpload()
<
戻り値の型: |Number|
term_dumpwrite({buf}, {filename} [, {options}]) *term_dumpwrite()*
ファイル {filename} に、{buf} の端末画面の内容をダンプする。こ
れは |term_dumpload()| および |term_dumpdiff()| で使われる
フォーマットを使用する。
端末のジョブがすでに終了していた場合はエラーが発生する: *E958*
{filename} が既に存在する場合はエラーが発生する: *E953*
|terminal-diff| も参照。
{options} は以下のオプショナルな要素を含む辞書である:
"rows" ダンプする行の最大値
"columns" ダンプする列の最大値
|method| としても使用できる、ベースはファイル名に使用される: >
GetFilename()->term_dumpwrite(bufnr)
<
戻り値の型: |Number|
term_getaltscreen({buf}) *term_getaltscreen()*
{buf} の端末が代替スクリーンを使用している場合 1 を返す。
{buf} の扱いについては |term_getsize()| と同じ。
|method| としても使用できる: >
GetBufnr()->term_getaltscreen()
<
戻り値の型: |Number|
term_getansicolors({buf}) *term_getansicolors()*
端末 {buf} で使用されている ANSI カラーパレットを取得する。
長さ 16 のリストを返し、各要は色を 16 進数の "#rrggbb" フォー
マットで表す文字列である。
|term_setansicolors()| および |g:terminal_ansi_colors| も参照。
どちらも使用されていない場合、既定値を返す。
{buf} の扱いについては |term_getsize()| と同じ。バッファが存在
しない、もしくは端末ウィンドウでない場合は、空リストが返され
る。
|method| としても使用できる: >
GetBufnr()->term_getansicolors()
<
戻り値の型: list<string> または list<any>
{GUI が有効もしくは |+termguicolors| 機能付きでコンパイルされ
たときのみ有効}
term_getattr({attr}, {what}) *term_getattr()*
term_scrape() で返された項目 "attr" の値である {attr} につい
て、{what} がオンになっているかを返す。{what} は次のうちどれか
1 つである:
bold
italic
underline
strike
reverse
|method| としても使用できる: >
GetAttr()->term_getattr()
<
戻り値の型: |Number|
term_getcursor({buf}) *term_getcursor()*
端末 {buf} のカーソル位置を取得する。2 つの数値と辞書から構成
されるリストを返す: [row, col, dict]。
"row" および "col" は 1 を基準とし、最初のスクリーンセルは、
行 1、列 1 である。これは端末自身のカーソル位置であり、Vim ウィ
ンドウのものではない。
"dict" は以下 3 つのメンバを持つ:
"visible" カーソルが可視のときは 1、不可視のときは 0
"blink" カーソルが点滅のときは 1、非点滅のときは 0
"shape" ブロックカーソルは 1、下線は 2、垂直線は 3
"color" カーソルの色。例: "green"
{buf} は端末ウィンドウのバッファ番号でなければならない。バッ
ファが存在しない、もしくは端末ウィンドウでない場合は、空リスト
が返される。
|method| としても使用できる: >
GetBufnr()->term_getcursor()
<
戻り値の型: list<any>
term_getjob({buf}) *term_getjob()*
端末ウィンドウ {buf} に関連付いたジョブを取得する。
{buf} の扱いについては |term_getsize()| と同じ。
ジョブがない場合は |v:null| を返す。Vim9 script では、ジョブが
ない場合 |null_job| を返す。
|method| としても使用できる: >
GetBufnr()->term_getjob()
<
戻り値の型: |job|
term_getline({buf}, {row}) *term_getline()*
端末ウィンドウ {buf} から行のテキストを取得する。
{buf} の扱いについては |term_getsize()| と同じ。
先頭行の {row} は 1 である。{row} が "." のときはカーソル行が
使われる。{row} が無効のときは空文字列が返される。
各文字の属性を取得するには |term_scrape()| を使用する。
|method| としても使用できる: >
GetBufnr()->term_getline(row)
<
戻り値の型: |String|
term_getscrolled({buf}) *term_getscrolled()*
端末 {buf} の先頭から上方にスクロールされた行の数を返す。これ
は |term_getline()| および |getline()| で使われる行番号のオフ
セットとなるので: >
term_getline(buf, N)
< は以下と等しい: >
getline(N + term_getscrolled(buf))
< (もしその行が存在していれば)。
{buf} の扱いについては |term_getsize()| と同じ。
|method| としても使用できる: >
GetBufnr()->term_getscrolled()
<
戻り値の型: |Number|
term_getsize({buf}) *term_getsize()*
端末 {buf} のサイズを取得する。2 つの数値を含むリストを返す:
[rows, cols]。これは端末のサイズであり、端末を含むウィンドウの
サイズではない。
{buf} は端末ウィンドウのバッファ番号でなければならない。現在の
バッファには空文字列を使用する。バッファが存在しない、もしくは
端末ウィンドウでない場合は、空リストが返される。
|method| としても使用できる: >
GetBufnr()->term_getsize()
<
戻り値の型: list<number> または list<any>
term_getstatus({buf}) *term_getstatus()*
端末 {buf} のステータスを取得する。これらの項目をコンマで区切っ
た一覧を文字列で返す:
running ジョブが実行中である
finished ジョブが完了した
normal 端末ノーマルモードである
"running" または "finished" のどちらかは常に存在する。
{buf} は端末ウィンドウのバッファ番号でなければならない。バッ
ファが存在しない、もしくは端末ウィンドウでない場合は、空文字列
が返される。
|method| としても使用できる: >
GetBufnr()->term_getstatus()
<
戻り値の型: |String|
term_gettitle({buf}) *term_gettitle()*
端末 {buf} のタイトルを取得する。これは端末内でジョブが設定し
たタイトルである。
{buf} は端末ウィンドウのバッファ番号でなければならない。バッ
ファが存在しない、もしくは端末ウィンドウでない場合は、空文字列
が返される。
|method| としても使用できる: >
GetBufnr()->term_gettitle()
<
戻り値の型: |String|
term_gettty({buf} [, {input}]) *term_gettty()*
端末ウィンドウ {buf} に関連付けられた制御端末の名前を取得する。
{buf} の扱いについては |term_getsize()| と同じ。
{input} が省略されたもしくは 0 のとき、書き込み (stdout) の名
前を返す。{input} が 1 のとき、読み込み (stdin) の名前を返す。
UNIX では両方で同じ名前が返る。
|method| としても使用できる: >
GetBufnr()->term_gettty()
<
戻り値の型: |String|
term_list() *term_list()*
すべての端末ウィンドウのバッファのバッファ番号のリストを返す。
戻り値の型: list<number> または list<any>
term_scrape({buf}, {row}) *term_scrape()*
端末スクリーン {buf} の {row} にある内容を取得する。
{buf} については |term_getsize()| を参照。
先頭行の {row} は 1 である。{row} が "." のときはカーソル行が
使用される。{row} が無効なときは空文字列が返される。
各スクリーンのセルに対する辞書を含んだリストを返す:
"chars" セルの文字
"fg" 文字色 (#rrggbb)
"bg" 背景色 (#rrggbb)
"attr" セルの属性、個々のフラグを取得するには
|term_getattr()| を使用する
"width" セルの幅: 1 もしくは 2
1項目が2セル幅の時、結果のリストは端末の幅より短くなりえる。
|method| としても使用できる: >
GetBufnr()->term_scrape(row)
<
戻り値の型: list<dict<any>> または list<any>
term_sendkeys({buf}, {keys}) *term_sendkeys()*
端末 {buf} にキー入力 {keys} を送る。
{buf} の扱いについては |term_getsize()| と同じ。
{keys} はキーシーケンスとして解釈される。例えば、"\<c-x>" は
文字 CTRL-X を意味する。
|method| としても使用できる: >
GetBufnr()->term_sendkeys(keys)
<
戻り値の型: |Number|
term_setansicolors({buf}, {colors}) *term_setansicolors()*
端末 {buf} で使用される ANSI カラーパレットを設定する。
{colors} は、|highlight-guifg| で受け付けられるような、有効な
カラー名もしくは 16 進数のカラーコードを 16 個含むリストでなけ
ればならない。
|term_getansicolors()| および |g:terminal_ansi_colors| も参照。
カラーは通常以下のとおり:
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
これらの色は、GUI 内および 'termguicolors' が設定されていると
きの端末内で使用される。GUI カラーを使用しないとき (GUI モード
もしくは 'termguicolors')、端末ウィンドウは、常に基となる端末
の 16 ANSI カラーを使用する。
|method| としても使用できる: >
GetBufnr()->term_sendkeys(keys)
<
戻り値の型: |Number|
{GUI が有効もしくは |+termguicolors| 機能付きでコンパイルされ
たときのみ有効}
term_setapi({buf}, {expr}) *term_setapi()*
端末 {buf} 内で |terminal-api| 機能に使用する関数名のプリフィッ
クスを設定する。例: >
:call term_setapi(buf, "Myapi_")
:call term_setapi(buf, "")
<
デフォルトは "Tapi_" である。{expr} が空の文字列の場合、{buf}
の |terminal-api| 機能は使用できない。
|method| としても使用できる、ベースは {buf} に使用される: >
GetBufnr()->term_setapi({expr})
<
戻り値の型: |Number|
term_setkill({buf}, {how}) *term_setkill()*
Vim が終了するもしくは何らかの方法で端末ウィンドウを閉じようと
しているとき、端末内のジョブを停止するかどうかを {how} で定義
する。
{how} が空 (既定値) のとき、ジョブは停止されない。終了しようと
すると |E947| となる。
それ以外では、{how} はジョブに何のシグナルを送るかを記述する。
値に関しては |job_stop()| を参照。
シグナルを送ったあと、Vim はジョブが実際に停止したか確認するた
めに 1 秒待つ。
|method| としても使用できる: >
GetBufnr()->term_setkill(how)
<
戻り値の型: |Number|
term_setrestore({buf}, {command}) *term_setrestore()*
この端末内のジョブを復元するためのセッションファイルを書き込む
コマンドを設定する。セッションファイル内に書き込まれる行は以下
の通り: >
terminal ++curwin ++cols=%d ++rows=%d {command}
< コマンドを適切にエスケープするよう気を付けること。
'shell' を実行するには空の {command} を使用する。
このウィンドウを復元しないためには "NONE" を使用する。
|method| としても使用できる: >
GetBufnr()->term_setrestore(command)
<
戻り値の型: |Number|
term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955*
端末 {buf} のサイズを設定する。端末を含むウィンドウのサイズが
可能であれば調整される。{rows} もしくは {cols} が、0 もしくは
負である場合、大きさは変わらない。
{buf} は端末ウィンドウのバッファ番号でなければならない。現在の
バッファには空文字列を使用する。バッファが存在しない、もしくは
端末ウィンドウでない場合は、エラーが発生する。
|method| としても使用できる: >
GetBufnr()->term_setsize(rows, cols)
<
戻り値の型: |Number|
term_start({cmd} [, {options}]) *term_start()*
端末ウィンドウを開き、その中で {cmd} を実行する。
{cmd} は |job_start()| と同じような文字列もしくはリストである。
ジョブを開始せずに端末ウィンドウを開くには、文字列 "NONE" を使
用することができ、端末の疑似端末は gdb のようなコマンドで使用
することができる。
端末ウィンドウのバッファ番号を返す。{cmd} が実行できない場合、
ウィンドウが開いてエラーメッセージを表示する。
ウィンドウを開くのに失敗すると 0 を返す。
{options} は |job_start()| で使用されるものと似ている。
|job-options| を参照。しかしながらすべてのオプションが使えるわ
けではない。サポートされているものは以下のとおり:
すべての timeout オプション
"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"
しなかしながら、少なくとも stdin、stdout もしくは stderr のう
ち 1 つは端末に接続されていなければならない。I/O が端末に接続
されているとき、その部分のコールバック機能は使用されない。
追加のオプションは以下のとおり:
"term_name" (コマンド名の代わりに使用される)バッファ
名に使用する名前。
"term_rows" ('termwinsize' の代わりに使用される) 端末
の垂直サイズ。有効範囲は0から1000。
"term_cols" ('termwinsize' の代わりに使用される) 端末
の水平サイズ
"vertical" ウィンドウを垂直に分割する。Note: 他のウィ
ンドウの位置は、|:belowright| のようなコマ
ンド修飾子によって決められる。
"curwin" ウィンドウを分割せず現在のウィンドウを使
用する、現在のバッファが放棄 (|abandon|)
不可の場合は失敗する
"hidden" ウィンドウを開かない
"norestore" 端末ウィンドウをセッションファイルに加え
ない
"term_kill" 端末ウィンドウを閉じようとしているときに
何をするか、|term_setkill()| を参照
"term_finish" ジョブが終了したときに何をするか:
"close": ウィンドウを閉じる
"open": 必要ならばウィンドウを開く
Note: "open" は割り込み的に発生する。
|term++close| および |term++open|を参照。
"term_opencmd" "term_finish" が "open" のときにウィンド
ウを開くために使用されるコマンド: バッファ
番号が入る "%d" を含む必要がある、例
"10split|buffer %d": 指定されていない場合
は "botright sbuf %d" が使用される
"term_highlight" "Terminal" の代わりにハイライトグループと
して使える
"eof_chars" すべてのバッファ行が書き込まれた後に端末
に送られるテキスト。設定されていないとき
は MS-Windows では CTRL-D が使用される。
Pythonでは CTRL-Z もしくは "exit()" を使
用する。シェルでは "exit" を使用する。常
に CR が追加される。
"exit". A CR is always added.
"ansi_colors" GUI カラーモードで使われる ANSI パレット
を定義する 16 個のカラー名もしくは 16 進
数コード。|g:terminal_ansi_colors| を参
照。
"tty_type" (MS-Windowsのみ): 使用する pty を指定す
る。値については 'termwintype' を参照。
"term_api" |terminal-api| 機能の関数名プリフィック
ス。|term_setapi()| を参照。
|method| としても使用できる: >
GetCommand()->term_start()
<
戻り値の型: |Number|
term_wait({buf} [, {time}]) *term_wait()*
{buf} で保留となっている更新が処理されるのを待つ。
{buf} の扱いについては |term_getsize()| と同じ。
{time} は更新が届くのを待つ、ミリ秒単位での長さ。設定されてい
ない場合は 10 ミリ秒が使用される。キューに入れられたメッセージ
も |:sleep| と同様に処理される。
|method| としても使用できる: >
GetBufnr()->term_wait()
<
戻り値の型: |Number|
==============================================================================
3. 端末通信 *terminal-communication*
端末内で実行中のジョブと通信するには、いくつかの方法がある:
- |term_sendkeys()| でテキストやエスケープシーケンスをVimからジョブに送信する。
- JSON APIを使用して、エンコードされたコマンドをジョブからVimに送信する。
- |client-server| 機構を使う。これは、XサーバーとMS-Windowsのマシンで動作する。