イベントに應じて自動的にコマンドを實行する

*autocmd.txt*   For Vim バージョン 8.1.  Last change: 2019 Sep 16


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

自動コマンド

基本的な說明については、ユーザーマニュアルの |40.3| 章を參照。

1. はじめに

ファイルを讀み込んだり書き込むときや、バッファやウィンドウに入つたり出たりしたとき、あるいは Vim を終了させるときに、コマンドを自動的に實行するやうに指定できる。例へば "*.c" にマッチするファイルに對して、オプション ’cindent’ をオンにする自動コマンドを作ることができる。また自動コマンドでさらに高度な機能を實裝することができる。壓縮ファイルを編輯するといつたやうな機能だ (|gzip-example| を參照)。かういつた自動コマンドはファイル .vimrc かファイル .exrc に書き込む。

警告:
自動コマンドは大變强力であるので、思ひも寄らない副作用をもたらすことがある。テキストを壞さないやうに注意しなければならない。

• 捨ててもよいやうなファイルのコピーに對して、最初にテストしておくのがよい。例へば、ファイルの編輯開始時にファイルを解凍する自動コマンドを使ふときには、書き込みするときに壓縮を行ふ自動コマンドが正しく働くか確かめること。
• 實行中のエラー (例へばディスクが滿杯になる) に對して、對處の準備をしておかなければならない。バッファへの變更に對しては大抵アンドゥができるが、他のファイルへの變更は、自分で處理しなければならないかもしれない (例へば、解凍されたファイルを壓縮する、等)。
• もしイベント BufRead* の自動コマンドによつて壓縮ファイルを編輯できるなら、FileRead* でも同じ事ができるやうにするべきである (かうすることで復舊可能になる場合がたまにある)。可能であれば、イベント File* や Buf* には同じ自動コマンドを使ふのはよい考へだ。

2. 自動コマンドの定義

:au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd}

{pat} |autocmd-patterns| に一致するファイルで、{event} のときに自動的に實行するコマンドのリストに、{cmd} を加へる。

Note:
クォートは :autocmd への引數として見なされ、コメントを開始しないことに注意。

{cmd} は常に既存の自動コマンドの後に追加されるので、自動コマンドは指定された順に實行される。 [nested] については |autocmd-nested| を參照。後方互換性のために、"nested" (++ なし) も使用できる。

[++once] が指定されてゐる場合、コマンドは 1 回實行されると削除される ("one shot")。

特殊なパターン <buffer> や <buffer=N> はバッファローカルな自動コマンドを定義する。|autocmd-buflocal| を參照。

Note:
’|’ が {cmd} の前にある場合、":autocmd" コマンドの後には別のコマンドを續けることができる。これは動作する:

:augroup mine | au! BufRead | augroup END

しかし、これは定義されたコマンドの一部として "augroup" を見る:

:augroup mine | au! BufRead * | augroup END
:augroup mine | au BufRead * set tw=70 | augroup END

代はりにグループ名をコマンドの中に置くことができる:

:au! mine BufRead *
:au mine BufRead * set tw=70

もしくは ‘:execute‘ を使用する:

:augroup mine | exe "au! BufRead *" | augroup END
:augroup mine | exe "au BufRead * set tw=70" | augroup END

Note:
":autocmd" の引數の中の特別な文字 (例へば "%" や "<cword>" 等) は、自動コマンドが定義されたときに展開されるのではなく、イベントの發生が認識され、{cmd} が實行されるときに展開されることに注意せよ。唯一の例外は、"<sfile>" が自動コマンドが定義されたときに展開されることである。例:

:au BufNewFile,BufRead *.html so <sfile>:h/html.vim

ここで <sfile> は、この行を含むファイルの名前に展開される。

‘:autocmd‘ は、すでに存在してゐるかどうかにかかはらず、自動コマンドのリストに追加する。.vimrc ファイルが 2 囘讀み込まれると、自動コマンドが 2 回表示される。これを避けるには、グループ內に自動コマンドを定義することで、簡單にクリアできる:

augroup vimrc
  " 「全ての」vimrcの自動コマンドを削除する
  autocmd!
  au BufNewFile,BufRead *.html so <sfile>:h/html.vim
augroup END

もし全ての自動コマンドを消去したくなかつたら、代はりに變數を使つて自動コマンドを讀み込むのがただ1度だけにすることができる。

:if !exists("autocommands_loaded")
:  let autocommands_loaded = 1
:  au ...
:endif

引數 [group] が指定されないと、現在のグループが使はれる (":augroup" で定義されたもの)。さうでなければ、Vim は [group] で定義されたグループを使ふ。

Note:
[group] はあらかじめ定義されてゐなければならないことに注意。

":au group ..." で新しいグループを定義することはできない。それには ":augroup" を使ふこと。

自動コマンドをテストするとき、オプション ’verbose’ が便利かもしれない。

:set verbose=9

この設定により、Vim は自動コマンドが實行されるとそれらを表示するやうになる。

スクリプト內で自動コマンドを定義するときには、スクリプト內でのみ有效なローカル函數とローカルキーマップを利用できる。イベントが發生してコマンドが實行されるとき、コマンドは自分の定義されたスクリプト內での設定に從つて働く。これはコマンドに |<SID>| が使はれてゐるときに問題になる。

コマンドを實行するとき、あるコマンドからのメッセージは前のメッセージを上書きしてしまふ。これはコマンドを手動で實行するときとは違ふ動作である。大抵、メッセージスクリーンはスクロールしないので、「續けるには」といふプロンプトは現れない。また 1 個のコマンドが 2 つのメッセージを出すときには、何にせよメッセージは上書きされてしまふ。

3. 自動コマンドの除去

:au[tocmd]! [group] {event} {pat} [++once] [++nested] {cmd}

{event} と {pat} に關聯づけられた全ての自動コマンドを除去し、コマンド {cmd} を加へる。 [nested] については |autocmd-nested| を參照。

:au[tocmd]! [group] {event} {pat}

{event} と {pat} に關聯づけられた全ての自動コマンドを除去し、コマンド {cmd} を加へる。[++once] については |autocmd-once| を參照。[++nested] については |autocmd-nested| を參照。

:au[tocmd]! [group] * {pat}

{pat} に關聯づけられた、全てのイベントに關する自動コマンドを全て除去する。

:au[tocmd]! [group] {event}

{event} に關聯づけられた「全ての」自動コマンドを除去する。

警告:
|BufRead| や他の一般的なイベントのためのグループなしでこれを行ふべきではない。プラグインや構文のハイライトなどを壞すことがある。

:au[tocmd]! [group]

「全ての」自動コマンドを除去する。

Note:
クォートは :autocmd への引數と見なされ、コメントを開始しないことに注意。

警告:
通常はグループなしでこれを行ふべきではない。プラグインや構文の强調表示などが壞れる。

引數 [group] が指定されないと、現在のグループが使はれる (":augroup" で定義されたもの)。さうでなければ、[group] で定義されたグループが使はれる。

4. 自動コマンドの列擧

:au[tocmd] [group] {event} {pat}

{event} と {pat} に關聯づけられた全ての自動コマンドを表示する。

:au[tocmd] [group] * {pat}

{pat} に關聯づけられた、全てのイベントに關する自動コマンドを表示する。

:au[tocmd] [group] {event}

{event} に關聯づけられた全ての自動コマンドを表示する。

:au[tocmd] [group]

全ての自動コマンドを表示する。

引數 [group] を指定すると、[group] に關する自動コマンドのみが列擧される。さうでなければ、「全ての」グループに關する自動コマンドが表示される。

Note:
ここでの引數による動作の違ひは、自動コマンドを定義したり除去するときとは違ふことに注意。

バッファローカルな自動コマンドを列擧するには、<buffer> または <buffer=N> といふ形のパターンを使ふ。|autocmd-buflocal| を參照。

’verbose’がゼロでないならば、自動コマンドを列擧するときに、それが最後にどこで定義されたかも表示する。例:

:verbose autocmd BufEnter
FileExplorer  BufEnter
    *         call s:LocalBrowse(expand("<amatch>"))
        Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim

より詳しい情報は |:verbose-cmd| を參照。

5. イベント

複數のイベントをコンマ (,) で區切つたリストにして指定することもできる。そのリストにはスペースを含めてはいけない。そのコマンドは指定したリストにある全てのイベントに適用される。

「ファイル讀み込み」には次の 4 種類のイベントが發生しうる。

Vim はファイルを讀み込むときにこの 4 種類のうちどれか1つを利用する。"Pre" と "Post" のイベントは、ファイル讀み込みの前後で兩方とも起動される。

Note:
イベント *ReadPre や、全てのイベント Filter に關する自動コマンドは、カレントバッファを變更してはならないことに注意 (これが起きると、エラーメッセージが表示される)。これは、閒違つたバッファにファイルを讀み込むのを防ぐためである。

Note:
オプション ’modified’ は、BufReadPost と BufNewFile の自動コマンドを實行した「後に」オフに設定されることに注意。しかし ’modified’ が自動コマンドからオンに設定されたときはさうならない。

’eventignore’ は、いくつかあるいは全てのイベントを無視するために使へる。 Vim は以下のイベントを認識する。イベント名が大文字か小文字かは無視される (例へば "BufRead" の代はりに "BUFread" や "bufread" が使へる)。

まず機能ごとに短い說明とともに槪要を解說する。それから完全な說明とともにアルファベット順のリストを載せる |autocmd-events-abc|。

自動コマンドイベントのアルファベット順リスト:

BufAdd または

BufCreate

バッファリストに追加されるバッファを作つた直後か、バッファをバッファリストに追加した直後。バッファリスト內のバッファがリネームされた直後にも發生する。イベント BufCreate は歷史上の理由で存在してゐる。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと "<afile>" で表される作成されたバッファは異なるかもしれないことに注意。

BufDelete

バッファリストからバッファを削除する前。(バッファが讀み込まれてゐるなら) BufUnload が最初に呼び出されるだらう。また、バッファリスト內のバッファがリネームされた直前にも使はれる。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと "<afile>" と "<abuf>" で表される削除されるバッファとは異なるかもしれないことに注意。他のバッファに切り替へないこと。もしすると問題が發生するだらう。

BufEnter

バッファに入つた後。ファイルタイプに關するオプションの設定に便利である。バッファの編輯を始めるときにも、BufReadPost の自動コマンドの後に實行される。

BufFilePost

現在のバッファの名前をコマンド ":file" または ":saveas" で變更した後。

BufFilePre

現在のバッファの名前をコマンド ":file" または ":saveas" で變更する前。

BufHidden

バッファが隱れ狀態 (hidden) になる直前。つまりそのバッファを表示するウィンドウがもう存在しないのに、バッファが解放されなかつたり、削除されないとき。":qa" や "q" で Vim を終了するときには使はれない。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと "<afile>" で表される解放されるバッファとは異なるかもしれないことに注意。

BufLeave

他のバッファに移る前。カレントウィンドウを離れたり、閉ぢたりするときで、新しいカレントウィンドウが同じバッファを開いてゐないとき。":qa" や "q" で Vim を閉ぢるときには使はれない。

BufNew

新しいバッファを作つた直後。バッファがリネームされた直後にも發生する。バッファがバッファリストに追加されると、イベント BufAdd も發生する。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと "<afile>" で表される作成されるバッファとは異なるかもしれないことに注意。

BufNewFile

存在しないファイルの編輯を始めたとき。スケルトンファイル {譯注: テンプレートファイルともいふ} に讀み込むときに使へる。

BufRead または

BufReadPost

新しいバッファの編輯を始めたときの、ファイルをバッファに讀み込んだ後で、モードラインを實行する前。モードラインを實行した後に何かするには |BufWinEnter| を參照すること。 これは ":r file" には「動作しない」。ファイルが存在しないときも使へない。またファイルの復舊に成功したときにも使はれる。また、":filetype detect" を實行したとき、あるいは無名バッファを保存してバッファに名前がついたとき、filetypedetect グループを對象として發行される。

BufReadCmd

新しいバッファの編輯を始める前。ファイルをバッファ內に讀み込む役目を負ふ。|Cmd-event|

BufReadPre

新しいバッファの編輯を始めたときの、ファイルをバッファに讀み込む前。讀み込むファイルが存在しないときは使へない。

BufUnload

バッファを解放する前。これは、バッファ內のテキストが解放されるときである。BufWritePost の後で、BufDelete の前かもしれない。Vim が終了しようとしてゐるとき、讀み込まれた全てのバッファについて發生する。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと"<afile>" で表される解放されるバッファとは異なるかもしれないことに注意。他のバッファやウィンドウに切り替へないこと。問題が發生するだらう。終了時に v:dying が 2 以上のときはこのイベントは發生しない。

BufWinEnter

バッファがウィンドウ內に表示された後。これはバッファが讀み込まれたとき (モードラインの處理後) か、隱れ (hidden) バッファがウィンドウ內に表示されたとき (もう隱れバッファでなくなつたとき)。 引數なしで |:split| をしたときや、既にウィンドウに表示されてゐるバッファを指定して ":split" をしたときは、同じバッファを開いたままなので、このイベントは發生しない。既存のバッファがそのまま使はれるためである。しかし、カレントバッファの名前を指定して ":split" をすると、そのバッファを再讀み込みすることになるので、發生する。

端末ウィンドウでは發生しない。何故なら Terminal-Job モードで開始され、Normal モードコマンドは機能しないからである。代はりに |TerminalOpen| を使用すること。

BufWinLeave

バッファがウィンドウから取り除かれる前。そのバッファが別のウィンドウ內で表示中ならば發生しない。Vim の終了時にも發生する。イベント BufUnload や BufHidden よりも前に發生する。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと"<afile>" で表される解放されるバッファとは異なるかもしれないことに注意。他のバッファに切り替へないこと。もしすると問題が發生するだらう。終了時に v:dying が 2 以上のときはこのイベントは發生しない。

BufWipeout

バッファを完全に削除する前。イベント BufUnload と BufDelete が先に發生するかもしれない (バッファが讀み込まれてゐて、バッファリスト內に存在するなら)。バッファがリネームされる直前にも發生する (そのバッファがバッファリスト內になくとも)。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと "<afile>" で表される削除されるバッファとは異なるかもしれないことに注意。

BufWrite または

BufWritePre

バッファ全體をファイルに書き込む前。

BufWriteCmd

バッファ全體をファイルに書き込む前。もしも成功するなら、ファイルへの書き込みを實行してオプション ’modified’ をオフにする。’cpo’ に ’+’ が無いのであれば、他のファイルに書き込みをする |cpo-+|。バッファの內容を變更すべきではない。’modified’ をオフにすると、以前の undo 狀態が ’modified’ (變更あり) になるやうに undo 情報が調整される (|:write| と同樣)。|Cmd-event|

BufWritePost

バッファ全體をファイルに書き込んだ後 (イベント BufWritePre によるコマンドをアンドゥする役目を果たす)。

CmdUndefined

ユーザー定義コマンドが使はれたが、定義されてゐなかつたとき。必要なときのみコマンドを定義するのに便利である。パターンはコマンド名に對して照合される。<amatch> と <afile> の兩方ともコマンド名に設定される。

Note:
未定義のコマンドに對して自動補完は機能しない。このイベントを使ふ代はりにユーザー定義コマンドを常に定義するやうにしてそのコマンドから autoload 函數を呼び出すやうにするといふ方法もある。|autoload| 參照。

CmdlineChanged

コマンドラインのテキストに變更が加へられた後。Vim が固まつてしまふ可能性があるので、コマンドラインで閒違ひを起こさないよう注意すること。<afile> はコマンドラインの種類を示す 1 文字に設定される。 |cmdwin-char|

CmdlineEnter

ユーザーがコマンドを入力もしくは文字列を檢索できるコマンドラインにカーソルが移動した後。<afile> はコマンドラインの種類を示す 1 文字に設定される。 |cmdwin-char|

CmdlineLeave

カーソルがコマンドラインを離れる前。CTRL-C もしくは <Esc> の入力によつてコマンドラインを抛棄する場合も同樣。

コマンドの結果がエラーとなる場合は、コマンドラインは引き續き實行中となる。

<afile> はコマンドラインの種類を示す 1 文字に設定される。|cmdwin-char|

CmdwinEnter

Command-line ウィンドウに入つた後。この特殊なウィンドウに對してのみオプションを設定するのに便利である。<afile> は、command-line の種類を示す 1 文字に設定される。|cmdwin-char|

CmdwinLeave

Command-line ウィンドウから出る前。イベント CmdwinEnter で行つたグローバル設定を消去するのに便利である。<afile> は、command-line の種類を示す 1 文字に設定される。|cmdwin-char|

ColorScheme

カラースキームを讀み込んだ後。|:colorscheme| パターンはカラースキーム名にマッチする。<afile> はこのオプションを設定したファイルの名前になる。<amatch> はカラースキーム名になる。

ColorSchemePre

カラースキームを讀み込む前。|:colorscheme|

あるカラースキームが讀み込まれる前に、それ以前に別のカラースキームによつて追加されたものを取り除くのに便利。

CompleteChanged

插入モード補完メニューが變更される度。ポップアップメニューが非表示時には發生しない。そのためには |CompleteDone| を使用すること。再歸的に發生することはない。

これらの |v:event| キーを設定する:

completed_item	|complete-items| 參照
height	表示項目數
width	畫面セル數
row	畫面上端の行
col	畫面最左の桁
size	全項目數
scrollbar	表示時 TRUE

テキストの |textlock| を變更することはできない。

ポップアップのサイズと位置は、|pum_getpos()| を呼び出すことでも得られる。

CompleteDone

插入モード補完が完了したとき。補完が實行されても中止されても發行される。|ins-completion| 變數 |v:completed_item| には補完された候補についての情報が含まれてゐる。

CursorHold

’updatetime’ の時閒の閒、ユーザーがキーを押さなかつたとき。ユーザーが何かキーを押すまで、再び發生することはない (例へば、もしあなたがコーヒーを入れるために Vim の前を離れても、その閒の ’updatetime’ ミリ秒ごと發生することはない :-)。タグをプレビューするためには、|CursorHold-example| を參照。 このイベントはノーマルモードのときのみ呼ばれる。コマンドの引數の入力待ち狀態、またはオペレータの後の移動コマンド入力待ち狀態のときは發生しない。レコーディングの最中には CursorHold イベントは發生しない。|q| この自動コマンドは內部的に <CursorHold> キーが引き金になつてゐる。式による指定のマッピング內では |getchar()| によつてこの文字が取得されることがある。

Note:
このイベントには對話的なコマンドは使へないことに注意。「續けるには」プロンプトは現れず、スクリーンは必要に應じて直接更新される。

Note:

近いうちに、發生するまでの時閒を設定する別のオプションができるだらう。

Hint:
ステータスラインの更新を强制的に行ふには、これを使ふこと:

:let &ro = &ro

{Vim の Amiga 版、Unix 版、Win32 版、MSDOS 版および全ての GUI 版でのみ有效}

CursorHoldI

CursorHold と同樣だが、插入モードのとき發生する。例へば別のキーを待つてゐるとき、例へば CTRL-V の後で、CTRL-X モード |insert_expand| ではないときにはトリガーされない。

CursorMoved

ノーマルモードかビジュアルモードでカーソルが移動した後。カーソル行のテキストが變更されたときにも發生する(例: "x", "rx", "p"などで)。先行入力があつたりオペレータが實行待ちになつてゐる場合は發生しない。|match-parens| の例を參照。

Note:
この自動イベントは ‘:noautocmd‘ を付けてもスキップできない。

Careful:
このイベントは頻繁に發生するので、ユーザーが豫期しないことや時閒のかかる處理は行はないこと。

CursorMovedI

插入モードでカーソルが移動した後。ポップアップメニューが表示されてゐるときは發行されない。それ以外は CursorMoved と同じ。

EncodingChanged

オプション ’encoding’ が變更されたとき。例へば、フォント等の設定に便利である。

FileAppendCmd

ファイルに追加する前。ファイルへの追加の役目を負ふ。|Cmd-event|

FileAppendPost

ファイルに追加した後。

FileAppendPre

ファイルに追加する前。行範圍を指定するためには ’[ と ’] マークを使ふ

FileChangedRO

讀み込み專用ファイルに最初の變更を加へる前。ソース管理システム {譯注: CVS や RCS} からファイルをチェックアウトするのに使はれる。變更が自動コマンドによるときには發生しない。このイベントが發生するのは、バッファに最初の變更を行ふときや、’readonly’ がセットされた後に最初の變更を行ふときの、變更が適用される直前である。

警告:
自動コマンドでカーソルが動かされるときの動作は、定義されてゐない。

ここで他のバッファに變更をしてはならない。バッファを再讀み込みするとはよいが、他のバッファを編輯してはならない。 行數が變化した場合 undo のための保存は失敗し、その變更は中止されるだらう。

DiffUpdated

diff が更新された後。どの diff (內藏もしくは外部) が使はれてゐるかに應じて、すべての變更もしくは最中に發動する |:diffupdate|。

DirChanged

|:cd|, |:tcd| もしくは |:lcd| コマンドによつて、もしくは ’autochdir’ オプションの結果として作業ディレクトリが變更された後。

パターンは以下のやうになる:

"window"	‘:lcd‘ により發生する
"tabpage"	‘:tcd‘ により發生する
"global"	‘:cd‘により發生する
"auto"	’autochdir’ により發生する
"drop"	ファイルの編輯により發生する

<afile> は新ディレクトリ名に設定される。

ExitPre

Vim を終了させる ‘:quit‘, ‘:wq‘ もしくは ‘:qall‘ wo使用したときで、|QuitPre| の直後。不必要なウィンドウを閉ぢるのに使ふことができる。自動的に保存されない變更濟みのバッファがある場合には、終了はまだキャンセルされる可能性がある。本當に終了するときのためには |VimLeavePre| を使用すること。

FileChangedShell

ファイルのタイムスタンプが、ファイルの編輯が始まつてから變更されたことを發見したとき。ファイルの屬性やファイルサイズが變更されたときにも使はれる。|timestamp| 大抵はシェルコマンドの實行後に發生する。またコマンド |:checktime| の實行後や、gvim が入力フォーカスを一度失ひ、再び得たときにも發生する。このイベントは變更されたファイルそれぞれに對して發生する。

オプション ’autoread’ がオンであり、かつバッファが變更されてゐないときには使はれない。もし FileChangedShell の自動コマンドが存在しても、警告メッセージやプロンプトは現れない。

變數 |v:fcs_reason| に何が起こつたのかが設定され、|v:fcs_choice| によつて Vim に次に何をすべきかを指示できる。

Note:
このイベントで自動コマンドが實行されたときは、"%" で表されるカレントバッファと "<afile>" で表される變更されたバッファとは異なるかもしれないことに注意。

Note:
この自動コマンドはカレントバッファを變更したり、別のバッファにジャンプしたり、バッファを消去してはいけない。

Note:
このイベントは、無限ループを避けるために決してネストしてはいけない (入れ子にならない)。つまり、FielChangedShell イベントの處理中は他の FileChangedShell イベントは呼ばれない。

FileChangedShellPost

Vim の外部でファイルが變更されたのを檢出・對處した後。ステータスラインを更新するのに使へる。

FileEncoding

時代遲れである。まだ有效だがイベント |EncodingChanged| と同等である。

FileReadCmd

コマンド ":read" でファイルを讀み込む前。ファイルを讀み込む役目を負ふ。|Cmd-event|

FileReadPost

コマンド ":read" でファイルを讀み込んだ後。

Note:
讀み込んだテキストの先頭行と末尾行には、マーク ’[ と ’] が設定されることに注意。これは、讀み込まれた行に對して操作を行ふのに使はれる。

FileReadPre

コマンド ":read" でファイルを讀み込む前。

FileType

オプション ’filetype’ が設定されたとき。パターンはファイルタイプに對して照合される。<afile> は ’filetype’ が設定されたファイルの名前として使へる。<amatch> は ’filetype’ の新しい値として使へる。他のウィンドウもしくはバッファへの移動は許されてゐない。|filetypes| を參照。

FileWriteCmd

バッファ全體を書き込まない場合の、ファイルに書き込む前。ファイルへの書き込みの役目を負ふ。バッファを變更すべきではない。|Cmd-event|

FileWritePost

バッファ全體を書き込まない場合の、ファイルに書き込んだ後。

FileWritePre

バッファ全體を書き込まない場合の、ファイルに書き込む前。

FilterReadPost

フィルタコマンドからファイルを讀み込んだ後。Vim は FilterReadPre と同樣に、現在のバッファの名前に對してパターンを調べる。’shelltemp’ がオフの時は發生しない。

FilterReadPre

フィルタコマンドからファイルを讀み込む前。Vim は、フィルタコマンドの出力である一時ファイルの名前ではなく、現在のバッファの名前に對してパターンを調べる。’shelltemp’ がオフの時は發生しない。

FilterWritePost

フィルタコマンド用のファイルを書き込んだり、外部 diff で差分表示用のファイルを作つた後 (內部 diff については |DiffUpdated| を參照)。Vimは FilterWritePre と同樣、現在のバッファの名前に對してパターンをチェックする。’shelltemp’ がオフのときは發生しない。

FilterWritePre

フィルタコマンド用のファイルを書き込んだり、外部 diff で差分表示用のファイルを作る前。Vim はフィルタコマンドの出力である一時ファイルの名前ではなく、現在のバッファの名前に對してパターンをチェックする。’shelltemp’ がオフのときは發生しない。

FocusGained

Vim が入力フォーカスを得たとき。GUI 版と、入力フォーカスを認識できるいくつかのコンソール版でのみ有效。

FocusLost

Vim が入力フォーカスを失つたとき。GUI 版と、入力フォーカスを認識できるいくつかのコンソール版でのみ有效。ダイアログがポップアップした時に發生するかもしれない。

FuncUndefined

ユーザー定義函數が使はれたが、定義されてゐなかつたとき。必要なときのみ函數を定義するのに便利である。パターンは函數名に對して照合される。<amatch> と <afile> の兩方とも函數名に設定される。

Note:
Vim script を書くときには autoload 函數を使ふ方がよい。|autoload-functions| を參照。

GUIEnter

GUI の開始に成功し、ウィンドウを開いた後。gvim を使つたときは、VimEnter の前に發生する。ファイル .gvimrc からウィンドウの配置場所を設定するために使ふことができる。

:autocmd GUIEnter * winpos 100 50

GUIFailed

GUI の開始に失敗した後。可能ならば、Vim はターミナル內で實行を繼續する (Unix 系のみ。X サーバーへ接續が失敗したとき)。ここで Vim を終了させるには、次のやうにする:

:autocmd GUIFailed * qall

InsertChange

插入・置換モードで <Insert> をタイプしたとき。變數 |v:insertmode| が新しいモードを示す。カーソルを移動したりなどユーザーが豫期しないことは行はないやうに注意。

InsertCharPre

插入モードで文字が入力されたとき、その文字が插入される前。|v:char| 變數に入力された文字が入つてゐる。イベント內でそれを變更することで實際に插入される文字を變更できる。

|v:char| に 2 つ以上の文字を入れた場合はそのテキストはそのまま (literally) 插入される。 テキストを變更することはできない |textlock|。このイベントは ’paste’ がオンに設定されてゐるときは發行されない。

{+eval 機能が有效な場合のみ}

InsertEnter

插入モード・置換モード・假想置換モードを開始する直前。變數 |v:insertmode| がモードを示す。ユーザーが豫期しないことは行はないやうに注意。

カーソルはコマンド實行後に復元される。復元されたくない場合は |v:char| に非空文字を設定する。

InsertLeave

插入モードを拔けるとき。CTRL-O |i_CTRL-O| を使つたときにも發生する。|i_CTRL-C| のときは發生しない。

MenuPopup

(マウス右ボタンで) ポップアップメニューを表示する直前。カーソル下やマウスポインタの下にあるものによつてメニューを調整するのに便利。 パターンにはモードを表す 1 もしくは 2 文字を記述する:

n	ノーマル
v	ビジュアル
o	オペレータ實行待ち
i	插入
c	コマンドライン
tl	Terminal

OptionSet

オプションが設定された後。パターンは長い (短縮しない) オプション名に對してマッチする。|<amatch>| は對象のオプション名が設定される。

|v:option_type| はオプションの變更のスコープがグローバルかローカルかが格納される。

|v:option_command| はどのコマンドで値が設定されたかが格納される。(タグのジャンプ先にある表を參照)

|v:option_new| は新しく設定された値が格納される。

|v:option_oldlocal| は變更前のローカルの値が格納される。

|v:option_oldglobal| は變更前のグローバルの値が格納される。

|v:option_old| は變更前の値が格納される。

|v:option_oldlocal| には |:set| か |:setlocal|、|modeline| のいづれかが使用された場合に値が格納される。同樣に |v:option_oldglobal| には |:set| か |:setglobal| が使用された場合に値が格納される。

Note:
|global-local| なオプションと |:set| を利用して文字列をセットした場合、|v:option_old| には古いグローバルの値が格納されるが、それ以外の場合 (例へばローカルな文字列や |global-local| な數値等) は古いローカルの値が格納されるので注意。

OptionSet は起動時と ’key’ の變更の際にはあへてイベントが發生しないやうにしてゐる。

使用例: ’backupdir’ や ’undodir’ で指定されたディレクトリが存在してゐるかチェックし、もしなければディレクトリを作成する。

Note:
この自動コマンド中でオプションの値をリセットするのは、プラグインの擧動を破壞するため、良くない。この自動コマンドの實行は ‘:noa‘ を使ふことで抑制することができる。

自動コマンドで |:set| を使用するとき、イベントは再度引き起こされない。

OSAppearanceChanged

變數 |v:os_appearance| が變更された後。 この變更は OS が自身のアピアランスを變更、かつ Vim が GUI で動作してゐるときのみ生じます。

QuickFixCmdPre

QuickFix コマンドが實行される前 (|:make|, |:lmake|, |:grep|, |:lgrep|, |:grepadd|, |:lgrepadd|, |:vimgrep|, |:lvimgrep|, |:vimgrepadd|, |:lvimgrepadd|, |:cscope|, |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|, |:lgetfile|, |:laddfile|, |:helpgrep|, |:lhelpgrep|, |:cexpr|, |:cgetexpr|, |:caddexpr|, |:cbuffer|, |:cgetbuffer|, |:caddbuffer|)。 パターンには實行されるコマンドを記述する。|:grep| が書かれてゐると、’grepprg’ が "internal" にセットされてゐても實行される。このコマンドを使つて變數 ’makeprg’ と’grepprg’ を設定することはできない。このコマンドでエラーになると QuickFix コマンドは實行されない。

QuickFixCmdPost

QuickFixCmdPre と同樣だが、QuickFix コマンドが實行された後、最初の位置にジャンプする前に發生する。|:cfile| コマンドと |:lfile| コマンドの場合はイベントはエラーファイルを讀み込んだ後、最初のエラーに移動する前に實行される。|QuickFixCmdPost-example| を參照。

QuitPre

‘:quit‘, ‘:wq‘, ‘:qall‘ を使つたとき、カレントウィンドウを閉ぢるのか、Vim を終了するのかを決定する前に發行される。例へば、普通のウィンドウがカレントウィンドウだけだつたときに、他の餘分なウィンドウを閉ぢることができる。|ExitPre| も參照。

RemoteReply

サーバーとして働く Vim からの應答を受け取つたとき |server2client()|。パターンは {serverid} に對して照合される。<amatch> は應答が送られてきたサーバーの {serverid} になり、<afile> は應答の實際の內容になる。

Note:
これに自動コマンドを定義したときも、應答を讀み込むのには、讀み込んだ應答を處理できるやうに函數 |remote_read()| を使ふべきであることに注意。

SafeState

何も保留されてをらず、ユーザーの文字入力を待つとき。 次の場合はトリガーされない:

• オペレータ待機中
• レジスタが "r で入力された
• コマンドの實行途中
• マップの實行中
• 先行入力がある
• 插入モード補完がアクティブ
• コマンドライン補完がアクティブ

‘mode()‘ を使用して、Vim の狀態を確認できる。それは以下かもしれない:

• ビジュアルモード
• ノーマルモード
• 插入モード
• コマンドラインモード

やりたいことによつては、‘state()‘ でさらにチェックすることもできる。例へば、畫面がメッセージのためにスクロールされたかどうか。

SafeStateAgain

SafeState に似てゐるが、メッセージを處理し、コールバックを呼び出した後。これは頻繁にトリガーされる可能性があるので、時閒がかかるやうなことはしないこと。

SessionLoadPost

|:mksession| で作られたセッションファイルを讀み込んだ後。

ShellCmdPost

|:!cmd|, |:shell|, |:make|, |:grep| を使つてシェルコマンドを實行した後。變更されたファイルをチェックするのに使へる。

ShellFilterPost

":{range}!cmd", ":w !cmd", ":r !cmd" を使つてシェルコマンドを實行した後。變更されたファイルをチェックするのに使へる。

SourcePre

Vim script を讀み込む前。|:source| <afile> は讀み込まれるファイルの名前となる。

SourcePost

Vim script を讀み込んだ後。|:source| <afile> は讀み込んだファイルの名前となる。讀み込みが中斷された場合はトリガーされない。自動コマンド SourceCmd がトリガーされた後にもトリガーされる。

SourceCmd

Vim script を讀み込むとき。|:source| <afile> は讀み込まれるファイルの名前となる。この自動コマンドはこのファイルを讀み込まねばならない。|Cmd-event|

SpellFileMissing

スペルチェックファイルを讀み込まうとしたが、見つからなかつたとき。パターンは言語に對して照合される。<amatch> は言語。’encoding’ も關係する。|spell-SpellFileMissing| を參照。

StdinReadPost

標準入力からバッファへ讀み込んだ後で、モードラインを實行する前。Vim を開始したときに引數 "-" が使はれた場合のみ使はれる (|--| 參照)。

StdinReadPre

標準入力からバッファへ讀み込む前。Vim を開始したときに引數 "-" が指定された場合のみ使はれる (|--| 參照)。

SwapExists

ファイルの編輯を始めようとしてスワップファイルが存在することを檢出したとき。この狀況に對應する方法を選擇できるときだけユーザーにどうするか問ひ合はせる。 變數 |v:swapname| が見つかつたスワップファイルの名前を保持する。<afile> は編輯しようとしてゐるファイルである。|v:swapcommand| が開かれたファイルで實行するコマンドを含んでゐるかもしれない。 このコマンドは變數 |v:swapchoice| を Vim が次にどうするべきかを示す 1 文字の文字列にセットしなければならない:

’o’	讀み込み專用で開く
’e’	とにかくファイルを編輯する
’r’	復元する
’d’	スワップファイルを削除する
’q’	ファイルを編輯せずに終了する
’a’	CTRL-C を押したのと同樣に强制終了する

これが空文字列にセットされると、自動コマンド SwapExists が存在しないときと同樣にユーザーに問ひ合はせをする。 ここでは他のバッファに切り替へること、バッファ名を變更すること、ディレクトリを變更することは許可されてゐない。

{+eval 機能が有效な場合のみ}

Syntax

オプション ’syntax’ が設定されたとき。パターンは構文名に對して照合される。<afile> は ’syntax’ が設定されたファイルの名前として使へる。<amatch> は ’syntax’ の新しい値として使へる。|:syn-on| を參照。

TabClosed

タブページを閉ぢた後。

TabEnter

タブページに入つた直後 |tab-page|。WinEnter が發生した後、BufEnter が發生する前。

TabLeave

タブページを離れる直前 |tab-page|。最初に WinLeave が發生する。

TabNew

タブページが作成されたとき。|tab-page| WinEnter イベントが最初にトリガーされ、TabEnter が實行される。

TermChanged

オプション ’term’ を變更した後。色やフォント等、ターミナル依存の設定を更新するために構文定義ファイルを再讀み込みするのに便利である。讀み込まれたバッファ全てで發生する。

TerminalOpen

‘:terminal‘ もしくは |term_start()| により端末バッファが生成された直後。このイベントは、++hidden オプションによつてウィンドウなしにバッファが生成された場合でも發生する。

TerminalWinOpen

‘:terminal‘ もしくは |term_start()| により端末バッファが作成された直後。このイベントは、バッファがウィンドウと共に作成された場合にのみ發生する。端末ウィンドウのウィンドウローカルオプションの設定に使用できる。

TermResponse

|t_RV| に對する應答をターミナルから受け取つたとき。Vim 變數 |v:termresponse| の値を使つて、ターミナルのバージョンに應じた處理ができる。

Note:
このイベントは他のイベントの處理中にも發行されることがある。特に、ファイル入出力、シェルコマンドの實行、時閒の掛かる處理など。

TextChanged

ノーマルモードでカレントバッファのテキストが變更されたとき。つまり |b:changedtick| が更新されるとき。つまり |b:changedtick| が更新された後 (自動コマンド TextChanged が定義される前にそれが起こつたときも同樣)。

未處理のキー入力がまだあるとき、またはオペレータを待機してゐるときは、發生しない。

Note:
この自動イベントは ‘:noautocmd‘ を付けてもスキップできない。

Careful:
このイベントは頻繁に發生するので、ユーザーが豫期しないことや時閒のかかる處理は行はないこと。

TextChangedI

插入モードでカレントバッファのテキストが變更されたとき。ポップアップメニューが表示されてゐるときは發生しない。他は TextChanged と同じ。

TextChangedP

插入モードでカレントバッファのテキストに變更が加へられた後で、ポップアップメニューが表示されてゐる場合に限られる。さうでなければ TextChanged と同じ。

TextYankPost

カレントバッファでテキストがヤンクもしくは削除された後。|v:event| の以下の値は、この autocmd を發生させた操作を特定するのに使用できる:

operator	オペレーションが實行された。
regcontents	行のリストとしてレジスタに格納されたテキスト、例: getreg(r, 1, 1)
regname	|register| の名前、もしくは無名レジスタの場合は空文字列。
regtype	レジスタの種類。|getregtype()| を參照

|quote_| が使用された場合、もしくは再歸的に呼び出された場合には發生しない。バッファのテキストを變更することは許されてゐない、|textlock| を參照。

{+eval 機能付きでコンパイルされた場合のみ有效}

User

自動的に實行されることはない。コマンド ":doautocmd" によつてのみ實行される自動コマンドのために使用される。

Note:
該當する自動コマンドが存在しないときに ‘:doautocmd User MyEvent‘ が使用された場合、エラーが發生する。これを囘避したい場合、ダミーの自動コマンドを自身で定義すること。

UserGettingBored

ユーザーが同じキーを 42 回押したとき。ただの冗談！ :-)

VimEnter

ファイル .vimrc の讀み込みを含む、全てのスタートアップ處理を行ひ、"-c cmd" の引數を實行し、全てのウィンドウを構築し、それらにバッファを讀み込んだ後。 このイベントがトリガーされる直前に、|v:vim_did_enter| 變數が設定されてゐるので、以下のことができる:

if v:vim_did_enter
  call s:init()
else
  au VimEnter * call s:init()
endif

VimLeave

Vim を終了する前で、ファイル .viminfo を書き込んだ後。VimLeavePre のやうに、ただ 1 度だけ實行される。異常終了の檢出には |v:dying| を使ふこと。終了時に v:dying が 2 以上のときはこのイベントは發生しない。

VimLeavePre

Vim を終了する前で、ファイル .viminfo を書き込む直前。これは終了時にたまたまカレントバッファになつたバッファの名前とマッチしたときに、ただ 1 度だけ實行される。 大抵、パターンには "*" を使ふと便利である。

:autocmd VimLeavePre * call CleanupStuff()

異常終了の檢出には |v:dying| を使ふこと。終了時に v:dying が 2 以上のときはこのイベントは發生しない。

VimResized

Vim ウィンドウのサイズが變はつたとき。よつて ’lines’ と ’columns’ が變更される。しかし開始時には發生しない。

WinEnter

別のウィンドウに入つた後。Vim の開始直後、1 個目のウィンドウに入つたときは發生しない。ウィンドウの高さを設定するのに便利である。そのウィンドウで他のバッファを開いてゐたときは、イベント WinEnter の後に BufEnter が發生する。

Note:
split と tabpage コマンドに關しては、WinEnter イベントが發生するのは分割もしくはタブコマンドの後だが、ファイルが讀み込まれる前であることに注意。

WinLeave

ウィンドウを離れる前。次に入るウィンドウで他のバッファを開いてゐたときは、イベント WinLeave の前に BufLeave が發生する (ただし ":new" を使つたときはさうならない)。":qa" や "q" で Vim を終了するときには發生しない。

WinNew

新しいウィンドウが作成されたとき。Vim がちやうど開始したとき、最初のウィンドウのためには行はれない。WinEnter イベントの前。

6. パターン

引數 {pat} にはコンマ區切りのリストを指定することができる。これによりコマンドは指定されたそれぞれのパターンについて實行される。例へばこのコマンド:

:autocmd BufRead *.txt,*.info set et

は下記と等しくなる:

:autocmd BufRead *.txt set et
:autocmd BufRead *.info set et

ファイルパターン {pat} がファイル名とマッチするかどうかは、2 通りの方法で調べられる。

1. パターンに ’/’ が含まれないとき: Vim はファイル名の後ろの部分からのみマッチを調べる (ファイル名の前につくディレクトリパスは除く)。
2. パターンに ’/’ が含まれるとき: Vim は短いファイル名 (ユーザーが打ち込んだもの) と長いファイル名 (短いファイル名をフルパスに展開し、シンボリックリンクならその實體を探したもの) との兩方から一致を調べる。

特殊なパターン <buffer> または <buffer=N> はバッファローカルな自動コマンド |autocmd-buflocal| で使はれる。このパターンはバッファの名前に對してはマッチしない。

例:

:autocmd BufRead *.txt          set et

全てのテキストファイルに對しオプション ’expandtab’ をオンにする。

:autocmd BufRead /vim/src/*.c	set cindent

ディレクトリ /vim/src 內の C 言語ファイルに對しオプション ’cindent’ をオンにする。

:autocmd BufRead /tmp/*.c       set ts=5

"/tmp/test.c" から "/home/nobody/vim/src/test.c" にリンクを張つてゐると、"/tmp/test.c" の編輯を始めたとき、この自動コマンドは實行される。

Note:
パスの途中だけにマッチさせ、ルートディレクトリにマッチさせたくないときは、最初の1文字目に ’*’ を使ふ。例:

:autocmd BufRead */doc/*.txt    set tw=78

この自動コマンドは、例へば "/tmp/doc/xx.txt" や "/usr/home/piet/doc/yy.txt" にマッチする。ここで、ディレクトリの深さは關係ない。

パターンがマッチするファイル名は、ワイルドカードを展開した後のものである。そのため、次のコマンドを實行すると

:e $ROOTDIR/main.$EXT

まずコマンドの引數は、ファイル名が自動コマンドのパターンにマッチする前に、次のやうに展開される。

/usr/root/main.py

イベント FileReadCmd 等を使ふときにはこれに注意すること。<amatch> の値が、ユーザーの豫期するものと違ふかもしれない。

パターンの中で環境變數を使ふこともできる。

:autocmd BufRead $VIMRUNTIME/doc/*.txt  set expandtab

環境變數 $HOME が定義されてゐるなら、~ をホームディレクトリとして使ふこともできる。

:autocmd BufWritePost ~/.vimrc   so ~/.vimrc
:autocmd BufRead ~archive/*      set readonly

環境變數は、自動コマンドが定義されるときに展開される。自動コマンドが實行されるときではない。これは command とは違つてゐる！

パターンの解釋方法は、ファイル名の解釋方法と大體同じである。

Note:
’/’ といふ文字は、全てのシステムでパスの區切り文字に使はれることに注意すること (MS-DOS と OS/2 でさへも)。これは、パターン內でバックスラッシュを使ふことが難しい上に、別々のシステムでも自動コマンドが動作するやうにするためである。

|pattern| を使ふことができる。上記の飜譯が行はれてゐるため、期待通りに機能しない可能性がある。

パターンマッチの檢索は、イベントの發生時に行はれる。自動コマンドのどれかでバッファ名を變更しても、それどころかバッファを削除しても、實行される 自動コマンドは變はらない。例:

au BufEnter *.foo  bdel
au BufEnter *.foo  set modified

これはカレントバッファを削除し、代はりにカレントバッファになつたバッファ內でオプション ’modified’ をオンにする。Vim は "*.foo" が新しいカレントバッファのバッファ名にマッチしなくとも氣にしない。"*.foo" はイベントが發生した時點でのバッファ名にマッチする。

しかし、|:bwipe| でワイプアウトされたバッファに對しては、バッファローカルな自動コマンドは實行されない。|:bdel| で削除されたバッファは實際にはまだ存在してゐる (リストされなくなつただけ) なので、自動コマンドは實行される。

7. バッファローカルな自動コマンド

バッファローカルな自動コマンドは特定のバッファに結びつけられてゐる。これは名前を持たないバッファや特定のパターンにマッチしない名前のバッファに使ふと便利である。しかしそれぞれのバッファに明示的に追加する必要がある。

バッファローカルな自動コマンドはパターンの代はりに以下の形式のどれかを使ふ:

例:

:au CursorHold <buffer>  echo 'hold'
:au CursorHold <buffer=33>  echo 'hold'
:au BufNewFile * au CursorHold <buffer=abuf>  echo 'hold'

自動コマンドに對するコマンドは全てバッファローカルな自動コマンドに對しても機能する。パターンの代はりに特別な文字列を使ふ。例:

Note:
カレントバッファに對して自動コマンドを定義するとき、それがバッファ番號とともに保存されることに注意。つまりカレントバッファ番號が 12 なら "<buffer=12>" といふ形になる。例へば自動コマンドをリストするときこの形式で表示される。

バッファローカル自動コマンドが存在するかを判定するには函數 |exists()| を次のやうに使ふ:

:if exists("#CursorHold#<buffer=12>") | ... | endif
:if exists("#CursorHold#<buffer>") | ... | endif    " for current buffer

バッファがワイプアウトされると當然バッファローカル自動コマンドも失はれる。":bdel" などでバッファを削除するときは、それがリストからなくなるだけで、自動コマンドはまだ存在してゐることに注意。バッファローカル自動コマンドの削除を表示させるにはかうする:

:set verbose=6

存在しないバッファに對してバッファローカル自動コマンドを定義することはできない。

8. グループ

自動コマンドはグループにまとめることができる。これは一聯の自動コマンドを取り除いたり實行したりする際に便利である。例へば、構文强調表示のための全ての自動コマンドはグループ "highlight" に入つてゐて、GUIの 開始時に ":doautoall highlight BufRead" で實行できる。

特定のグループが選擇されないとき、既定のグループが使はれる。既定のグループには名前がない。既定のグループから個別に自動コマンドを實行することはできない。それらを實行できるのは、全てのグループに對する自動コマンドを實行するときのみである。

普通、自動コマンドを自動的に實行するときは、全てのグループに對する 自動コマンドが使はれる。グループが問題になつてくるのは、":doautocmd" や ":doautoall" によつて自動コマンドを實行するときと、自動コマンドを定義したり削除するときである。

グループ名には空白を除く全ての文字が使へる。"end" といふグループ名は豫約語になつてゐる (大文字も)。

グループ名では大文字と小文字を區別して扱ふ。イベントの名前とは違ふことに注意すること。

:aug[roup] {name}

後に續くコマンド ":autocmd" のためのグループ名を定義する。{name} を "end" や "END" にすると既定のグループが選ばれる。混亂を避けるため、既存の {event} の名前とは違ふ名前をつけるべきである。これはたいてい意圖しない動作を引き起こす。

:aug[roup]! {name}

自動コマンドのグループ {name} を削除する。そのグループを使つてゐる自動コマンドがまだあるなら、これは使はないこと！その點はチェックされない。とにかくそれをしたら、警告が表示される。グループが現在のグループの場合、エラー E936 が表示される。

特定のグループとして自動コマンドを定義するには、次の手順に從ふこと。

1. ":augroup {name}" によつてグループを選擇する。
2. ":au!" によつて古い自動コマンドを全て消去する。
3. 自動コマンドを定義する。
4. ":augroup END" によつて既定のグループに戾る。

例:

:augroup uncompress
:  au!
:  au BufEnter *.gz     %!gunzip
:augroup END

これで自動コマンドを (例へばファイル .vimrc を再び讀み込んだ後) 2 回定義することが防げる。

9. 自動コマンドの實行

自動コマンドは「自動的」でなくとも實行できる。これはあなたが自動コマンドを變更したときや、閒違つた自動コマンドが實行されたとき (つまりファイルパターンのマッチングが閒違つてゐたとき) に便利である。

Note:
オプション ’eventignore’ はここにも適用されることに注意。ここに列擧されたイベントでは、どんな自動コマンドも實行されない。

:do[autocmd] [<nomodeline>] [group] {event} [fname]

[fname] (省略するとカレントファイルの名前) にマッチする、{event} のための自動コマンドをカレントバッファに適用する。カレントファイル名が正しいファイルパターンにマッチしないときや設定を變へた後、またはあるイベントのために自動コマンドを實行するために使用できる。 これを自動コマンドの內部で實行することも可能である。だから、ある擴張子用の自動コマンドを元にして別の擴張子用のものを作ることができる。例:

:au BufEnter *.cpp so ~/.vimrc_cpp
:au BufEnter *.cpp doau BufEnter x.c

無限の循環に陷らないよう注意すること。また |autocmd-nested| を參照すること。

引數 [group] が省かれると、全てのグループの自動コマンドが實行される。[group] が指定されると、それにマッチするグループの自動コマンドのみが實行される。

Note:
定義されてゐないグループ名を使ふと、エラーメッセージが表示される。

自動コマンドを適用した後にモードラインが處理される。ファイルを編輯するときと同じやうに、自動コマンドでなされた設定を上書きするためである。<nomodeline> が指定されてゐる場合はモードラインは處理されない。バッファのロード以外で使はれるイベント (例へば |User|) などは <nomodeline> を指定したはうがよいかもしれない。一致する自動コマンドが實行されなかつた場合も、モードラインの處理はスキップされる。

:doautoa[ll] [<nomodeline>] [group] {event} [fname]

":doautocmd" と似てゐるが、讀み込まれたバッファそれぞれに自動コマンドを適用する。[fname] は自動コマンドを選擇するのに使はれる。コマンドを適用するバッファではない。{譯注: |:autocmd| の {pat} に使ふ？}

Note:
このコマンドで、バッファを削除したり、バッファを變へたり、バッファの內容を變へるやうな自動コマンドを實行しないこと。結果は豫期できない。このコマンドは、オプションを設定したり、構文强調表示を變へたりする自動コマンドのためのものである。

10. 自動コマンドを使ふ

「ファイルの書き込み」には、4 組のイベントが起こりうる。1 回の書き込みコマンドでは、これらのうち 1 組しか使はれない。

"*Cmd" にマッチする自動コマンドがあるときは、それが書き込み作業を行ふものと想定される。書き込みはそれ以上行はれず、他のイベントも發生しない。|Cmd-event|

Note:
イベント *WritePost による自動コマンドは、イベント *WritePre による自動コマンドの引き起こしたバッファに對する變化を、どのやうなものでもアンドゥすべきであることに注意。さもないと、ファイルの書き込みがバッファを變更するといふ副作用を持つてしまふ。

あるバッファの中の行をファイルに書き込むとき、自動コマンドを實行する前にそのバッファが一時的にカレントバッファになる。自動コマンドがカレントバッファを變更したり、元のカレントバッファを消去しない限り、カレントバッファは再び元に戾る。

イベント *WritePre や *AppendPre による自動コマンドは、書き込み元のバッファを削除してはならない。

マーク ’[ と ’] は特別な位置を記憶してゐる。

• イベント *ReadPre の前に、新しい行が插入される所の上の行にマーク ’[ が設定される。
• イベント *ReadPost の前に、讀み込まれた最初の行にマーク ’[ が、最後の行にマーク ’] が設定される。
• イベント *WriteCmd, *WritePre と *AppendPre による自動コマンドが實行される前に、書き込まれる最初の行にマーク ’[ が、最後の行にマーク ’] が設定される。

Careful:
バッファを變更するコマンドを使ふと、’[ と ’] の場所も變更される。

ファイル名を必要とするコマンドでは、讀み込まれるファイル名に "<afile>" を使ふことができる (カレントファイル名に "%" を使ふこともできる) |:<afile>|。現在有效なバッファ番號には "<abuf>" を使ふことができる。これは名前を持たないバッファに對しても有效だが、バッファを持たないファイルには使へない (例へば、":r file" で讀み込まれたファイル)。

壓縮されたファイルを讀み書きする例:

:augroup gzip
:  autocmd!
:  autocmd BufReadPre,FileReadPre     *.gz set bin
:  autocmd BufReadPost,FileReadPost   *.gz '[,']!gunzip
:  autocmd BufReadPost,FileReadPost   *.gz set nobin
:  autocmd BufReadPost,FileReadPost   *.gz execute ":doautocmd BufReadPost " . expand("%:r")
:  autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
:  autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r

:  autocmd FileAppendPre              *.gz !gunzip <afile>
:  autocmd FileAppendPre              *.gz !mv <afile>:r <afile>
:  autocmd FileAppendPost             *.gz !mv <afile> <afile>:r
:  autocmd FileAppendPost             *.gz !gzip <afile>:r
:augroup END

グループ "gzip" は、":autocmd!" で既存の自動コマンドを全て削除できるやうにするために使はれてゐる。これはスクリプトファイルが 2 囘讀み込まれたときのためである。

("<afile>:r" は擴張子のないファイル名である。|:_%:| を參照)

イベント BufNewFile, BufRead/BufReadPost, BufWritePost, FileAppendPost, VimLeave によつて實行された自動コマンドは、バッファの被修正フラグを切り替へない。BufReadPost による自動コマンドで、壓縮されてゐるバッファを解凍したときは、":q" で Vim を終了することができる。BufWritePre による自動コマンドの起こした變更を戾すために BufWritePost で ":undo" を使つたときも、":q" を使ふことができる ("ZZ" も可)。バッファが變更されたことにしたいなら、":set modified" とすること。

自動コマンドからノーマルモードのコマンドを實行したいときは、コマンド ":normal" を使ふこと。使ふときは注意！ノーマルモードのコマンドが完結してゐないと、ユーザーが文字を打ち込まないといけない (例へば、":normal m" の後にはマーク名を打ち込まないといけない)。

バッファの內容を變更した後に、變更されてゐないことにしたいなら、オプション ’modified’ をオフにすること。かうすると ":q!" ではなく ":q" でも Vim を終了できる。

既定では、自動コマンドはネストしない (入れ子にならない)。例へば、自動コマンド內で ":e" や ":w" を使つても、これらに對してはイベント BufRead や BufWrite による自動コマンドは實行されない。もしこれを實行してほしいなら、ネストしてほしいコマンド內でフラグ "nested" を使ふこと。例:

:autocmd FileChangedShell *.c ++nested e!

再歸的ループを避けるために、ネストは 10 段階までに制限されてゐる。

自動コマンドの中でコマンド ":au" を使ふこともできる。これは自己修正的 {譯注: 原文 "self-modifying"} なコマンドになりうる！これは 1 回だけ實行すべき自動コマンドに便利である。

あるコマンドを實行するときだけ自動コマンドをスキップしたい場合は、修飾子 |:noautocmd| を使ふかオプション ’eventignore’ を使ふ。

Note:
(":read file" やフィルタコマンドで) 讀み込んだファイルの最後の行に <EOL> がないとき、Vim はこのことを記憶する。その次の (":write file" やフィルタコマンドでの) 書き込みで、先ほどの最後の行が再び最後の行として書き込まれ、かつオプション ’binary’ がオンになつてゐると、<EOL> は付け足されない。

これにより、讀み込まれた行に對するフィルタコマンドで、讀み込まれた通りに書き出すことができる。また、フィルタ處理された行に對する書き込みのコマンドで、フィルタが出力した通りに書き出すことができる。例へば、壓縮されたファイルを書き込むもう 1 つの例は以下のやうになる。

:autocmd FileWritePre *.gz   set bin|'[,']!gzip
:autocmd FileWritePost *.gz  undo|set nobin

コンマで區切られた複數のパターンを指定することもできる。以下にいくつか例を擧げる。

:autocmd BufRead   *          set tw=79 nocin ic infercase fo=2croq
:autocmd BufRead   .letter    set tw=72 fo=2tcrq
:autocmd BufEnter  .letter    set dict=/usr/lib/dict/words
:autocmd BufLeave  .letter    set dict=
:autocmd BufRead,BufNewFile   *.c,*.h set tw=0 cin noic
:autocmd BufEnter  *.c,*.h    abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
:autocmd BufLeave  *.c,*.h    unabbr FOR

Makefile (makefile, Makefile, imakefile, makefile.unix 等) にマッチさせるにはかうする。

:autocmd BufEnter  ?akefile*	set include=^s\=include
:autocmd BufLeave  ?akefile*	set include&

C ソースファイルを編輯するとき、常に最初の函數から始めるにはかうする。

:autocmd BufRead   *.c,*.h      1;/^{

上の "1;" がないと、檢索が始まる場所はファイルの最初ではなく、ファイルの插入された場所になる。

新しいファイルを作るときにスケルトン (テンプレート) ファイルを讀み込むにはかうする。

:autocmd BufNewFile  *.c      0r ~/vim/skeleton.c
:autocmd BufNewFile  *.h      0r ~/vim/skeleton.h
:autocmd BufNewFile  *.java   0r ~/vim/skeleton.java

HTML ファイルを書き込むときに現在の日附と時刻を插入したいならかうする {譯注: KoRoN 氏作成の autodate.vim を使つた方がよい}

:autocmd BufWritePre,FileWritePre *.html   ks|call LastMod()|'s
:fun LastMod()
:  if line("$") > 20
:    let l = 20
:  else
:    let l = line("$")
:  endif
:  exe "1," . l . "g/Last modified: /s/Last modified: .*/Last modified: " .
:  \ strftime("%Y %b %d")
:endfun

これを機能させるためには、ファイルの先頭から 20 行以內に "Last modified: <date time>" といふ行を入れる必要がある。Vim は <date time> (とその行內のそれ以後を) を現在の日附と時刻に置き換へる。說明:

函數 LastMod() はファイルの長さが20行以下であるかを調べ、キーワード "Last modified: " の含まれる行を探すためにコマンド ":g" を實行する。キーワードの含まれる行に對しては ":s" が實行され、既存の日附を現在のものに置き換へる。":execute" は ":g" や ":s" で expression を使へるやうにするためのものである。日附は函數 strftime() から得られる。strftime() の引數を變更して、別の形の日附を得ることもできる。

コマンドラインから自動コマンドを入力すると、(<Tab> や CTRL-D などで) イベントとコマンド名が適切に補完される。

Vim はマッチする全ての自動コマンドをユーザーの指定した順に實行する。ユーザーが實行させる最初の自動コマンドにはファイルパターンに "*" を使ひ、全てのファイルに適用されるやうにするとよい。これはつまり、あらゆる設定のための既定を好きなやうに定義することができ、もしマッチする自動コマンドが別にあれば、そちらの方が設定を上書きできるといふことである。しかしマッチする自動コマンドが他になければ、少なくともあなたの設定した既定は恢復される (もし自動コマンドがマッチした別のファイルから、マッチしなかつたファイルに移つても)。

Note:
Unix のシェルと違ひ、"*" は "." で始まるファイルにもマッチすることに注意。

自動コマンドは現在の檢索パターンを變更しない。Vim は自動コマンドの實行前に現在の檢索パターンを保存し、自動コマンドが終了してから復元する。つまり自動コマンドはオプション ’hlsearch’ で强調表示されてゐる文字列に影響しないといふことである。自動コマンド內でも、例へばコマンド "n" 等で、檢索パターンは普通に使用できる。 もし自動コマンドの中で終了後に使ふ檢索パターンを設定したいなら、":let =" とすること。自動コマンドの中で ":nohlsearch" を使つて、檢索語の强調表示を無效にすることはできない。Vim の開始時に檢索語の强調表示を行はないためには、’viminfo’ のフラグ ’h’ を使ふこと。

イベント "*Cmd" のうちどれかを使ふと、それによる自動コマンドが讀み込み、書き込み、または source を行ふものと想定される。これは特殊なファイル、例へばリモートシステム上のファイルに作業をするときに使へる。

Careful:
これらのイベントを誤つた方法で使ふと、そのイベントが發生するファイルの讀み書きが不可能になつてしまふ。自分の自動コマンドをしつかりテストすること。最良の方法は、普通のファイル名には決してマッチしないパターン (例へば "ftp://*") を使ふことである。

BufReadCmd に對して自動コマンドを定義すると、クラッシュしたセッションの復舊が難しくなる。元のファイルから復舊するとき、Vim はスワップファイル內に見つからなかつた部分のみを讀み込む。それは BufReadCmd の自動コマンドを使つたときは不可能なので、コマンド |:preserve| を使つて元のファイルが復舊に必要ないやうにすること。さうするのはファイルが變更を受けたと判斷したときのみでもよい。

讀み込みと書き込みのコマンドの場合、Vim 變數 |v:cmdarg| は引數 "++enc=" と "++ff=" の、有效だつたものを保持してゐる。これらはファイルを讀み書きするコマンドで使はれるべきである。Vim 變數 |v:cmdbang| はコマンドに "!" が使はれたときに 1、さうでないときに 0 が設定される。

例は標準プラグイン $VIMRUNTIME/plugin/netrwPlugin.vim を參照。

11. 自動コマンドを無效にする

一時的に自動コマンドを無效にするにはオプション ’eventignore’ を使ふ。これは豫期しない振るまいを引き起こす可能性がある。|:finally| つきの |:try| ブロックを使つて後で ’eventignore’ を元に戾すやうにすること。

1 つのコマンドを實行する閒だけ自動コマンドを無效にするには修飾子 ":noautocmd" を使ふ。これは後に續くコマンドを實行する閒だけ、’eventignore’ を "all" にセットする。例:

:noautocmd w fname.gz

これは gzip プラグインで定義された自動コマンドを發生させずにファイルを書き込む。

Note:
處理の最中ではなく、終はつた後で呼び出される自動コマンドもある。特に |CursorMoved| や |TextChanged| があてはまる。