vim-jp / vimdoc-ja / terminal

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

メインヘルプファイルに戻る English | 日本語 | 編集
terminal.txt  For Vim バージョン 9.1.  Last change: 2024 Feb 21


                VIMリファレンスマニュアル    by Bram Moolenaar


端末ウィンドウサポート                          terminal terminal-window


端末機能はオプションなので、あなたのVimが対応しているかは次のコマンドを使って
確認できます: >
        echo has('terminal')
結果が "1" ならば対応しています。


1. 基本的な使い方               terminal-use
      キー入力                          terminal-typing
      サイズと色                        terminal-size-color
      文法                              :terminal
      サイズ変更                        terminal-resizing
      端末モード                        Terminal-mode
      カーソルスタイル                  terminal-cursor-style
      セッション                        terminal-session
      特別なキー                        terminal-special-keys
      Unix                              terminal-unix
      MS-Windows                        terminal-ms-windows
2. 端末関数                             terminal-function-details
3. 端末通信                             terminal-communication
      Vim からジョブへ: term_sendkeys() terminal-to-job
      ジョブから Vim へ: JSON API       terminal-api
      クライアントサーバー機能を使う    terminal-client-server
4. リモートテスト               terminal-testing
5. 画面ダンプの差分             terminal-diff
      Vimの画面ダンプテストを書く       terminal-dumptest
      画面ダンプを作成する              terminal-screendump
      画面ダンプを比較する              terminal-diffscreendump
6. デバッグ                     terminal-debug
      はじめに                          termdebug-starting
      セッション例                      termdebug-example
      コードをステップ実行する          termdebug-stepping
      変数を検査する                    termdebug-variables
      スタックフレームの移動            termdebug-frames
      その他のコマンド                  termdebug-commands
      イベント                          termdebug-events
      プロンプトモード                  termdebug-prompt
      マッピング                        termdebug-mappings
      通信                              termdebug-communication
      カスタマイズ                      termdebug-customizing

{Vimが +terminal 機能付きでコンパイルされたときのみ有効}
端末機能を使うには +job と +channel 機能が必要です。

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

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

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

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


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

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


端末ウィンドウでの特別な操作:                   t_CTRL-W_.  t_CTRL-W_N
        CTRL-W .        端末内のジョブに CTRL-W を送る
        CTRL-W CTRL-\   端末内のジョブに CTRL-\ を送る
        CTRL-W N        端末ノーマルモードに移行、Terminal-mode を参照
        CTRL-\ CTRL-N   端末ノーマルモードに移行、Terminal-mode を参照
        CTRL-W " {reg}  レジスタ {reg} の内容を貼り付け t_CTRL-W_quote
                        式の評価結果を挿入するためのレジスタ = も機能する
        CTRL-W CTRL-C   ジョブを停止する。下記の t_CTRL-W_CTRL-C を参照
        CTRL-W gt       次のタブページに移動する。`gt` と同じ   t_CTRL-W_gt
        CTRL-W gT       前のタブページに移動する。`gT` と同じ   t_CTRL-W_gT

CTRL-W の代わりに別のキーを使うにはオプション 'termwinkey' を参照してください。
但し 'termwinkey' を2回タイプすると 'termwinkey' がジョブへ送信されます。例:
        'termwinkey' CTRL-W    次のウィンドウにフォーカスを移動する
        'termwinkey' :         Exコマンドに入る
        'termwinkey' 'termwinkey' 端末内のジョブに 'termwinkey' を送信する
        'termwinkey' .         端末内のジョブに 'termwinkey' を送信する
        'termwinkey' CTRL-\    端末内のジョブに CTRL-\ を送信する
        'termwinkey' N         端末ノーマルモードへ移行する。以下を参照
        'termwinkey' CTRL-N    CTRL-W N と同じ t_CTRL-W_N
        'termwinkey' CTRL-C    CTRL_W CTRL_C と同じ t_CTRL-W_CTRL-C
                                                        t_CTRL-\_CTRL-N
他のモードと同じように、ノーマルモードへ移行するための特別なキーの組み合わせで
ある CTRL-\ CTRL-N が利用できます。
                                                        t_CTRL-W_CTRL-C
ジョブを強制停止するのに CTRL-W CTRL-C を使えます。MS-Windowsでは CTRL-Break
でも同様にジョブを停止できます。

CTRL-C を入力した場合、その効果は pty がどのように構成されているかに従います。
シンプルなコマンドにおいては SIGINT がジョブに送られ、結果的にジョブが停止する
でしょう。中には SIGINT を無視するコマンドもあるでしょうし、また (Vim がそうし
ているように) CTRL-C をプログラム自身で取り扱うものもあるでしょう。

入力したキーを別のものに読み替えさせるには端末モードマッピング、詳細は :tmap
を参照してください。これはどのようなマッピングでも定義できますが、端末内で実行
されているジョブに送信されるキー入力にのみ作用します。例えば、F1 キーで端末ノー
マルモードに切り替えるには: >
   tnoremap <F1> <C-W>N
Esc を使うことができますが、他のキーが壊れないようにする必要があります (カーソ
ルキーは Esc で始まるので、それらは壊れるかもしれません)、これはおそらくGUIで
しか動作しません: >
   tnoremap <Esc> <C-W>N
   set notimeout ttimeout timeoutlen=100

端末モードマッピングと同様にメニューを作成することもできますが、:tmenu ではな
く :tlmenu を使用する必要があります。

                                                        options-in-terminal
端末ウィンドウを開いて 'buftype' を "terminal" に設定すると、TerminalWinOpen
自動コマンドイベントが発生します。これにより、端末ウィンドウとバッファ専用のオ
プションを設定することが可能です。例: >
   au TerminalWinOpen * setlocal bufhidden=hide
これが適切に動作するのは端末が隠れていない場合に限ります。

端末が隠れている場合と隠れていない場合両方で動作するのは、バッファローカルと
ウィンドウローカルのオプションです: >
   au TerminalWinOpen,BufWinEnter * if &buftype == 'terminal'
        \ | setlocal bufhidden=hide colorcolumn=123
        \ | endif
Note この隠れている端末のオプションは端末が隠れている間は値が設定されません。

TerminalOpen イベントもあります。これは隠れた端末で発生するかもしれず、その
場合は現在のウィンドウとバッファはこの新しい端末ではないことに注意してくださ
い。
端末バッファに設定するなら、<abuf> を使う必要があります。例: >
    au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(),
            \ '&termwinscroll', 1000)
ウィンドウローカルオプションは、端末ウィンドウが生成されるまで設定が遅延する必
要があります (これは隠れた端末だけで働きます): >
    au TerminalOpen * exe printf(
        \    'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d',
        \       expand('<abuf>')->str2nr(), 123)
隠れていない端末では TerminalWinOpen を使います。

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


サイズと色 ~

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

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

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

異なる色を使う場合には Terminal ハイライトグループを利用できます。例: >
    hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
もしくは Terminal の代わりとして`term_start()` のオプション "term_highlight"
で別グループを設定できます。

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


コマンド文法 ~

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

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

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

                        Vimのコマンドを後ろに続けることはできず、どんな | も
                        [command] に含まれてしまいます。
                        同じ行で Vim コマンドを続けるなら `:execute` を利用し
                        てください。

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

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

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

                        ++curwin        現在のウィンドウで端末を開き、現在の
                                        ウィンドウを分割しない。現在のバッファ
                                        を放棄( abandon )できない場合は失敗
                                        する。
                        ++hidden        端末を隠しバッファとして開く。ウィンド
                                        ウは使用されない。
                        ++norestore     セッションファイルに端末ウィンドウを含
                                        めない。
                        ++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!`
を使うとジョブは終了します。ウィンドウのテキストは失われ、バッファは削除されま
す。`CTRL-W :bunload!` はバッファは残りますが、空になります。

`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


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, "")
<
                デフォルトは "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` からの出力は、再描画によって消去されるかもしれません。
                `: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-autoshelldir
これを使用して、カレントディレクトリをシェルから Vim に渡すことができます。こ
れを .vimrc に置きます: >
        def g:Tapi_lcd(_, path: string)
            if isdirectory(path)
                execute 'silent lcd ' .. fnameescape(path)
            endif
        enddef
<
そして、bash の初期化ファイルには: >
        if [[ -n "$VIM_TERMINAL" ]]; then
            PROMPT_COMMAND='_vim_sync_PWD'
            function _vim_sync_PWD() {
                printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD"
            }
        fi
<
または、zsh の場合は: >
        if [[ -n "$VIM_TERMINAL" ]]; then
            autoload -Uz add-zsh-hook
            add-zsh-hook -Uz chpwd _vim_sync_PWD
            function _vim_sync_PWD() {
                printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD"
            }
        fi
<
または、fish の場合は: >
        if test -n "$VIM_TERMINAL"
            function _vim_sync_PWD --on-variable=PWD
                printf '\033]51;["call", "Tapi_lcd", "%s"]\007' "$PWD"
            end
        end


クライアントサーバー機能を使う ~
                                                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

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


セッション例 ~
                                                        termdebug-example
Vimの "src" ディレクトリを起動して、Vimをビルドします: >
        % make
デバッグシンボルが存在することを確認します。通常は、$CFLAGS に "-g" が含まれる
ことを意味します。

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          現在の行を実行し、次の文(の手前)で停止する。関数の内側に入る
- until         現在の行を通過する、または指定位置を通過する、または現在のス
                タックフレームに戻るまで実行する
- finish        現在の関数を抜けるまで実行する
- where         スタックを表示する
- frame N       N 番目のスタックフレームに移動する
- continue      実行を再開する

                                                :Run :Arguments
ソースコードを表示するウィンドウで、これらのコマンドをgdbの制御に使用できます:
 `:Run[args]      [args] または以前の引数でプログラムを実行する
 `:Arguments{args}  次の `:Run` のために引数を設定する
 :Break       カーソル位置にブレークポイントを設定する
 :Break {position}
                指定位置にブレークポイントを設定する
 :Tbreak      カーソル位置に一時的なブレークポイントを設定する
 :Tbreak {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' オプションを設定する必要があります。
このツールバーの設定については、termdebug_winbar を参照。
                                                                :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-frames :Frame :Up :Down
 `:Frame[frame]       フレームを選択する。[frame] は、フレーム番号、アドレ
                        ス、または関数名 (デフォルト: カレントフレーム)
 `:Up[count]          [count] フレーム上へ (デフォルト: 1; カレントを呼び出
                        したフレーム)
 `+`                    同上 (無効にするには termdebug_map_plus を参照)
 `:Down[count]        [count] フレーム下へ (デフォルト: 1; カレントによって
                        呼び出されるフレーム)
 `-`                    同上 (無効にするには termdebug_map_minus を参照)


その他のコマンド ~
                                                        termdebug-commands
 :Gdb      gdb ウィンドウに移動する
 :Program    デバッグ中のプログラムウィンドウに移動する
 :Source     ソースコードウィンドウにジャンプする、ウィンドウがなければ作成
             する
 :Asm      逆アセンブルウィンドウにジャンプする、ウィンドウがなければ作成す
             る
 :Var      ローカル変数と引数変数のあるウィンドウにジャンプし、なければ作成
             する。このウィンドウは、プログラムが停止されるたびに更新される

イベント ~
                                                        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'
<
                                                TermdebugStartPre
TermdebugStartPre               デバッグ開始前。
                                すでにデバッガが開始しているもしくはデバッガコ
                                マンドが実行できない場合は発行されない。
                                                TermdebugStartPost
TermdebugStartPost              デバッグの初期化後。
                                `:Termdebug` あるいは `:TermdebugCommand` 経由
                                で ! 修飾子付きで実行された場合は gdb 内で提供
                                コマンドが動き出す前に発行される。
                                                TermdebugStopPre
TermdebugStopPre                デバッグの終了前で、gdb が終了する時、多くの場
                                合は gdb window で "quit" コマンドを発行した
                                後。
                                                TermdebugStopPost
TermdebugStopPost               デバッグの終了後、gdb 関連ウィンドウが閉じ、
                                デバッグのバッファが消去されデバッグ前の状態が
                                復帰した時。


カスタマイズ ~
                                termdebug-customizing g:termdebug_config
以前は、構成にいくつかのグローバル変数が使用されていました。これらは非推奨であ
り、g:termdebug_config 辞書の使用が推奨されます。g:termdebug_config が存在する
場合、他のグローバル変数は使用されません。推奨される方法は、空の辞書から始める
ことです: >
        let g:termdebug_config = {}

次に、以下のように辞書にエントリを追加することができます。非推奨のグローバル変
数名については、念のため記載しています。g:termdebug_config の使用に切り替える
場合は、古い変数名を見つけてその値を引き継ぎ、非推奨の変数を削除することができ
ます。


プロンプトモード ~
                                                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 termdebug-mappings
K へのバッファローカル (:map-local) マッピングがすでに存在している場合を除
き、K キーは通常 :Evaluate にマップされています。これが不要な場合は: >
        let g:termdebug_config['map_K'] = 0
g:termdebug_config がない場合は、以下を使用できます: >
        let g:termdebug_map_K = 0
<
                                                termdebug_map_minus
- へのバッファローカルマッピングがすでに存在している場合を除き、- は通常
:Down にマップされています。これが不要な場合は: >
        let g:termdebug_config['map_minus'] = 0
<
                                                termdebug_map_plus
+ へのバッファローカルマッピングがすでに存在している場合を除き、+ は通常 :Up
にマップされています。これが不要な場合は: >
        let g:termdebug_config['map_plus'] = 0
<
                                                termdebug_disasm_window
Asm ウィンドウをデフォルトで表示させたい場合、"disasm_window" フラグに 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_disasm_window = 15
1以上の任意の値を設定でき、その値が Asm ウィンドウの高さになります。
カレントウィンドウに十分な水平方向のスペースがある場合、垂直方向に分割され、
Asm ウィンドウがソースコードウィンドウと並べて表示されます (高さのオプションは
使用されません)。

                                                termdebug_variables_window
Var ウィンドウをデフォルトで表示させたい場合、"variables_window" フラグに 1 を
設定します。"variables_window_height" エントリを使用してウィンドウの高さを設定
できます: >
        let g:termdebug_config['variables_window'] = 1
        let g:termdebug_config['variables_window_height'] = 15
g:termdebug_config がない場合は、以下を使用できます: >
        let g:termdebug_variables_window = 15
1 以上の任意の値を設定でき、その値が Var ウィンドウの高さになります。
カレントウィンドウに十分な水平方向のスペースがある場合、垂直方向に分割され、
Var ウィンドウがソースコードウィンドウと並べて表示されます (高さのオプションは
使用されません)。

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

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


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


デフォルトの目印の変更 ~
                                                        termdebug_signs
Termdebug は、signcolumn のブレークポイント ID の 16 進数を使用してブレークポ
イントを表します。"0xFF" より大きい場合は、実際には記号用の画面セルが 2 つしか
ないため、"F+" と表示されます。

ブレークポイントの目印をカスタマイズしたい場合: >
        let g:termdebug_config['sign'] = '>>'
g:terminal_config がまだない場合は、以下を使用できます: >
        let g:termdebug_config = {'sign': '>>'}

この後、ブレークポイントはサイン欄に `>>` と表示されます。


ウィンドウツールバー ~
                                                        termdebug_winbar
デフォルトでは、マウスが有効な場合、Termdebug プラグインはウィンドウツールバー
を作成します (:Winbar を参照)。これを望まない場合は、次のようにして無効にし
てください: >
        let g:termdebug_config['winbar'] = 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: