vim-jp / vimdoc-ja / terminal

terminal - Vim日本語ドキュメント

メインヘルプファイルに戻る English | 日本語 | 編集
terminal.txt  For Vim バージョン 8.1.  Last change: 2018 May 17


                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-communication
      Vim からジョブへ: term_sendkeys() terminal-to-job
      ジョブから Vim へ: JSON API       terminal-api
      クライアントサーバー機能を使う    terminal-client-server
3. リモートテスト               terminal-testing
4. 画面ダンプの差分             terminal-diff
      Vimの画面ダンプテストを書く       terminal-dumptest
      画面ダンプを作成する              terminal-screendump
      画面ダンプを比較する              terminal-diffscreendump
5. デバッグ                     terminal-debug
      はじめに                          termdebug-starting
      セッション例                      termdebug-example
      コードをステップ実行する          termdebug-stepping
      変数を検査する                    termdebug-variables
      その他のコマンド                  termdebug-commands
      プロンプトモード                  termdebug-prompt
      通信                              termdebug-communication
      カスタマイズ                      termdebug-customizing

{Vi にはこれらのコマンドはありません}
{Vimが +terminal 機能付きでコンパイルされたときのみ有効}

端末機能を使うには +multi_byte+job そして +channel 機能が必要です。

==============================================================================
1. 基本的な使い方                                       terminal-use

これは Vim のウィンドウ内で端末エミュレーターを実行する機能です。端末エミュレー
ターに接続すると1つのジョブが開始されます。例としてシェルを実行するならば以下
のようになります:
     :term bash

またビルドコマンドを実行するにはこうなります:
     :term make myprogram

ジョブはVimとは非同期的に動作し、他のウィンドウで編集中であってもジョブからの
出力は随時端末ウィンドウに反映されます。


キー入力
                                                        terminal-typing
端末ウィンドウにキーボードのフォーカスがある時には、入力したキーはジョブに送ら
れます。これには可能ならば pty を使用します。端末ウィンドウ外をクリックすれば、
キーボードフォーカスを外に動かせます。

ウィンドウや他の CTRL-W コマンドを操作するために CTRL-W を使えます。例えば:
        CTRL-W CTRL-W   次のウィンドウにフォーカスを移動する
        CTRL-W :        Exコマンドに入る
他のコマンドについては CTRL-W 参照してください。


端末ウィンドウでの特別な操作:                   CTRL-W_.  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} の内容を貼り付け CTRL-W_quote
                        式の評価結果を挿入するためのレジスタ = も機能する
        CTRL-W CTRL-C   ジョブを停止する, 下記の t_CTRL-W_CTRL-C を参照

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 と同じ
        'termwinkey' 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 を使うことができますが、他のキーが壊れないようにする必要があります:
   tnoremap <Esc> <C-W>N
   set notimeout ttimeout timeoutlen=100

                                                        options-in-terminal
端末ウィンドウを開いて 'buftype' を "terminal" に設定すると、TerminalOpen 自動
コマンドイベントが発生します。これにより、ウィンドウとバッファ専用のオプション
を設定することが可能です。例:
   au TerminalOpen * if &buftype == 'terminal' | setlocal bufhidden=hide | endif
<abuf> は端末バッファに設定されていますが、ウィンドウが存在しない場合(隠され
た端末)は間違ったバッファにオプションが設定されるため、この例では &buftype の
チェックが行われます。

マウスイベント (クリックやドラッグ) は端末に渡されます。マウス移動イベントは
Vim 自身が受け取ったときにのみ渡されます。'balloonevalterm' が有効になっている
端末の場合です。


サイズと色

                                                        terminal-size-color
端末ウィンドウのサイズを制御するにはオプション 'termwinsize' を参照してくださ
い。
(TODO: 端末がウィンドウよりも大きい場合にはスクロールすることを記述する)

端末内のジョブは端末の色を変更できます。デフォルトの前景色及び背景色はVimの
Normal ハイライトグループにより決定されます。

カラー端末を開始する際に、背景に白と黒どちらの系統の色を使用するかは、オプショ
ン 'background' を用いて決定します。

異なる色を使う場合には Terminal ハイライトグループを利用できます。例:
    hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue

                                                        g:terminal_ansi_colors
新しい端末ウィンドウでデフォルトで使用される16個のANSI カラーは、変数
g:terminal_ansi_colors を使用して設定することができます。これは、16個の色名
または 16進数の色コードのリストでなければなりません。これは、highlight-guifg
で受け入れられるものと同様です。 GUI カラーを使用しない場合、端末ウィンドウは
常に端末基礎の16個の ANSI カラーを使用します。
term_setansicolors() 関数を使用して色を変更したり、term_getansicolors() を
使用して現在使用されている色を取得することができます。


文法

:[range]ter[minal] [options] [command]                  :ter :terminal
                        新しい端末ウィンドウを開きます。

                        [command] が指定された場合、それをジョブとして実行し、
                        端末の入出力を接続します。
                        [command] が指定されなかった場合、オプション 'shell'
                        を使用します。
                        [command] が NONE の場合ジョブは開始されず、端末の pty
                        は gdb のようなコマンドによって利用できます。

                        [command] がない場合、デフォルトの動作はシェルが終了し
                        たときに端末を閉じます。この動作は ++noclose 引数で変
                        更できます。
                        [command] が指定されている場合、デフォルトの動作は端末
                        を端末ノーマルモードで開いたままにします。
                        この動作は ++close 引数で変更できます。

                        新しいバッファが作られ、 [command] もしくは 'shell' に
                        "!" が前置された名前が与えられます。すでに同じ名前の
                        バッファが存在する場合には、カッコに囲まれた番号が付与
                        されます。例えば "gdb" が存在するなら2つ目の端末には
                        "!gdb (1)" という名前が使われます。

                        [range] が与えられた場合は、指定された範囲の行がジョブ
                        の入力として使われます。その際の端末ウィンドウではキー
                        入力ができなくなります。MS-Windows においては以下の
                        ++eof オプションも参照してください。

                                                term++close term++open
                        サポートされる [options] は以下の通り:
                        ++close         ジョブが終了した際には自動的に端末ウィ
                                        ンドウを閉じる。
                        ++noclose       ジョブが終了しても自動的に端末ウィンド
                                        ウを閉じません。
                        ++open          ジョブが終了した際にウィンドウが表示さ
                                        れていない場合に、ウィンドウを表示す
                                        る。割り込み的に発生しうることに留意。
                                ++close, ++noclose と ++open は最後に指定され
                                たものが有効です。

                        ++curwin        現在のウィンドウで端末を開き、現在の
                                        ウィンドウを分割しない。現在のバッファ
                                        を放棄( abandon )できない場合は失敗
                                        する。
                        ++hidden        端末を隠しバッファとして開く。ウィンド
                                        ウは使用されない。
                        ++norestore     セッションファイルに端末ウィンドウを含
                                        めません。
                        ++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 を示す。

                        より詳細なオプションを使いたいならば term_start() 関
                        数を使ってください。

端末に関連付けられたバッファが強制的にアンロードもしくは削除された場合には、
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 コマンドで現在のウィンドウを端末ウィンドウにするこ
とができます。未保存の変更があった場合にはこれは失敗しますが、通常と同じように
! で強制できます。

バックグラウンドジョブをウィンドウ無しで実行し、終了したらウィンドウに表示する
には、次のようにオプションを指定します:
        :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


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 という名前に変更してください。

環境変数は実行中のジョブに情報を渡すために使用されます:
    VIM_SERVERNAME      v:servername

==============================================================================
2. 端末通信                                      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_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 からの出力は、再描画によって消去されるかもしれません。
                :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&

理論的根拠: コマンドや式を許可しないのはなぜですか? セキュリティ上の問題が生
じる可能性があるためです。


クライアントサーバー機能を使う
                                                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行目にカーソルが置かれます。

==============================================================================
3. リモートテスト                                       terminal-testing

VimのほとんどのテストはVimのなかでスクリプトを実行しています。テスト対象のコー
ドと干渉してしまうような、幾つかのテストではこれは機能しません。これを避けるた
めに端末ウィンドウ内でさらにVimを実行しています。そのテストではキーストローク
を端末に送信し、その結果として端末画面の状態が変わるのを検査します。

関数

term_sendkeys()         端末にキーストロークを送信する (tmap の影響を受けない)
term_wait()             端末画面が更新されるのを待つ
term_scrape()           端末画面の内容を検査する


==============================================================================
4. 画面ダンプの差分                                     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("Test_func.dump.failed", "dumps/Test_func.dump")

カレントディレクトリを src/testdir に設定して、Vimでこのコマンドを使用します。
テストに満足したら、参照の代わりに失敗したダンプを移動します:
        :!mv Test_func.dump.failed 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' を使用します。

あるいは、 "s" を押して、1番目と2番目のダンプを入れ替えます。これを何度か実行
して、テキストの文脈における相違を見つけ出すことができます。

==============================================================================
5. デバッグ                             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 の制御下にない。バッファ名は "gdb 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

引数が指定されていない場合、gdbウィンドウが表示されます。このウィンドウでは、
例えばgdbの file コマンドを使って、どのコマンドを実行するか指定する必要があ
ります。


セッション例
                                                        termdebug-example
Vimの "src" ディレクトリを起動して、Vimをビルドします:
        % make
Vimを起動します:
        % ./vim
termdebug プラグインを読み込んで、Vimのデバッグを開始します:
        :packadd termdebug
        :Termdebug vim
これで、3つのウィンドウが表示されます:
    source  - 開始直後はボタン付きウィンドウツールバーがあります
    gdb     - ここに gdb コマンドを入力できます
    program - 実行されたプログラムはこのウィンドウを使用します

CTRL-W CTRL-W またはマウスを使用して、ウィンドウ間でフォーカスを移動できます。
gdbウィンドウにフォーカスを当てて、次のように入力します:
        break ex_help
        run
Vim は programウィンドウで実行を開始します。そこにフォーカスを置いて入力しま
す:
        :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          現在の行を実行し、次の文(の手前)で停止する。関数の内側に入る
- finish        現在の関数を抜けるまで実行する
- where         スタックを表示する
- frame N       N 番目のスタックフレームに移動する
- continue      実行を再開する

                                                :Run :Arguments
ソースコードを表示するウィンドウで、これらのコマンドをgdbの制御に使用できます:
 :Run [args]      [args] または以前の引数でプログラムを実行する
 :Arguments {args}  次の :Run のために引数を設定する
 :Break       現在の行にブレークポイントを設定する。サインが表示される
 :Delete      現在の行のブレークポイントを削除する
 :Step        gdb の "step" コマンドを実行する
 :Over        gdb の "next" コマンドを実行する
                (:Next だと Vim のコマンドとかぶるので)
 :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                  上に同じ
 :Evaluate {expr}   {expr} を評価する
 :'<,'>Evaluate     ビジュアル選択したテキストを評価する

これは gdb ウィンドウで "print" コマンドを使ったのに相当します。
:Evaluate は :Ev に短縮できます。


その他のコマンド
                                                        termdebug-commands
 :Gdb      gdb ウィンドウに移動する
 :Program    デバッグ中のプログラムウィンドウに移動する
 :Source     ソースコードウィンドウにジャンプする、ウィンドウがなければ作成する


プロンプトモード
                                                termdebug-prompt
+terminal 機能がサポートされていない場合や MS-Windows上の場合、gdbは
'buftype' が "prompt" に設定されたバッファで動作します。これは少し違った働きを
します:
- コマンドを入力している間、gdbウィンドウは挿入モードになります。<Esc> でノー
  マルモードにして、バッファ間を移動したり、コピー/ペーストなどをおこなうこと
  ができます。a や i のような挿入モードを開始するコマンドでgdbコマンドの編
  集に戻ります。
- デバッグ中のプログラムは別のウィンドウで実行されます。MS-Windowsでは、これは
  新しいコンソールウィンドウです。Unixでは、+terminal 機能が利用可能な場合、
  端末ウィンドウが開いてデバッグされたプログラムを実行します。

                                                termdebug_use_prompt
プロンプトモードは、+terminal 機能が有効な場合でも使用できます:
        let g:termdebug_use_prompt = 1


通信
                                                termdebug-communication
Vim が gdb と通信するために他に隠されたバッファを利用します。バッファ名は "gdb
communicate" です。このバッファは消さないでください。消してしまうとデバッガが
動作しなくなってしまうでしょう。

gdb は奇妙な動作をしていますが、プラグインはその問題を回避するために最善を尽く
しています。
たとえば、gdbウィンドウで "continue" と入力した後に、CTRL-C を使用して実行中の
プログラムを中断することができます。しかし、MIコマンド "-exec-continue" を使用
した後、CTRL-C を押しても中断しません。したがって、通信チャネルを使用する代わ
りに、:Continue コマンドに "continue" が使用されていることがわかります。


カスタマイズ

GDBコマンド                                              termdebug-customizing

gdb コマンド以外のデバッガを使うには、 :Termdebug を実行する前に
"termdebugger" 変数を変更してください:
        let termdebugger = "mygdb"
                                                        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_popup = 0


Vimのウィンドウ幅                                               termdebug_wide

デバッグを開始した際に Vim のウィンドウ幅を変更し、垂直分割を利用するには次の
ように設定します:
  let g:termdebug_wide = 163
これは :Termdebug を実行した際に &columns を 163 に設定します。元の値はデバッ
ガが終了する際に復元されます。
g:termdebug_wide が設定されていて、&columnsがすでに g:termdebug_wide より大き
い場合、&columns を変更せずに垂直分割が使用されます。
&columns を変更せずに垂直分割を行うには、1に設定します。(端末がVimによってサイ
ズ変更できない場合に便利です)



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