terminal.txt For Vim バージョン 9.0. Last change: 2022 Jun 09
VIMリファレンスマニュアル by Bram Moolenaar
端末ウィンドウサポート terminal terminal-window
端末機能はオプションなので、あなたのVimが対応しているかは次のコマンドを使って
確認できます:
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-commands
イベント termdebug-events
プロンプトモード termdebug-prompt
通信 termdebug-communication
カスタマイズ termdebug-customizing
{Vimが +terminal 機能付きでコンパイルされたときのみ有効}
端末機能を使うには +job と +channel 機能が必要です。
==============================================================================
1. 基本的な使い方 terminal-use
これは Vim のウィンドウ内で端末エミュレーターを実行する機能です。端末エミュレー
ターに接続すると1つのジョブが開始されます。例としてシェルを実行するならば以下
のようになります:
またビルドコマンドを実行するにはこうなります:
ジョブは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 キーで端末ノー
マルモードに切り替えるには:
ルキーは Esc で始まるので、それらは壊れるかもしれません)、これはおそらくGUIで
しか動作しません:
端末モードマッピングと同様にメニューを作成することもできますが、:tmenu ではな
く :tlmenu を使用する必要があります。
options-in-terminal
端末ウィンドウを開いて 'buftype' を "terminal" に設定すると、TerminalWinOpen
自動コマンドイベントが発生します。これにより、端末ウィンドウとバッファ専用のオ
プションを設定することが可能です。例:
端末が隠れている場合と隠れていない場合両方で動作するのは、バッファローカルと
ウィンドウローカルのオプションです:
TerminalOpen イベントもあります。これは隠れた端末で発生するかもしれず、その
場合は現在のウィンドウとバッファはこの新しい端末ではないことに注意してくださ
い。
端末バッファに設定するなら、<abuf> を使う必要があります。例:
要があります (これは隠れた端末だけで働きます):
マウスイベント (クリックやドラッグ) は端末に渡されます。マウス移動イベントは
Vim 自身が受け取ったときにのみ渡されます。'balloonevalterm' が有効になっている
端末の場合です。
サイズと色
terminal-size-color
端末ウィンドウのサイズを制御するにはオプション 'termwinsize' を参照してくださ
い。
(TODO: 端末がウィンドウよりも大きい場合にはスクロールすることを記述する)
端末内のジョブは端末の色を変更できます。デフォルトの前景色及び背景色はVimの
Normal ハイライトグループにより決定されます。
カラー端末を開始する際に、背景に白と黒どちらの系統の色を使用するかは、オプショ
ン 'background' を用いて決定します。
異なる色を使う場合には Terminal ハイライトグループを利用できます。例:
で別グループを設定できます。
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] がない場合、デフォルトの動作はシェルが終了し
たときに端末を閉じます。この動作は ++noclose 引数で変
更できます。
[command] が指定されている場合、デフォルトの動作は端末
を端末ノーマルモードで開いたままにします。
この動作は ++close 引数で変更できます。
Vimのコマンドを後ろに続けることはできず、どんな | も
[command] に含まれてしまいます。
同じ行で Vim コマンドを続けるなら :execute を利用し
てください。
新しいバッファが作られ、 [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 セッションファイルに端末ウィンドウを含
めない。
++shell {command} を直接実行するのではなく、
:!command と同様にシェルを使用する。
E279
{Vim: UnixとMS-Windowsでのみ動作する}
++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() 関
数を使ってください。
ウィンドウを縦分割するには、次のようにします:
端末に関連付けられたバッファが強制的にアンロードもしくは削除された場合には、
job_stop(job, "kill") を呼んだのと同じようにそのジョブが殺されます。
普通にウィンドウを閉じると E947 が返ります。killメソッドが "++kill={how}" か
term_setkill() で設定されている時にウィンドウを閉じると、その方法でジョブを
強制終了または中断します。例:
ジョブが実行され続けるとウィンドウはそのバッファが変更されたかのように振る舞い
ます。CTRL-W :quit でウィンドウを閉じようとしても失敗します。CTRL-W :quit!
を使うとジョブは終了します。ウィンドウのテキストは失われます。バッファは依然存
在しますが、:buffer でウィンドウに割り当てても空のバッファが表示されます。
CTRL-W :close で閉じようとしてもまた失敗します。CTRL-W :close! はウィンド
ウを閉じ、バッファを隠し状態にします。
CTRL-W :hide を使うとジョブを実行したまま、端末ウィンドウを閉じバッファを隠
し状態にできます。:buffer コマンドで現在のウィンドウを端末ウィンドウにするこ
とができます。未保存の変更があった場合にはこれは失敗しますが、通常と同じように
! で強制できます。
terminal-close
端末ウィンドウが閉じられるとき、例えば、シェルが終了し、"++close" 引数が使用さ
れ、これが最後の通常のVimウィンドウである場合、Vimは終了します。これは、通常の
ウィンドウで :quit を使用するようなものです。ヘルプウィンドウとプレビューウィ
ンドウはカウントされません。
バックグラウンドジョブをウィンドウ無しで実行し、終了したらウィンドウに表示する
には、次のようにオプションを指定します:
があることに留意してください。
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の両方が認識するエス
ケープシーケンスのみが端末ウィンドウで利用可能になります。もし、端末で実行中の
ジョブに他のエスケープシーケンスを渡したい場合は、転送を設定する必要がありま
す。例:
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
==============================================================================
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 としても使用できる:
term_dumpload()
term_dumpload({filename} [, {options}])
{filename} の内容を表示する新しいウィンドウを開く。このファイ
ルは term_dumpwrite() で作られたものでなければならない。
失敗したときはバッファ番号もしくは 0 を返す。
terminal-diff も参照。
{options} については term_dumpdiff() を参照。
method としても使用できる:
term_dumpwrite()
term_dumpwrite({buf}, {filename} [, {options}])
ファイル {filename} に、{buf} の端末画面の内容をダンプする。こ
れは term_dumpload() および term_dumpdiff() で使われる
フォーマットを使用する。
端末のジョブがすでに終了していた場合はエラーが発生する: E958
{filename} が既に存在する場合はエラーが発生する: E953
terminal-diff も参照。
{options} は以下のオプショナルな要素を含む辞書である:
"rows" ダンプする行の最大値
"columns" ダンプする列の最大値
method としても使用できる、ベースはファイル名に使用される:
term_getaltscreen({buf}) term_getaltscreen()
{buf} の端末が代替スクリーンを使用している場合 1 を返す。
{buf} の扱いについては term_getsize() と同じ。
method としても使用できる:
term_getansicolors({buf}) term_getansicolors()
端末 {buf} で使用されている ANSI カラーパレットを取得する。
長さ 16 のリストを返し、各要は色を 16 進数の "#rrggbb" フォー
マットで表す文字列である。
term_setansicolors() および g:terminal_ansi_colors も参照。
どちらも使用されていない場合、既定値を返す。
{buf} の扱いについては term_getsize() と同じ。バッファが存在
しない、もしくは端末ウィンドウでない場合は、空リストが返され
る。
method としても使用できる:
{GUI が有効もしくは +termguicolors 機能付きでコンパイルされ
たときのみ有効}
term_getattr({attr}, {what}) term_getattr()
term_scrape() で返された項目 "attr" の値である {attr} につい
て、{what} がオンになっているかを返す。{what} は次のうちどれか
1 つである:
bold
italic
underline
strike
reverse
method としても使用できる:
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 としても使用できる:
term_getjob({buf}) term_getjob()
端末ウィンドウ {buf} に関連付いたジョブを取得する。
{buf} の扱いについては term_getsize() と同じ。
ジョブが存在しないときには v:null を返す。
method としても使用できる:
term_getline({buf}, {row}) term_getline()
端末ウィンドウ {buf} から行のテキストを取得する。
{buf} の扱いについては term_getsize() と同じ。
先頭行の {row} は 1 である。{row} が "." のときはカーソル行が
使われる。{row} が無効のときは空文字列が返される。
各文字の属性を取得するには term_scrape() を使用する。
method としても使用できる:
term_getscrolled({buf}) term_getscrolled()
端末 {buf} の先頭から上方にスクロールされた行の数を返す。これ
は term_getline() および getline() で使われる行番号のオフ
セットとなるので:
{buf} の扱いについては term_getsize() と同じ。
method としても使用できる:
term_getsize({buf}) term_getsize()
端末 {buf} のサイズを取得する。2 つの数値を含むリストを返す:
[rows, cols]。これは端末のサイズであり、端末を含むウィンドウの
サイズではない。
{buf} は端末ウィンドウのバッファ番号でなければならない。現在の
バッファには空文字列を使用する。バッファが存在しない、もしくは
端末ウィンドウでない場合は、空リストが返される。
method としても使用できる:
term_getstatus({buf}) term_getstatus()
端末 {buf} のステータスを取得する。これらの項目をコンマで区切っ
た一覧を文字列で返す:
running ジョブが実行中である
finished ジョブが完了した
normal 端末ノーマルモードである
"running" または "finished" のどちらかは常に存在する。
{buf} は端末ウィンドウのバッファ番号でなければならない。バッ
ファが存在しない、もしくは端末ウィンドウでない場合は、空文字列
が返される。
method としても使用できる:
term_gettitle({buf}) term_gettitle()
端末 {buf} のタイトルを取得する。これは端末内でジョブが設定し
たタイトルである。
{buf} は端末ウィンドウのバッファ番号でなければならない。バッ
ファが存在しない、もしくは端末ウィンドウでない場合は、空文字列
が返される。
method としても使用できる:
term_gettty({buf} [, {input}]) term_gettty()
端末ウィンドウ {buf} に関連付けられた制御端末の名前を取得する。
{buf} の扱いについては term_getsize() と同じ。
{input} が省略されたもしくは 0 のとき、書き込み (stdout) の名
前を返す。{input} が 1 のとき、読み込み (stdin) の名前を返す。
UNIX では両方で同じ名前が返る。
method としても使用できる:
term_list() term_list()
すべての端末ウィンドウのバッファのバッファ番号のリストを返す。
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 としても使用できる:
term_sendkeys({buf}, {keys}) term_sendkeys()
端末 {buf} にキー入力 {keys} を送る。
{buf} の扱いについては term_getsize() と同じ。
{keys} はキーシーケンスとして解釈される。例えば、"\<c-x>" は
文字 CTRL-X を意味する。
method としても使用できる:
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 としても使用できる:
{GUI が有効もしくは +termguicolors 機能付きでコンパイルされ
たときのみ有効}
term_setapi({buf}, {expr}) term_setapi()
端末 {buf} 内で terminal-api 機能に使用する関数名のプリフィッ
クスを設定する。例:
デフォルトは "Tapi_" である。{expr} が空の文字列の場合、{buf}
の terminal-api 機能は使用できない。
method としても使用できる、ベースは {buf} に使用される:
term_setkill({buf}, {how}) term_setkill()
Vim が終了するもしくは何らかの方法で端末ウィンドウを閉じようと
しているとき、端末内のジョブを停止するかどうかを {how} で定義
する。
{how} が空 (既定値) のとき、ジョブは停止されない。終了しようと
すると E947 となる。
それ以外では、{how} はジョブに何のシグナルを送るかを記述する。
値に関しては job_stop() を参照。
シグナルを送ったあと、Vim はジョブが実際に停止したか確認するた
めに 1 秒待つ。
method としても使用できる:
term_setrestore({buf}, {command}) term_setrestore()
この端末内のジョブを復元するためのセッションファイルを書き込む
コマンドを設定する。セッションファイル内に書き込まれる行は以下
の通り:
'shell' を実行するには空の {command} を使用する。
このウィンドウを復元しないためには "NONE" を使用する。
method としても使用できる:
term_setsize({buf}, {rows}, {cols}) term_setsize() E955
端末 {buf} のサイズを設定する。端末を含むウィンドウのサイズが
可能であれば調整される。{rows} もしくは {cols} が、0 もしくは
負である場合、大きさは変わらない。
{buf} は端末ウィンドウのバッファ番号でなければならない。現在の
バッファには空文字列を使用する。バッファが存在しない、もしくは
端末ウィンドウでない場合は、エラーが発生する。
method としても使用できる:
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 としても使用できる:
term_wait({buf} [, {time}]) term_wait()
{buf} で保留となっている更新が処理されるのを待つ。
{buf} の扱いについては term_getsize() と同じ。
{time} は更新が届くのを待つ、ミリ秒単位での長さ。設定されてい
ない場合は 10 ミリ秒が使用される。
method としても使用できる:
==============================================================================
3. 端末通信 terminal-communication
端末内で実行中のジョブと通信するには、いくつかの方法があります:
- term_sendkeys() でテキストやエスケープシーケンスをVimからジョブに送信する。
- JSON APIを使用して、エンコードされたコマンドをジョブからVimに送信する。
- client-server 機構を使う。これは、XサーバーとMS-Windowsのマシンで動作しま
す。
Vim からジョブへ: term_sendkeys()
terminal-to-job
これにより、端末内で実行中のジョブをリモート制御することができます。これは一方
向の機構です。ジョブは Vim に合図することで表示を更新することができます。たと
えば、シェルが端末内で実行されている場合、次の操作を実行できます:
これは、キーを受け取ったときに正しいことをする適切な状態になるようなジョブを必
要とします。上記の例では、シェルはコマンドの入力を待つ必要があります。
この目的のために作成されたジョブでは、JSON APIエスケープシーケンスを別の方向で
使用できます。例:
ジョブから Vimへ: JSON API
terminal-api
ジョブは特殊なエスケープシーケンスを使用してJSONをVimに送ることができます。
JSONは、Vimが理解できるコマンドをエンコードします。そのようなメッセージの例:
本体は常にリストになっており、終わりを見つけやすいです: ]<07>
<Esc>]51;msg<07> シーケンスは "Emacs shell" のためにxtermによって予約されてい
ます。私たちがここでやっていることに似ています。
現在サポートされているコマンド:
call {funcname} {argument}
ユーザー定義関数を {argument} で呼び出します。
関数は2つの引数で呼び出されます: 端末のバッファ番号とデコード
されたJSON引数 {argument} です。
デフォルトでは、関数名は端末API用に意図されていない関数を誤っ
て呼び出すのを避けるため、"Tapi_" で始まる必要があります。これ
は、term_setapi() で変更できます。
ユーザー関数は引数の正常性チェックをする必要があります。
関数は term_sendkeys() を使って返信を送り返すことができます。
JSONでの例:
:echomsg を使い、:messages でそれを見ることができます。
drop {filename} [options]
Vimに :drop コマンドのようにファイルを開かせます。
もし、{filename} が既にウィンドウで開かれていたら、そのウィン
ドウに切り替えます。それ以外の場合は、{filename} を編集するた
めの新しいウィンドウを開きます。
Note ジョブとVimの両方がカレントディレクトリを変更する可能性が
あるので、フルパスを使用することをお勧めします。
[options] は新しくウィンドウを開いた時にだけ使われます。
与える場合、それは辞書でなければなりません。 ++opt と同様に、
これらのエントリは認識されます:
"ff" ファイルフォーマット: "dos" か "mac" か "unix"
"fileformat" 同上。
"enc" 'fileencoding' を上書きします。
"encoding" 同上。
"bin" 'binary' を設定します。
"binary" 同上。
"nobin" 'binary' をリセットします。
"nobinary" 同上。
"bad" 不正な文字のための振る舞いを指定します。
++bad を参照してください。
JSONでの例:
Vimにこのエスケープシーケンスを送信させるトリック:
理論的根拠: コマンドや式を許可しないのはなぜですか？ セキュリティ上の問題が生
じる可能性があるためです。
クライアントサーバー機能を使う
terminal-client-server
これは、 v:servername が空でない場合にのみ機能します。必要に応じて、端末を開く
前に次のように設定することができます:
$VIM_SERVERNAME はサーバー名を渡すために端末内に設定されます。
ジョブでは、次のようなことをおこなうことができます:
==============================================================================
4. リモートテスト terminal-testing
VimのほとんどのテストはVimのなかでスクリプトを実行しています。テスト対象のコー
ドと干渉してしまうような、幾つかのテストではこれは機能しません。これを避けるた
めに端末ウィンドウ内でさらにVimを実行しています。そのテストではキーストローク
を端末に送信し、その結果として端末画面の状態が変わるのを検査します。
関数
term_sendkeys() 端末にキーストロークを送信する (tmap の影響を受けない)
term_wait() 端末画面が更新されるのを待つ
term_scrape() 端末画面の内容を検査する
==============================================================================
5. 画面ダンプの差分 terminal-diff
場合によっては、Vimが正しい文字を画面に表示するかどうかテストするのは面倒かも
しれません。例えば、構文の強調表示。これを簡単にするために、端末の画面ダンプを
取ってそれを予想される画面ダンプと比較することが可能です。
Vimはウィンドウのサイズ、テキスト、色、その他の属性を表示します。 Vimの画面サ
イズ、フォント、その他のプロパティは関係ありません。したがって、この機構はシス
テム間で移植可能です。従来のスクリーンショットでは、フォントサイズやフォント
ファミリーなど、すべての違いが反映されます。
Vimの画面ダンプテストを書く
terminal-dumptest
例については、src/testdir/test_syntax.vim の Test_syntax_c() 関数を参照してく
ださい。主要な部分は:
- テストするファイルを作成します。構文のハイライトをテストするのに便利です。空
のバッファでVimを起動することもできます。
- 特定のサイズの端末でVimを実行します。デフォルトは75桁で20行です。これはダン
プが常にこのサイズであることを確認します。RunVimInTerminal() 関数がこれを処
理します。Vimコマンドの引数を渡します。
- term_sendkeys() を使用して任意のコマンドをVimに送信します。例えば:
します。これは、参照する画面ダンプが src/testdir/dumps/ ディレクトリに存在す
ることを前提としています。 ".dump" なしの名前を渡します。テスト関数の名前と
シーケンス番号を使用してファイルがどのようなテストで使用されているかを知るこ
とができます。
- コマンド送信と状態の確認を繰り返します。
- 最後に StopVimInTerminal() を呼び出してVimを停止します。
初めてこれを行うときにはスクリーンダンプはまだありません。空のファイルを作成し
ます。例:
テストが失敗したら、参照ダンプと失敗したダンプを比較するコマンドを提供します。
例:
カレントディレクトリを src/testdir に設定して、Vimでこのコマンドを使用します。
テストに満足したら、参照の代わりに失敗したダンプを移動します:
画面ダンプを作成する
terminal-screendump
画面ダンプを作成するには、端末でVim (または他のプログラム)を実行し、目的の状態
を表示させます。その後、term_dumpwrite() 関数を使用して画面ダンプファイルを
作成します。例:
この "77" は端末のバッファ番号です。それを見るためには :ls! を使用してくださ
い。
term_dumpload() で画面ダンプを見ることができます:
Vimがまったく同じ画面を表示していることを確認するには、まったく同じ方法でVimを
再度実行し、目的の状態を表示します。次に、別のファイル名を使用して画面ダンプを
再度作成します:
ファイルがまったく同じものであることを主張するには assert_equalfile() を使い
ます:
違いがある場合、v:errors はエラーメッセージを含みます。
画面ダンプを比較する
terminal-diffscreendump
assert_equalfile() は、何が違うのかを簡単に見分けることはできません。問題を
見つけるには、term_dumpdiff() を使用します:
これで3つの部分からなるウィンドウが開きます:
1. 1番目のダンプの内容
2. 1番目と2番目のダンプの差
3. 2番目のダンプの内容
通常、2番目の部分で何が違うかを見ることができます。1番目または2番目ダンプの位
置に関連付けるには 'ruler' を使用します。文字は違いの種類を示します:
X 異なる文字
> 1番目にはカーソルがあるが、2番目にはカーソルがない
< 2番目にはカーソルがあるが、1番目にはカーソルがない
w 文字の幅が異なる (単一 対 2倍幅)
f 文字色が異なる
b 背景色が異なる
a 属性が異なる (ボールド、下線、反転など)
? 両方に文字がない
+ 1番目に文字がない
- 2番目に文字がない
あるいは、 "s" を押して、1番目と2番目のダンプを入れ替えます。これを何度か実行
して、テキストの文脈における相違を見つけ出すことができます。
==============================================================================
6. デバッグ terminal-debug terminal-debugger
Vim のウィンドウでソースコードを表示しながらプログラムを gdb でデバッグするの
に、端末デバッグプラグインが利用できます。これは Vim の中だけで完結するので、
SSH 接続が1つあればリモートで機能します。
+terminal 機能がない場合、プラグインは可能であれば "prompt" バッファタイプを
使用します。実行中のプログラムは、新しく開かれた端末ウィンドウを使用します。詳
細は termdebug-prompt を参照してください。
はじめに
termdebug-starting
以下のコマンドでプラグインを読み込みます:
デバッグを開始するには :Termdebug または :TermdebugCommand に続けてコマン
ド名を入力します。例:
これにより2つのウィンドウが開きます:
gdb のウィンドウ
"gdb vim" を実行した端末ウィンドウ。ここでは直接 gdb とやりと
りできる。バッファ名は "!gdb"
プログラムのウィンドウ
実行したプログラムの端末ウィンドウ。 gdb 内で "run" をしてプロ
グラムの I/O が発生するとこのウィンドウに反映される。その内容
は gdb の制御下にない。バッファ名は "debugged program" である。
現在のウィンドウはソースコードを表示するのに使われます。gdb が一時停止した際
に、可能ならばその場所が表示されます。現在の位置を示すためにハイライトグループ
debugPC を使ってサインが利用されます。
現在のウィンドウの内容が変更されると、現在の gdb の位置を表示するために別のウィ
ンドウが開きます。:Winbar を使ってウィンドウツールバーを追加することができま
す。
実行中のプログラムを操作するにはその端末にフォーカスを合わせます。以降の操作は
普通の端末ウィンドウと同様です。
デバッガの終了は、通常は gdb のウィンドウで "quit" とタイプすると、開いている
2つのウィンドウが閉じられます。
一度にアクティブにできるデバッガは1つだけです。
:TermdebugCommand
デバッグ中のコマンドに特定のコマンドを与える場合は、:TermdebugCommand コマン
ドの後にコマンド名と追加パラメータを使用できます。
:Termdebug と:TermdebugCommand はオプションの "!" をサポートしています。
gdbウィンドウで一時停止せずにコマンドをすぐに開始します (そしてカーソルはデバッ
グされたウィンドウに表示されます) 例えば:
すでに実行中の実行可能ファイルにgdbをアタッチするか、コアファイルを使用するに
は、追加の引数を渡します。例:
引数が指定されていない場合、gdbウィンドウが表示されます。このウィンドウでは、
例えばgdbの file コマンドを使って、どのコマンドを実行するか指定する必要があ
ります。
セッション例
termdebug-example
Vimの "src" ディレクトリを起動して、Vimをビルドします:
ことを意味します。
Vimを起動します:
termdebug プラグインを読み込んで、Vimのデバッグを開始します:
source - 開始直後はボタン付きウィンドウツールバーがあります
gdb - ここに gdb コマンドを入力できます
program - 実行されたプログラムはこのウィンドウを使用します
CTRL-W CTRL-W またはマウスを使用して、ウィンドウ間でフォーカスを移動できます。
gdbウィンドウにフォーカスを当てて、次のように入力します:
す:
ルが表示されます。ブレークポイントが設定されている目印欄に赤い "1 " のマーカー
が表示されます。デバッガが停止した行が強調表示されます。今すぐプログラムを進め
ることができます。マウスを使いましょう: ウィンドウツールバーの "Next" ボタンを
クリックしてください。デバッガがソースコードの行を実行すると、強調表示されま
す。
forループが強調表示されるまで、"Next" を数回クリックします。カーソルを
"eap->arg" の最後に置き、ツールバーの "Eval" をクリックします。これが表示され
ます:
"eap->arg": 0x555555e68855 "gui"
こうすることで、ローカル変数の値を調べることができます。また、gdbウィンドウに
フォーカスを当てて、"print" コマンドを使用することもできます。例:
に置かれたときにVimはバルーンを表示します。
次に、sourceウィンドウに戻り、forループの後の最初の行にカーソルを置いて、次の
ように入力します:
をクリックして、コードをブレークポイントまで実行させます。
より高度なコマンドをgdbウィンドウに入力することができます。例えば、次のように
入力します:
ます)。do_ecmd() にある "curbuf" の値が変更されるまで、実行が継続されます。こ
のウォッチポイントを再度削除するには、gdbウィンドウで次のように入力します:
gdbウィンドウに次のように入力すると、スタックが表示されます:
コードをステップ実行する
termdebug-stepping
gdb ウィンドウにフォーカスを移しコマンドを入力します。一般的なものは以下:
- CTRL-C プログラムを中断する
- next 現在の行を実行し、次の行(の手前)で停止する
- step 現在の行を実行し、次の文(の手前)で停止する。関数の内側に入る
- until 現在の行を通過する、または指定位置を通過する、または現在のス
タックフレームに戻るまで実行する
- finish 現在の関数を抜けるまで実行する
- where スタックを表示する
- frame N N 番目のスタックフレームに移動する
- continue 実行を再開する
:Run :Arguments
ソースコードを表示するウィンドウで、これらのコマンドをgdbの制御に使用できます:
:Run [args] [args] または以前の引数でプログラムを実行する
:Arguments {args} 次の :Run のために引数を設定する
:Break カーソル位置にブレークポイントを設定する。
:Break {position}
指定位置にブレークポイントを設定する。
:Clear カーソル位置のブレークポイントを削除する
:Step gdb の "step" コマンドを実行する
:Over gdb の "next" コマンドを実行する
(:Next だと Vim のコマンドとかぶるので)
:Until gdb の "until" コマンドを実行する
:Finish gdb の "finish" コマンドを実行する
:Continue gdb の "continue" コマンドを実行する
:Stop プログラムを中断する
'mouse' が設定されている場合、プラグインはこれらのエントリを持つウィンドウツー
ルバーを追加します:
Step :Step
Next :Over
Finish :Finish
Cont :Continue
Stop :Stop
Eval :Evaluate
この方法で、マウスを使用して最も一般的なコマンドを実行できます。マウスのクリッ
クを有効にするには、'mouse' オプションを設定する必要があります。
:Winbar
開いている他のウィンドウにウィンドウツールバーを追加することができます:
gdbがソース行で停止し、現在ソースコードを表示しているウィンドウがない場合、ソー
スコード用の新しいウィンドウが作成されます。これは、ソースコードウィンドウの
バッファが変更され、破棄できない場合でも発生します。
gdbは各ブレークポイントに番号を与えます。Vim内では、赤い背景で、目印欄に表示さ
れます。次のgdbコマンドを使用できます。
- info break ブレークポイントの一覧
- delete N ブレークポイント N を削除
また、カーソルがブレークポイントの行にある場合は :Clear コマンドを使うことが
できます。または、右クリックのメニュー項目 "Clear breakpoint" を使用することも
できます。
変数を検査する
termdebug-variables :Evaluate
:Evaluate カーソルの下の式を評価する
K 上に同じ (無効にする場合は termdebug_map_K を参照)
:Evaluate {expr} {expr} を評価する
:'<,'>Evaluate ビジュアル選択したテキストを評価する
これは gdb ウィンドウで "print" コマンドを使ったのに相当します。
:Evaluate は :Ev に短縮できます。
その他のコマンド
termdebug-commands
:Gdb gdb ウィンドウに移動する
:Program デバッグ中のプログラムウィンドウに移動する
:Source ソースコードウィンドウにジャンプする、ウィンドウがなければ作成
する
:Asm 逆アセンブルウィンドウにジャンプする、ウィンドウがなければ作成す
る
イベント
termdebug-events
4 つのautocmdが使えます:
TermdebugStartPre
TermdebugStartPre デバッグ開始前。
すでにデバッガが開始しているもしくはデバッガコ
マンドが実行できない場合は発行されない。
TermdebugStartPost
TermdebugStartPost デバッグの初期化後。
:Termdebug あるいは :TermdebugCommand 経由
で ! 修飾子付きで実行された場合は gdb 内で提供
コマンドが動き出す前に発行される。
TermdebugStopPre
TermdebugStopPre デバッグの終了前で、gdb が終了する時、多くの場
合は gdb window で "quit" コマンドを発行した
後。
TermdebugStopPost
TermdebugStopPost デバッグの終了後、gdb 関連ウィンドウが閉じ、
デバッグのバッファが消去されデバッグ前の状態が
復帰した時。
プロンプトモード
termdebug-prompt
+terminal 機能がサポートされていない場合や MS-Windows上の場合、gdbは
'buftype' が "prompt" に設定されたバッファで動作します。これは少し違った働きを
します:
- コマンドを入力している間、gdbウィンドウは挿入モードになります。<Esc> でノー
マルモードにして、バッファ間を移動したり、コピー/ペーストなどをおこなうこと
ができます。a や i のような挿入モードを開始するコマンドでgdbコマンドの編
集に戻ります。
- デバッグ中のプログラムは別のウィンドウで実行されます。MS-Windowsでは、これは
新しいコンソールウィンドウです。Unixでは、+terminal 機能が利用可能な場合、
端末ウィンドウが開いてデバッグされたプログラムを実行します。
termdebug_use_prompt
プロンプトモードは、+terminal 機能が有効な場合でも使用できます:
termdebug_map_K
K は通常 :Evaluate にマッピングされています。これが不要な場合は:
termdebug_disasm_window
Asm ウィンドウをデフォルトで表示させたい場合、このフラグに1を設定します。
"disasm_window_height" エントリを使用してウィンドウの高さを設定できます:
通信
termdebug-communication
Vim が gdb と通信するために他に隠されたバッファを利用します。バッファ名は "gdb
communicate" です。このバッファは消さないでください。消してしまうとデバッガが
動作しなくなってしまうでしょう。
gdb は奇妙な動作をしていますが、プラグインはその問題を回避するために最善を尽く
しています。
例えば、gdbウィンドウで "continue" と入力した後に、CTRL-C を使用して実行中のプ
ログラムを中断することができます。しかし、MIコマンド "-exec-continue" を使用し
た後、CTRL-C を押しても中断しません。したがって、通信チャネルを使用する代わり
に、:Continue コマンドに "continue" が使用されていることがわかります。
カスタマイズ
termdebug-customizing g:termdebug_config
以前はいくつかのグローバル変数を設定に使用していました。これらは非推奨になり、
辞書 g:termdebug_config の使用が推奨されます。g:termdebug_config が存在する時
は他のグローバル変数は使用されません。
GDBコマンド
g:termdebugger
gdb コマンド以外のデバッガを使うには、:Termdebug を実行する前に
g:termdebug_config の "debugger" エントリか "g:termdebugger" 変数を変更してく
ださい:
コマンドに引数が必要な場合はリストを使用してください:
gdb がデバッガで適切に動作するように、いくつかの引数が追加されます。それらを変
更したい場合は、引数リストをフィルタリングする関数を追加します:
引数を追加したくないが、"pty" を設定する必要がある場合は、関数を使用して必要な
引数を追加します:
す。
gdb-version
gdb と完全互換のあるデバッガのみが使えます。Vim は gdb の操作に GDB/MI インター
フェイスを利用しています。 "new-ui" コマンドには、gdbバージョン7.12以降が必要
です。このエラーが発生した場合:
カラー
hl-debugPC hl-debugBreakpoint
サインの色は以下のハイライトグループで調整できます:
- debugPC 現在の位置
- debugBreakpoint ブレークポイント
'background' オプションが "light" の時のデフォルトは以下のとおりです:
hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
hi debugBreakpoint term=reverse ctermbg=red guibg=red
'background' オプションが "dark" の時は以下のとおりです:
hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
hi debugBreakpoint term=reverse ctermbg=red guibg=red
ショートカット
termdebug_shortcuts
TermDebugSendCommand() 関数を使用して、任意のウィンドウで動作する gdb を制御す
る独自のショートカット(マッピング)を定義できます。例:
ポップアップメニュー
termdebug_popup
デフォルトでTermdebugプラグインは 'mousemodel' を "popup_setpos" に設定し、こ
れらのエントリをポップアップメニューに追加します:
Set breakpoint :Break
Clear breakpoint :Clear
Evaluate :Evaluate
あなたがこれを望まないならば、それを無効にしてください:
Vimのウィンドウ幅
termdebug_wide
デバッグを開始した際に Vim のウィンドウ幅を変更し、垂直分割を利用するには次の
ように設定します:
これは :Termdebug を実行した際に 'columns' を 163 に設定します。元の値はデ
バッガが終了する際に復元されます。
幅の値が設定されていて、'columns' がすでに幅の値より大きい場合、'columns' を変
更せずに垂直分割が使用されます。
幅の値を1に設定することで 'columns' の変更なしに垂直分割が使えます。これは端末
がVimによってサイズ変更できない場合に便利です。
vim:tw=78:ts=8:noet:ft=help:norl:
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-commands
イベント termdebug-events
プロンプトモード termdebug-prompt
通信 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
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 この隠れている端末のオプションは端末が隠れている間は値が設定されません。\ | setlocal bufhidden=hide colorcolumn=123
\ | endif
TerminalOpen イベントもあります。これは隠れた端末で発生するかもしれず、その
場合は現在のウィンドウとバッファはこの新しい端末ではないことに注意してくださ
い。
端末バッファに設定するなら、<abuf> を使う必要があります。例:
au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(),
\ '&termwinscroll', 1000)
ウィンドウローカルオプションは、端末ウィンドウが生成されるまで設定が遅延する必\ '&termwinscroll', 1000)
要があります (これは隠れた端末だけで働きます):
au TerminalOpen * exe printf(
\ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d',
\ expand('<abuf>')->str2nr(), 123)
隠れていない端末では TerminalWinOpen を使います。\ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d',
\ expand('<abuf>')->str2nr(), 123)
マウスイベント (クリックやドラッグ) は端末に渡されます。マウス移動イベントは
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] がない場合、デフォルトの動作はシェルが終了し
たときに端末を閉じます。この動作は ++noclose 引数で変
更できます。
[command] が指定されている場合、デフォルトの動作は端末
を端末ノーマルモードで開いたままにします。
この動作は ++close 引数で変更できます。
Vimのコマンドを後ろに続けることはできず、どんな | も
[command] に含まれてしまいます。
同じ行で Vim コマンドを続けるなら :execute を利用し
てください。
新しいバッファが作られ、 [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 セッションファイルに端末ウィンドウを含
めない。
++shell {command} を直接実行するのではなく、
:!command と同様にシェルを使用する。
E279
{Vim: UnixとMS-Windowsでのみ動作する}
++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!
を使うとジョブは終了します。ウィンドウのテキストは失われます。バッファは依然存
在しますが、:buffer でウィンドウに割り当てても空のバッファが表示されます。
CTRL-W :close で閉じようとしてもまた失敗します。CTRL-W :close! はウィンド
ウを閉じ、バッファを隠し状態にします。
CTRL-W :hide を使うとジョブを実行したまま、端末ウィンドウを閉じバッファを隠
し状態にできます。:buffer コマンドで現在のウィンドウを端末ウィンドウにするこ
とができます。未保存の変更があった場合にはこれは失敗しますが、通常と同じように
! で強制できます。
terminal-close
端末ウィンドウが閉じられるとき、例えば、シェルが終了し、"++close" 引数が使用さ
れ、これが最後の通常のVimウィンドウである場合、Vimは終了します。これは、通常の
ウィンドウで :quit を使用するようなものです。ヘルプウィンドウとプレビューウィ
ンドウはカウントされません。
バックグラウンドジョブをウィンドウ無しで実行し、終了したらウィンドウに表示する
には、次のようにオプションを指定します:
:term ++hidden ++open make
ウィンドウが予期せぬタイミングで開かれ、あなたが行っている操作に割り込む可能性があることに留意してください。
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
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
==============================================================================
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)
term_dumpload()
term_dumpload({filename} [, {options}])
{filename} の内容を表示する新しいウィンドウを開く。このファイ
ルは term_dumpwrite() で作られたものでなければならない。
失敗したときはバッファ番号もしくは 0 を返す。
terminal-diff も参照。
{options} については term_dumpdiff() を参照。
method としても使用できる:
GetFilename()->term_dumpload()
term_dumpwrite()
term_dumpwrite({buf}, {filename} [, {options}])
ファイル {filename} に、{buf} の端末画面の内容をダンプする。こ
れは term_dumpload() および term_dumpdiff() で使われる
フォーマットを使用する。
端末のジョブがすでに終了していた場合はエラーが発生する: E958
{filename} が既に存在する場合はエラーが発生する: E953
terminal-diff も参照。
{options} は以下のオプショナルな要素を含む辞書である:
"rows" ダンプする行の最大値
"columns" ダンプする列の最大値
method としても使用できる、ベースはファイル名に使用される:
GetFilename()->term_dumpwrite(bufnr)
term_getaltscreen({buf}) term_getaltscreen()
{buf} の端末が代替スクリーンを使用している場合 1 を返す。
{buf} の扱いについては term_getsize() と同じ。
method としても使用できる:
GetBufnr()->term_getaltscreen()
term_getansicolors({buf}) term_getansicolors()
端末 {buf} で使用されている ANSI カラーパレットを取得する。
長さ 16 のリストを返し、各要は色を 16 進数の "#rrggbb" フォー
マットで表す文字列である。
term_setansicolors() および g:terminal_ansi_colors も参照。
どちらも使用されていない場合、既定値を返す。
{buf} の扱いについては term_getsize() と同じ。バッファが存在
しない、もしくは端末ウィンドウでない場合は、空リストが返され
る。
method としても使用できる:
GetBufnr()->term_getansicolors()
{GUI が有効もしくは +termguicolors 機能付きでコンパイルされ
たときのみ有効}
term_getattr({attr}, {what}) term_getattr()
term_scrape() で返された項目 "attr" の値である {attr} につい
て、{what} がオンになっているかを返す。{what} は次のうちどれか
1 つである:
bold
italic
underline
strike
reverse
method としても使用できる:
GetAttr()->term_getattr()
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()
term_getjob({buf}) term_getjob()
端末ウィンドウ {buf} に関連付いたジョブを取得する。
{buf} の扱いについては term_getsize() と同じ。
ジョブが存在しないときには v:null を返す。
method としても使用できる:
GetBufnr()->term_getjob()
term_getline({buf}, {row}) term_getline()
端末ウィンドウ {buf} から行のテキストを取得する。
{buf} の扱いについては term_getsize() と同じ。
先頭行の {row} は 1 である。{row} が "." のときはカーソル行が
使われる。{row} が無効のときは空文字列が返される。
各文字の属性を取得するには term_scrape() を使用する。
method としても使用できる:
GetBufnr()->term_getline(row)
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()
term_getsize({buf}) term_getsize()
端末 {buf} のサイズを取得する。2 つの数値を含むリストを返す:
[rows, cols]。これは端末のサイズであり、端末を含むウィンドウの
サイズではない。
{buf} は端末ウィンドウのバッファ番号でなければならない。現在の
バッファには空文字列を使用する。バッファが存在しない、もしくは
端末ウィンドウでない場合は、空リストが返される。
method としても使用できる:
GetBufnr()->term_getsize()
term_getstatus({buf}) term_getstatus()
端末 {buf} のステータスを取得する。これらの項目をコンマで区切っ
た一覧を文字列で返す:
running ジョブが実行中である
finished ジョブが完了した
normal 端末ノーマルモードである
"running" または "finished" のどちらかは常に存在する。
{buf} は端末ウィンドウのバッファ番号でなければならない。バッ
ファが存在しない、もしくは端末ウィンドウでない場合は、空文字列
が返される。
method としても使用できる:
GetBufnr()->term_getstatus()
term_gettitle({buf}) term_gettitle()
端末 {buf} のタイトルを取得する。これは端末内でジョブが設定し
たタイトルである。
{buf} は端末ウィンドウのバッファ番号でなければならない。バッ
ファが存在しない、もしくは端末ウィンドウでない場合は、空文字列
が返される。
method としても使用できる:
GetBufnr()->term_gettitle()
term_gettty({buf} [, {input}]) term_gettty()
端末ウィンドウ {buf} に関連付けられた制御端末の名前を取得する。
{buf} の扱いについては term_getsize() と同じ。
{input} が省略されたもしくは 0 のとき、書き込み (stdout) の名
前を返す。{input} が 1 のとき、読み込み (stdin) の名前を返す。
UNIX では両方で同じ名前が返る。
method としても使用できる:
GetBufnr()->term_gettty()
term_list() term_list()
すべての端末ウィンドウのバッファのバッファ番号のリストを返す。
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)
term_sendkeys({buf}, {keys}) term_sendkeys()
端末 {buf} にキー入力 {keys} を送る。
{buf} の扱いについては term_getsize() と同じ。
{keys} はキーシーケンスとして解釈される。例えば、"\<c-x>" は
文字 CTRL-X を意味する。
method としても使用できる:
GetBufnr()->term_sendkeys(keys)
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)
{GUI が有効もしくは +termguicolors 機能付きでコンパイルされ
たときのみ有効}
term_setapi({buf}, {expr}) term_setapi()
端末 {buf} 内で terminal-api 機能に使用する関数名のプリフィッ
クスを設定する。例:
:call term_setapi(buf, "Myapi_")
:call term_setapi(buf, "")
:call term_setapi(buf, "")
デフォルトは "Tapi_" である。{expr} が空の文字列の場合、{buf}
の terminal-api 機能は使用できない。
method としても使用できる、ベースは {buf} に使用される:
GetBufnr()->term_setapi({expr})
term_setkill({buf}, {how}) term_setkill()
Vim が終了するもしくは何らかの方法で端末ウィンドウを閉じようと
しているとき、端末内のジョブを停止するかどうかを {how} で定義
する。
{how} が空 (既定値) のとき、ジョブは停止されない。終了しようと
すると E947 となる。
それ以外では、{how} はジョブに何のシグナルを送るかを記述する。
値に関しては job_stop() を参照。
シグナルを送ったあと、Vim はジョブが実際に停止したか確認するた
めに 1 秒待つ。
method としても使用できる:
GetBufnr()->term_setkill(how)
term_setrestore({buf}, {command}) term_setrestore()
この端末内のジョブを復元するためのセッションファイルを書き込む
コマンドを設定する。セッションファイル内に書き込まれる行は以下
の通り:
terminal ++curwin ++cols=%d ++rows=%d {command}
コマンドを適切にエスケープするよう気を付けること。'shell' を実行するには空の {command} を使用する。
このウィンドウを復元しないためには "NONE" を使用する。
method としても使用できる:
GetBufnr()->term_setrestore(command)
term_setsize({buf}, {rows}, {cols}) term_setsize() E955
端末 {buf} のサイズを設定する。端末を含むウィンドウのサイズが
可能であれば調整される。{rows} もしくは {cols} が、0 もしくは
負である場合、大きさは変わらない。
{buf} は端末ウィンドウのバッファ番号でなければならない。現在の
バッファには空文字列を使用する。バッファが存在しない、もしくは
端末ウィンドウでない場合は、エラーが発生する。
method としても使用できる:
GetBufnr()->term_setsize(rows, cols)
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()
term_wait({buf} [, {time}]) term_wait()
{buf} で保留となっている更新が処理されるのを待つ。
{buf} の扱いについては term_getsize() と同じ。
{time} は更新が届くのを待つ、ミリ秒単位での長さ。設定されてい
ない場合は 10 ミリ秒が使用される。
method としても使用できる:
GetBufnr()->term_wait()
==============================================================================
3. 端末通信 terminal-communication
端末内で実行中のジョブと通信するには、いくつかの方法があります:
- term_sendkeys() でテキストやエスケープシーケンスをVimからジョブに送信する。
- JSON APIを使用して、エンコードされたコマンドをジョブからVimに送信する。
- client-server 機構を使う。これは、XサーバーとMS-Windowsのマシンで動作しま
す。
Vim からジョブへ: term_sendkeys()
terminal-to-job
これにより、端末内で実行中のジョブをリモート制御することができます。これは一方
向の機構です。ジョブは Vim に合図することで表示を更新することができます。たと
えば、シェルが端末内で実行されている場合、次の操作を実行できます:
call term_sendkeys(buf, "ls *.java\<CR>")
これは、キーを受け取ったときに正しいことをする適切な状態になるようなジョブを必
要とします。上記の例では、シェルはコマンドの入力を待つ必要があります。
この目的のために作成されたジョブでは、JSON APIエスケープシーケンスを別の方向で
使用できます。例:
call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
ジョブから Vimへ: JSON API
terminal-api
ジョブは特殊なエスケープシーケンスを使用してJSONをVimに送ることができます。
JSONは、Vimが理解できるコマンドをエンコードします。そのようなメッセージの例:
<Esc>]51;["drop", "README.md"]<07>
本体は常にリストになっており、終わりを見つけやすいです: ]<07>
<Esc>]51;msg<07> シーケンスは "Emacs shell" のためにxtermによって予約されてい
ます。私たちがここでやっていることに似ています。
現在サポートされているコマンド:
call {funcname} {argument}
ユーザー定義関数を {argument} で呼び出します。
関数は2つの引数で呼び出されます: 端末のバッファ番号とデコード
されたJSON引数 {argument} です。
デフォルトでは、関数名は端末API用に意図されていない関数を誤っ
て呼び出すのを避けるため、"Tapi_" で始まる必要があります。これ
は、term_setapi() で変更できます。
ユーザー関数は引数の正常性チェックをする必要があります。
関数は term_sendkeys() を使って返信を送り返すことができます。
JSONでの例:
["call", "Tapi_Impression", ["play", 14]]
次のように定義された関数を呼び出します: function Tapi_Impression(bufnum, arglist)
if len(a:arglist) == 2
echomsg "impression " .. a:arglist[0]
echomsg "count " .. a:arglist[1]
endif
endfunc
:echo からの出力は、再描画によって消去されるかもしれません。if len(a:arglist) == 2
echomsg "impression " .. a:arglist[0]
echomsg "count " .. a:arglist[1]
endif
endfunc
:echomsg を使い、:messages でそれを見ることができます。
drop {filename} [options]
Vimに :drop コマンドのようにファイルを開かせます。
もし、{filename} が既にウィンドウで開かれていたら、そのウィン
ドウに切り替えます。それ以外の場合は、{filename} を編集するた
めの新しいウィンドウを開きます。
Note ジョブとVimの両方がカレントディレクトリを変更する可能性が
あるので、フルパスを使用することをお勧めします。
[options] は新しくウィンドウを開いた時にだけ使われます。
与える場合、それは辞書でなければなりません。 ++opt と同様に、
これらのエントリは認識されます:
"ff" ファイルフォーマット: "dos" か "mac" か "unix"
"fileformat" 同上。
"enc" 'fileencoding' を上書きします。
"encoding" 同上。
"bin" 'binary' を設定します。
"binary" 同上。
"nobin" 'binary' をリセットします。
"nobinary" 同上。
"bad" 不正な文字のための振る舞いを指定します。
++bad を参照してください。
JSONでの例:
["drop", "path/file.txt", {"ff": "dos"}]
Vimにこのエスケープシーケンスを送信させるトリック:
exe "set t_ts=\<Esc>]51; t_fs=\x07"
let &titlestring = '["call","Tapi_TryThis",["hello",123]]'
redraw
set t_ts& t_fs&
let &titlestring = '["call","Tapi_TryThis",["hello",123]]'
redraw
set t_ts& t_fs&
理論的根拠: コマンドや式を許可しないのはなぜですか？ セキュリティ上の問題が生
じる可能性があるためです。
クライアントサーバー機能を使う
terminal-client-server
これは、 v:servername が空でない場合にのみ機能します。必要に応じて、端末を開く
前に次のように設定することができます:
call remote_startserver('vim-server')
$VIM_SERVERNAME はサーバー名を渡すために端末内に設定されます。
ジョブでは、次のようなことをおこなうことができます:
vim --servername $VIM_SERVERNAME --remote +123 some_file.c
これによりファイル "some_file.c" が開き、123行目にカーソルが置かれます。==============================================================================
4. リモートテスト terminal-testing
VimのほとんどのテストはVimのなかでスクリプトを実行しています。テスト対象のコー
ドと干渉してしまうような、幾つかのテストではこれは機能しません。これを避けるた
めに端末ウィンドウ内でさらにVimを実行しています。そのテストではキーストローク
を端末に送信し、その結果として端末画面の状態が変わるのを検査します。
関数
term_sendkeys() 端末にキーストロークを送信する (tmap の影響を受けない)
term_wait() 端末画面が更新されるのを待つ
term_scrape() 端末画面の内容を検査する
==============================================================================
5. 画面ダンプの差分 terminal-diff
場合によっては、Vimが正しい文字を画面に表示するかどうかテストするのは面倒かも
しれません。例えば、構文の強調表示。これを簡単にするために、端末の画面ダンプを
取ってそれを予想される画面ダンプと比較することが可能です。
Vimはウィンドウのサイズ、テキスト、色、その他の属性を表示します。 Vimの画面サ
イズ、フォント、その他のプロパティは関係ありません。したがって、この機構はシス
テム間で移植可能です。従来のスクリーンショットでは、フォントサイズやフォント
ファミリーなど、すべての違いが反映されます。
Vimの画面ダンプテストを書く
terminal-dumptest
例については、src/testdir/test_syntax.vim の Test_syntax_c() 関数を参照してく
ださい。主要な部分は:
- テストするファイルを作成します。構文のハイライトをテストするのに便利です。空
のバッファでVimを起動することもできます。
- 特定のサイズの端末でVimを実行します。デフォルトは75桁で20行です。これはダン
プが常にこのサイズであることを確認します。RunVimInTerminal() 関数がこれを処
理します。Vimコマンドの引数を渡します。
- term_sendkeys() を使用して任意のコマンドをVimに送信します。例えば:
call term_sendkeys(buf, ":echo &lines &columns\<CR>")
- VerifyScreenDump() を使用して、画面が期待どおりの状態になっていることを確認します。これは、参照する画面ダンプが src/testdir/dumps/ ディレクトリに存在す
ることを前提としています。 ".dump" なしの名前を渡します。テスト関数の名前と
シーケンス番号を使用してファイルがどのようなテストで使用されているかを知るこ
とができます。
- コマンド送信と状態の確認を繰り返します。
- 最後に StopVimInTerminal() を呼び出してVimを停止します。
初めてこれを行うときにはスクリーンダンプはまだありません。空のファイルを作成し
ます。例:
touch src/testdir/dumps/Test_function_name_01.dump
テストが失敗したら、参照ダンプと失敗したダンプを比較するコマンドを提供します。
例:
call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump")
カレントディレクトリを src/testdir に設定して、Vimでこのコマンドを使用します。
テストに満足したら、参照の代わりに失敗したダンプを移動します:
:!mv failed/Test_func.dump dumps/Test_func.dump
画面ダンプを作成する
terminal-screendump
画面ダンプを作成するには、端末でVim (または他のプログラム)を実行し、目的の状態
を表示させます。その後、term_dumpwrite() 関数を使用して画面ダンプファイルを
作成します。例:
:call term_dumpwrite(77, "mysyntax.dump")
この "77" は端末のバッファ番号です。それを見るためには :ls! を使用してくださ
い。
term_dumpload() で画面ダンプを見ることができます:
:call term_dumpload("mysyntax.dump")
Vimがまったく同じ画面を表示していることを確認するには、まったく同じ方法でVimを
再度実行し、目的の状態を表示します。次に、別のファイル名を使用して画面ダンプを
再度作成します:
:call term_dumpwrite(88, "test.dump")
ファイルがまったく同じものであることを主張するには assert_equalfile() を使い
ます:
call assert_equalfile("mysyntax.dump", "test.dump")
違いがある場合、v:errors はエラーメッセージを含みます。
画面ダンプを比較する
terminal-diffscreendump
assert_equalfile() は、何が違うのかを簡単に見分けることはできません。問題を
見つけるには、term_dumpdiff() を使用します:
call term_dumpdiff("mysyntax.dump", "test.dump")
これで3つの部分からなるウィンドウが開きます:
1. 1番目のダンプの内容
2. 1番目と2番目のダンプの差
3. 2番目のダンプの内容
通常、2番目の部分で何が違うかを見ることができます。1番目または2番目ダンプの位
置に関連付けるには 'ruler' を使用します。文字は違いの種類を示します:
X 異なる文字
> 1番目にはカーソルがあるが、2番目にはカーソルがない
< 2番目にはカーソルがあるが、1番目にはカーソルがない
w 文字の幅が異なる (単一 対 2倍幅)
f 文字色が異なる
b 背景色が異なる
a 属性が異なる (ボールド、下線、反転など)
? 両方に文字がない
+ 1番目に文字がない
- 2番目に文字がない
あるいは、 "s" を押して、1番目と2番目のダンプを入れ替えます。これを何度か実行
して、テキストの文脈における相違を見つけ出すことができます。
==============================================================================
6. デバッグ terminal-debug terminal-debugger
Vim のウィンドウでソースコードを表示しながらプログラムを gdb でデバッグするの
に、端末デバッグプラグインが利用できます。これは Vim の中だけで完結するので、
SSH 接続が1つあればリモートで機能します。
+terminal 機能がない場合、プラグインは可能であれば "prompt" バッファタイプを
使用します。実行中のプログラムは、新しく開かれた端末ウィンドウを使用します。詳
細は termdebug-prompt を参照してください。
はじめに
termdebug-starting
以下のコマンドでプラグインを読み込みます:
packadd termdebug
:Termdebugデバッグを開始するには :Termdebug または :TermdebugCommand に続けてコマン
ド名を入力します。例:
:Termdebug vim
これにより2つのウィンドウが開きます:
gdb のウィンドウ
"gdb vim" を実行した端末ウィンドウ。ここでは直接 gdb とやりと
りできる。バッファ名は "!gdb"
プログラムのウィンドウ
実行したプログラムの端末ウィンドウ。 gdb 内で "run" をしてプロ
グラムの I/O が発生するとこのウィンドウに反映される。その内容
は gdb の制御下にない。バッファ名は "debugged program" である。
現在のウィンドウはソースコードを表示するのに使われます。gdb が一時停止した際
に、可能ならばその場所が表示されます。現在の位置を示すためにハイライトグループ
debugPC を使ってサインが利用されます。
現在のウィンドウの内容が変更されると、現在の gdb の位置を表示するために別のウィ
ンドウが開きます。:Winbar を使ってウィンドウツールバーを追加することができま
す。
実行中のプログラムを操作するにはその端末にフォーカスを合わせます。以降の操作は
普通の端末ウィンドウと同様です。
デバッガの終了は、通常は gdb のウィンドウで "quit" とタイプすると、開いている
2つのウィンドウが閉じられます。
一度にアクティブにできるデバッガは1つだけです。
:TermdebugCommand
デバッグ中のコマンドに特定のコマンドを与える場合は、:TermdebugCommand コマン
ドの後にコマンド名と追加パラメータを使用できます。
:TermdebugCommand vim --clean -c ':set nu'
:Termdebug と:TermdebugCommand はオプションの "!" をサポートしています。
gdbウィンドウで一時停止せずにコマンドをすぐに開始します (そしてカーソルはデバッ
グされたウィンドウに表示されます) 例えば:
:TermdebugCommand! vim --clean
すでに実行中の実行可能ファイルにgdbをアタッチするか、コアファイルを使用するに
は、追加の引数を渡します。例:
:Termdebug vim core
:Termdebug vim 98343
:Termdebug vim 98343
引数が指定されていない場合、gdbウィンドウが表示されます。このウィンドウでは、
例えばgdbの file コマンドを使って、どのコマンドを実行するか指定する必要があ
ります。
セッション例
termdebug-example
Vimの "src" ディレクトリを起動して、Vimをビルドします:
% make
デバッグシンボルが存在することを確認します。通常は、$CFLAGS に "-g" が含まれることを意味します。
Vimを起動します:
% ./vim
termdebug プラグインを読み込んで、Vimのデバッグを開始します:
:packadd termdebug
:Termdebug vim
これで、3つのウィンドウが表示されます::Termdebug vim
source - 開始直後はボタン付きウィンドウツールバーがあります
gdb - ここに gdb コマンドを入力できます
program - 実行されたプログラムはこのウィンドウを使用します
CTRL-W CTRL-W またはマウスを使用して、ウィンドウ間でフォーカスを移動できます。
gdbウィンドウにフォーカスを当てて、次のように入力します:
break ex_help
run
Vim は programウィンドウで実行を開始します。そこにフォーカスを置いて入力しまrun
す:
:help gui
Gdbはex_helpブレークポイントまで実行します。sourceウィンドウにex_cmds.cファイルが表示されます。ブレークポイントが設定されている目印欄に赤い "1 " のマーカー
が表示されます。デバッガが停止した行が強調表示されます。今すぐプログラムを進め
ることができます。マウスを使いましょう: ウィンドウツールバーの "Next" ボタンを
クリックしてください。デバッガがソースコードの行を実行すると、強調表示されま
す。
forループが強調表示されるまで、"Next" を数回クリックします。カーソルを
"eap->arg" の最後に置き、ツールバーの "Eval" をクリックします。これが表示され
ます:
"eap->arg": 0x555555e68855 "gui"
こうすることで、ローカル変数の値を調べることができます。また、gdbウィンドウに
フォーカスを当てて、"print" コマンドを使用することもできます。例:
print *eap
マウスポインタの動きがうまくいっていれば、マウスがgdbで評価できるテキストの上に置かれたときにVimはバルーンを表示します。
次に、sourceウィンドウに戻り、forループの後の最初の行にカーソルを置いて、次の
ように入力します:
:Break
新しいブレークポイントを示す ">>" マーカーが表示されます。ツールバーの "Cont"をクリックして、コードをブレークポイントまで実行させます。
より高度なコマンドをgdbウィンドウに入力することができます。例えば、次のように
入力します:
watch curbuf
ツールバーの "Cont" をクリックします (または、gdbウィンドウで "cont" と入力します)。do_ecmd() にある "curbuf" の値が変更されるまで、実行が継続されます。こ
のウォッチポイントを再度削除するには、gdbウィンドウで次のように入力します:
delete 3
gdbウィンドウに次のように入力すると、スタックが表示されます:
where
スタックフレームを移動します。例えば: frame 3
sourceウィンドウには、より深いレベルに呼び出された時点のコードが表示されます。コードをステップ実行する
termdebug-stepping
gdb ウィンドウにフォーカスを移しコマンドを入力します。一般的なものは以下:
- CTRL-C プログラムを中断する
- next 現在の行を実行し、次の行(の手前)で停止する
- step 現在の行を実行し、次の文(の手前)で停止する。関数の内側に入る
- until 現在の行を通過する、または指定位置を通過する、または現在のス
タックフレームに戻るまで実行する
- finish 現在の関数を抜けるまで実行する
- where スタックを表示する
- frame N N 番目のスタックフレームに移動する
- continue 実行を再開する
:Run :Arguments
ソースコードを表示するウィンドウで、これらのコマンドをgdbの制御に使用できます:
:Run [args] [args] または以前の引数でプログラムを実行する
:Arguments {args} 次の :Run のために引数を設定する
:Break カーソル位置にブレークポイントを設定する。
:Break {position}
指定位置にブレークポイントを設定する。
:Clear カーソル位置のブレークポイントを削除する
:Step gdb の "step" コマンドを実行する
:Over gdb の "next" コマンドを実行する
(:Next だと Vim のコマンドとかぶるので)
:Until gdb の "until" コマンドを実行する
:Finish gdb の "finish" コマンドを実行する
:Continue gdb の "continue" コマンドを実行する
:Stop プログラムを中断する
'mouse' が設定されている場合、プラグインはこれらのエントリを持つウィンドウツー
ルバーを追加します:
Step :Step
Next :Over
Finish :Finish
Cont :Continue
Stop :Stop
Eval :Evaluate
この方法で、マウスを使用して最も一般的なコマンドを実行できます。マウスのクリッ
クを有効にするには、'mouse' オプションを設定する必要があります。
:Winbar
開いている他のウィンドウにウィンドウツールバーを追加することができます:
:Winbar
gdbがソース行で停止し、現在ソースコードを表示しているウィンドウがない場合、ソー
スコード用の新しいウィンドウが作成されます。これは、ソースコードウィンドウの
バッファが変更され、破棄できない場合でも発生します。
gdbは各ブレークポイントに番号を与えます。Vim内では、赤い背景で、目印欄に表示さ
れます。次のgdbコマンドを使用できます。
- info break ブレークポイントの一覧
- delete N ブレークポイント N を削除
また、カーソルがブレークポイントの行にある場合は :Clear コマンドを使うことが
できます。または、右クリックのメニュー項目 "Clear breakpoint" を使用することも
できます。
変数を検査する
termdebug-variables :Evaluate
:Evaluate カーソルの下の式を評価する
K 上に同じ (無効にする場合は termdebug_map_K を参照)
:Evaluate {expr} {expr} を評価する
:'<,'>Evaluate ビジュアル選択したテキストを評価する
これは gdb ウィンドウで "print" コマンドを使ったのに相当します。
:Evaluate は :Ev に短縮できます。
その他のコマンド
termdebug-commands
:Gdb gdb ウィンドウに移動する
:Program デバッグ中のプログラムウィンドウに移動する
:Source ソースコードウィンドウにジャンプする、ウィンドウがなければ作成
する
:Asm 逆アセンブルウィンドウにジャンプする、ウィンドウがなければ作成す
る
イベント
termdebug-events
4 つのautocmdが使えます:
au User TermdebugStartPre echomsg 'debugging starting'
au User TermdebugStartPost echomsg 'debugging started'
au User TermdebugStopPre echomsg 'debugging stopping'
au User TermdebugStopPost echomsg 'debugging stopped'
au User TermdebugStartPost echomsg 'debugging started'
au User TermdebugStopPre echomsg 'debugging stopping'
au User TermdebugStopPost echomsg 'debugging stopped'
TermdebugStartPre
TermdebugStartPre デバッグ開始前。
すでにデバッガが開始しているもしくはデバッガコ
マンドが実行できない場合は発行されない。
TermdebugStartPost
TermdebugStartPost デバッグの初期化後。
:Termdebug あるいは :TermdebugCommand 経由
で ! 修飾子付きで実行された場合は gdb 内で提供
コマンドが動き出す前に発行される。
TermdebugStopPre
TermdebugStopPre デバッグの終了前で、gdb が終了する時、多くの場
合は gdb window で "quit" コマンドを発行した
後。
TermdebugStopPost
TermdebugStopPost デバッグの終了後、gdb 関連ウィンドウが閉じ、
デバッグのバッファが消去されデバッグ前の状態が
復帰した時。
プロンプトモード
termdebug-prompt
+terminal 機能がサポートされていない場合や MS-Windows上の場合、gdbは
'buftype' が "prompt" に設定されたバッファで動作します。これは少し違った働きを
します:
- コマンドを入力している間、gdbウィンドウは挿入モードになります。<Esc> でノー
マルモードにして、バッファ間を移動したり、コピー/ペーストなどをおこなうこと
ができます。a や i のような挿入モードを開始するコマンドでgdbコマンドの編
集に戻ります。
- デバッグ中のプログラムは別のウィンドウで実行されます。MS-Windowsでは、これは
新しいコンソールウィンドウです。Unixでは、+terminal 機能が利用可能な場合、
端末ウィンドウが開いてデバッグされたプログラムを実行します。
termdebug_use_prompt
プロンプトモードは、+terminal 機能が有効な場合でも使用できます:
let g:termdebug_config['use_prompt'] = 1
または、g:termdebug_config がない場合: let g:termdebug_use_prompt = 1
termdebug_map_K
K は通常 :Evaluate にマッピングされています。これが不要な場合は:
let g:termdebug_config['map_K'] = 0
または、g:termdebug_config がない場合: let g:termdebug_map_K = 0
termdebug_disasm_window
Asm ウィンドウをデフォルトで表示させたい場合、このフラグに1を設定します。
"disasm_window_height" エントリを使用してウィンドウの高さを設定できます:
let g:termdebug_config['disasm_window'] = 1
let g:termdebug_config['disasm_window_height'] = 15
または、g:termdebug_config がない場合:let g:termdebug_config['disasm_window_height'] = 15
let g:termdebug_disasm_window = 15
1以上の任意の値を設定でき、その値が Asm ウィンドウの高さになります。通信
termdebug-communication
Vim が gdb と通信するために他に隠されたバッファを利用します。バッファ名は "gdb
communicate" です。このバッファは消さないでください。消してしまうとデバッガが
動作しなくなってしまうでしょう。
gdb は奇妙な動作をしていますが、プラグインはその問題を回避するために最善を尽く
しています。
例えば、gdbウィンドウで "continue" と入力した後に、CTRL-C を使用して実行中のプ
ログラムを中断することができます。しかし、MIコマンド "-exec-continue" を使用し
た後、CTRL-C を押しても中断しません。したがって、通信チャネルを使用する代わり
に、:Continue コマンドに "continue" が使用されていることがわかります。
カスタマイズ
termdebug-customizing g:termdebug_config
以前はいくつかのグローバル変数を設定に使用していました。これらは非推奨になり、
辞書 g:termdebug_config の使用が推奨されます。g:termdebug_config が存在する時
は他のグローバル変数は使用されません。
GDBコマンド
g:termdebugger
gdb コマンド以外のデバッガを使うには、:Termdebug を実行する前に
g:termdebug_config の "debugger" エントリか "g:termdebugger" 変数を変更してく
ださい:
let g:termdebug_config['command'] = "mygdb"
または、g:termdebug_config がない場合: let g:termdebugger = "mygdb"
コマンドに引数が必要な場合はリストを使用してください:
let g:termdebug_config['command'] = ['rr', 'replay', '--']
または、g:termdebug_config がない場合: let g:termdebugger = ['rr', 'replay', '--']
gdb がデバッガで適切に動作するように、いくつかの引数が追加されます。それらを変
更したい場合は、引数リストをフィルタリングする関数を追加します:
let g:termdebug_config['command_filter'] = MyDebugFilter
引数を追加したくないが、"pty" を設定する必要がある場合は、関数を使用して必要な
引数を追加します:
let g:termdebug_config['command_add_args'] = MyAddArguments
この関数はいままでの引数のリストと、ptyの名前である2番目の引数とともに呼ばれます。
gdb-version
gdb と完全互換のあるデバッガのみが使えます。Vim は gdb の操作に GDB/MI インター
フェイスを利用しています。 "new-ui" コマンドには、gdbバージョン7.12以降が必要
です。このエラーが発生した場合:
Undefined command: "new-ui". Try "help".~
あなたの gdb が古すぎます。カラー
hl-debugPC hl-debugBreakpoint
サインの色は以下のハイライトグループで調整できます:
- debugPC 現在の位置
- debugBreakpoint ブレークポイント
'background' オプションが "light" の時のデフォルトは以下のとおりです:
hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
hi debugBreakpoint term=reverse ctermbg=red guibg=red
'background' オプションが "dark" の時は以下のとおりです:
hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
hi debugBreakpoint term=reverse ctermbg=red guibg=red
ショートカット
termdebug_shortcuts
TermDebugSendCommand() 関数を使用して、任意のウィンドウで動作する gdb を制御す
る独自のショートカット(マッピング)を定義できます。例:
map ,w :call TermDebugSendCommand('where')<CR>
引数は gdb コマンドです。ポップアップメニュー
termdebug_popup
デフォルトでTermdebugプラグインは 'mousemodel' を "popup_setpos" に設定し、こ
れらのエントリをポップアップメニューに追加します:
Set breakpoint :Break
Clear breakpoint :Clear
Evaluate :Evaluate
あなたがこれを望まないならば、それを無効にしてください:
let g:termdebug_config['popup'] = 0
または、g:termdebug_config がない場合: let g:termdebug_popup = 0
Vimのウィンドウ幅
termdebug_wide
デバッグを開始した際に Vim のウィンドウ幅を変更し、垂直分割を利用するには次の
ように設定します:
let g:termdebug_config['wide'] = 163
または、g:termdebug_config がない場合: let g:termdebug_wide = 163
これは :Termdebug を実行した際に 'columns' を 163 に設定します。元の値はデ
バッガが終了する際に復元されます。
幅の値が設定されていて、'columns' がすでに幅の値より大きい場合、'columns' を変
更せずに垂直分割が使用されます。
幅の値を1に設定することで 'columns' の変更なしに垂直分割が使えます。これは端末
がVimによってサイズ変更できない場合に便利です。
vim:tw=78:ts=8:noet:ft=help:norl: