キーマップと短縮入力

*map.txt*       For Vim バージョン 8.1.  Last change: 2019 Nov 09


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

キーマップ、短縮入力、ユーザー定義コマンドについて。

ユーザーマニュアルの |05.3|, |24.7|, |40.1| でこの機能について紹介してゐます。

1. マップ (Key mapping)

マップは入力キーの動作を變更するために使はれます。一般的にはファンクションキーにコマンドを割り當てるのに使はれます。例:

:map <F2> a<C-R>=strftime("%c")<CR><Esc>

このマップはカーソルの位置に現在の日時を插入します。(<F2> などは |<>| 表記法を參照)

1.1 マップコマンド

マップを新しく作成、削除、一覽表示するコマンドがあります。マップコマンドの種類とモードの關係については |map-overview| を參照してください。

マップコマンドを使ふと、單キーまたは複數キーの入力を別の文字列にマップできます。ファンクションキーにコマンド列を割り當てたり、あるキーを別のキーに變換したりできます。マップを保存、復元する方法については |:mkexrc| を參照してください。

2 つのマップがあつて、兩方とも同じ文字で始まつてゐる場合、どちらを使用するかがあゐまいになつてしまひます。例:

:imap aa foo
:imap aaa bar

"aa" と入力したとき、"aa" と "aaa" のどちらを使用するかを決定するためには、次の文字が必要になります。そのため、"aa" が入力された時點ではまだマップは適用されず、次の入力まで待機狀態になります。例へば空白文字を入力すれば "foo" と空白文字が插入されます。"a" を入力すれば "bar" が插入されます。

1.2 特別な引數

引數に "<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>", "<unique>" を指定できます。マップコマンドの直後 (他の引數の前) に置いてくださ い。

カレントバッファだけで使用できるマップを作成するには、マップコマンドの引數に "<buffer>" を指定します。例:

:map <buffer>  ,w  /[.,;]<CR>

この場合、他のバッファで、",w" に對して別の操作を割り當てることができます:

:map <buffer>  ,w  /[#&!]<CR>

バッファローカルなマップは通常のマップよりも優先して使用されます。長いグローバルなマップが存在する場合に短いローカルなマップが影響を受けないやうにするには下記の <nowait> を參照して下さい。

"<buffer>" はマップを削除するときにも指定できます:

:unmap <buffer> ,w
:mapclear <buffer>

バッファローカルなマップはそのバッファが削除されるときにいつしよに消去されます。アンロード(|:bunload|)では消去されません。ローカルオプションと同じです。また、|map-precedence| を參照して下さい。

"," にバッファローカルなマップを定義する場合に "," から始まるグローバルなマップがあるかもしれません。その場合は Vim が "," のマップか、あるいはより長いマップを使用するかどうか知るために別の文字を入力する必要があります。これを避けるには引數に <nowait> を追加します。そしてそのマップは一致する場合に使用され、Vim はそれ以上入力される文字を待ちません。しかし、既に文字が入力されてゐた場合はそれが使はれます。

實行するコマンドがコマンドラインに表示されないやうにするには、マップコマンドの引數に "<silent>" を指定します。例:

:map <silent> ,h /Header<CR>

このマップを使用するとき、檢索文字列はコマンドラインに表示されません。しかし、實行されたコマンドが出力するメッセージは表示されてしまひます。それを靜かにさせるには ":silent" を使ひます。

:map <silent> ,h :exe ":silent normal /Header\r"<CR>

それでもまだ、例へば inputdialog() のプロンプトなどは表示されます。"<silent>" は短縮入力にも使へますが、コマンドラインで使ふと正しく表示されなくなります。

マップや短縮入力を定義するときに "<script>" 引數を指定すると、{rhs} の中の "<SID>" で始まるスクリプトローカルなマップだけが再マップされます。別の場所でマップが定義されてゐても (例へば mswin.vim で CTRL-V にマップが定義されてゐても)、その影響を避けることができます。その場合でも同じスクリプトで定義されたマップは使ふことができます。

Note:
":map <script>" と ":noremap <script>" の動作は同じです。コマンド名より "<script>" の效果が優先されます。再マップが制限されることが明確になるため ":noremap <script>" を使ふ方がいいでせう。

マップや短縮入力を定義するときに "<unique>" 引數を指定すると、同じ名前のものがすでに定義されてゐた場合に、コマンドは失敗します。例:

:map <unique> ,w  /[#&!]<CR>

バッファローカルのマップを定義するときは、通常のマップも檢査の對象となります。失敗する例:

:map ,w  /[#&!]<CR>
:map <buffer> <unique> ,w  /[.,;]<CR>

すでにマップされてゐる機能をそのままに、新たにマップを設定したい場合は、|maparg()| を參照してください。

マップや短縮入力を定義するときに "<expr>" 引數を指定すると、引數が式 (スクリプト) として扱はれます。マップが實行されたときに、式が評價され、その値が {rhs} として使はれます。例:

:inoremap <expr> . InsertDot()

InsertDot() 函數の戾り値が插入されます。カーソルの前のテキストをチェックして、ある條件に一致するなら omni 補完を開始する、といふやうなことができます。

短縮入力では、入力されて短縮入力展開のトリガーとなつた文字が |v:char| にセットされます。これを使つて {lhs} の展開方法を決めることもできます。自分で v:char を插入したり變更したりすべきではありません。

副作用に注意してください。式は文字の取得中に評價されるため、簡單に異常動作を起こせてしまひます。そのため、次のものは制限されます:

• バッファのテキストの變更 |textlock|。
• 他のバッファの編輯。
• |:normal| コマンド。
• カーソルの移動は可能ですが、後で元に戾されます。

以上のことを實現したい場合は、そのためのコマンド文字列を返してください。

getchar() が使用できます。先行入力があればそれが消費されます。例へば次のやうなマップを定義します:

inoremap <expr> <C-L> nr2char(getchar())
inoremap <expr> <C-L>x "foo"

そして CTRL-L を押してみます。すぐには何も起きません。どのマップを使ふかを決定するためには文字がもう 1 つ必要です。次に ’x’ を押すと後者のマップが使はれ、"foo" が插入されます。他のキーを押すと前者のマップが使はれ、その文字が getchar() によつて取得され、返されます。

例を示します。リスト番號を自動的に增加させつつ插入します:

let counter = 0
inoremap <expr> <C-L> ListItem()
inoremap <expr> <C-R> ListReset()

func ListItem()
  let g:counter += 1
  return g:counter . '. '
endfunc

func ListReset()
  let g:counter = 0
  return ''
endfunc

CTRL-L で次の番號を插入し、CTRL-R で番號をリセットします。CTRL-R は空文字列を返すので、何も插入されません。

Note:
特殊キーが機能するやうにしたり、テキスト中の CSI バイトをエスケープしたりするために、特別な處理が行はれてゐます。|:map| コマンドも同樣の處理を行ふので、それが二重に實行されるのを防ぐ必要があります。次のものは機能しません:

:imap <expr> <F3> "<Char-0x611B>"

なぜなら、<Char- で表記した文字 (あるいは本物の文字) のバイト列は |:imap| コマンドが解釋されるときにエスケープされ、<expr> で使はれるときにもう一度エスケープされるからです。次のものは機能します:

:imap <expr> <F3> "\u611B"

テキストの末尾以外で 0x80 をシングルバイトとして使つた場合、それは機能しません。特殊キーとして認識されます。

1.3 マップとモード

マップには 6 つの種類があります。

• ノーマルモード: ノーマルモードのコマンドを入力するとき。
• ビジュアルモード: ビジュアルモードのコマンドを入力するとき。
• 選擇モード: ビジュアルモードに似てゐますが入力したテキストによつて選擇範圍が置換されます。
• オペレータ待機モード: オペレータを待機してゐるとき。("d"、"y"、"c"、などの後)。|omap-info| 參照。
• 插入モード: 置換モードでも使はれます。
• コマンドラインモード: ":" もしくは "/" コマンドを入力したとき。

例外として、ノーマルモードでカウント (コマンドの繰り返し回數) を入力してゐるときは、0 (ゼロ) に對するマップは適用されません。これは 0 がマップされてゐても、カウントの指定でゼロを入力できるやうにするためです。

マップコマンドとモードの對應表。詳細は以後に。

{譯注: Lang-Arg については |language-mapping| を參照}

:nunmap は修道院の外でも使へます。{譯注: nunは修道女の意}

いくつかのコマンドはビジュアルモードと選擇モードの兩方で機能しますが、さうでないコマンドもあります。「ビジュアル」といふ言葉がビジュアルモードと選擇モードの兩方を指してゐる場合が多々あるので注意してください。|Select-mode-mapping|

Note:
選擇モードで印字可能文字にマップを定義するとユーザーの混亂を招くかもしれません。印字可能文字に對しては明示的に :xmap と :smap を使ひ分けるのがいいでせう。マップを定義したあとで :sunmap を使ふ方法もあります。

一部のコマンドは、插入モードとコマンドラインモードの兩方で使へますが、一部はさうではありません:

{譯注: Lang-Arg については |language-mapping| を參照}

もしも ’iminsert’ が 1 なら、下記の |language-mapping| を參照してください。

オリジナルの Vi はノーマルモード、ビジュアルモード、オペレータ待機モード、でひとまとまり、插入モード、コマンドラインモード、でさらにひとまとまりのマップを持ち、それぞれ區別されてゐませんでした。そのため、Vim の ":map" と ":map!" コマンドは複數のモードに對してマップを設定したり表示したりします。Vim では ":nmap", ":vmap", ":omap", ":cmap", ":imap" を使ひ分けることで、それぞれのモード別にマップを設定することができます。

ターミナルマップは、ターミナルウィンドウの中で動作してゐるジョブに對してキーが入力されたときに機能します。|terminal-typing| を參照してください。

オペレータ待機マップを使ふと、移動コマンドを定義できます。そして、オペレータと組み合はせて使ふことができます。簡單な例:

:omap { w

これを定義した場合、"y{" が "yw" として、"d{" が "dw" として機能するやうになります。

マップ適用時のカーソル位置を無視し、異なるテキストを選擇するには、omap 內でビジュアルモードを開始して對象となるテキストを選擇してください。例へば、現在行の函數名を選擇するには次のやうにします:

onoremap <silent> F :<C-U>normal! 0f(hviw<CR>

CTRL-U (<C-U>) を使つて (Vim によつて插入される) 範圍指定を削除してゐます。ノーマルモードコマンドを使つて、最初の ’(’ 文字を探し、その前にある單語を選擇します。通常はこれで函數名を選擇できるでせう。

あるマップをノーマルモードとビジュアルモードで使用し、そして、オペレータ待機モードでは使用しないといふ場合は、3 つのモードに對してマップを定義してからオペレータ待機モードのマップだけを削除します:

:map	xx something-difficult
:ounmap xx

ビジュアルモードとオペレータ待機モードの場合や、ノーマルモードとオペレータ待機モードの場合も同樣にします。

":lmap" で定義したマップ(以下、言語マップ)は次の場面で利用できます:

• 插入モード
• コマンドラインモード
• 檢索パターンを入力するとき
• "r" や "f" などのコマンドに續いて文字を入力するとき
• input() の入力

大まかに說明すると、Vim コマンドとしてではなく、テキストの一部として入力するやうなときにはいつでも利用できます。"Lang-Arg" は別個のモードではなく、そのやうな場面の總稱です。

ある言語用の言語マップをロードするには、オプション ’keymap’ を設定するのが簡單です。|45.5|を參照してください。

插入モードとコマンドラインモードでは CTRL-^ で言語マップの使用の有無を切り替へることができます |i_CTRL-^| |c_CTRL-^|。これらのコマンドは ’iminsert’ オプションの値を變更します。(檢索パターンの入力ではなく) コマンドラインに入力するときには CTRL-^ で切り替へるまで言語マップは無效になつてゐます。插入モードと檢索パターンでの使用狀態は別々に記錄されます。插入モードの使用狀態は "f" や "t" などのコマンドで文字を入力するときにも使用されます。

言語マップは、既にマップが適用された文字には適用されません。言語マップは入力された文字に對してのみ使用されます。これは、言語マップは文字が入力されたときに適用されたはずといふ想定によるものです。

1.4 マップの一覽表示

マップを一覽表示したときの行頭の 2 文字は使用できるモードを表してゐます:

{譯注: Lang-Arg については |language-mapping| を參照}

{rhs} の直前に特殊な文字が表示されてゐるものは次のことを意味します:

{lhs} の後ろの最初の非空白文字から行末 (もしくは ’|’) までのすべての文字は {rhs} の一部です。そのため {rhs} の末尾を空白文字にすることができます。

Note:
ビジュアルモードのマップでは "’<" マークが使へます。これはカレントバッファで選擇されてゐた範圍の開始位置を示してゐます |'<|。

何がマッピングされてゐるか調べるのに |:filter| コマンドを使ふことができます。パターンは {lhs} と {rhs} に對しては、生の形式で (譯注: 實際のキャラクターコードを用ゐて)マッチします。

’verbose’ がゼロ以外のときにマップ一覽を表示すると、どこで定義されたのかも表示されます。例:

:verbose map <C-W>*

n  <C-W>*      * <C-W><C-S>*
        Last set from /home/abcd/.vimrc

詳しくは |:verbose-cmd| を參照してください。

1.5 特殊キーのマップ

特殊キーをマップに含めるのには次の 3 つの方法があります:

1. Vi 互換の方法: 生のキーコードをマップします。それはほとんどの場合 <Esc> で始まるキーコード列です。このやうなマップを入力するには、まづ ":map " と入力し、CTRL-V を押してからファンクションキーを押します。

   Note:
   そのキーのキーコードが termcap(t_options) にある場合は、自動的に內部コードの形式に變換され、次の 2. のやうなマップになります (’cpoptions’ に ’k’ フラグが指定されてゐる場合は除く)

2. ファンクションキーの內部コードを使ひます。そのやうなマップを入力するには、CTRL-K を押してからファンクションキーを押します。もしくは、"#1"、"#2"、.. "#9"、"#0"、"<Up>"、"<S-Down>"、"<S-F7>"、などの形式で指定します。(キーの表は |key-notation| 參照。<Up> 以下のすべてのキーを使ふことができます)。

   1 から 10 までのファンクションキーは 2 つの方法で定義できます:"#2" のやうな番號だけの方法と、"<F2>" といふ表記で指定する方法です。この兩方がファンクションキー 2 を表します。"#0" はファンクションキー 10 を表し、’t_f10’ で定義されます。"#0" は、キーボードによつてはファンクションキー 0 になることがあります。

   ’cpoptions’ に ’<’ フラグが指定されてゐる場合は、|<>| 表記は使へません。

3. termcap エントリを <t_xx> といふ形式で指定します。"xx" は termcap エントリの名前です。どんなエントリの文字列も使ふことができます。例:

   :map <t_F3> G
   

   これはファンクションキー 13 を "G" にマップします。’cpoptions’ に ’<’ フラグが指定されてゐる場合は使へません。

2. と 3. の方法の利點は、異なる端末でもマップを修正する必要がないことです(ファンクションキーは、同じ意味の內部コード、もしくは實際のキーコードに變換されます。使用してゐる端末に依存しません。termcap が正しく設定されてゐれば、異なる端末で同じマップを共有できます)。

詳細:
まず Vim はキーボードから送られたキーコードがマップされてゐるかどうかを調べます。マップされてゐなければ、端末のキーコードかどうか調べます(參照 |terminal-options|)。端末コードであれば、內部コードで置き換へます。それからもう一度、マップされてゐるかどうかをチェックします (これにより內部コードをマップできます)。

スクリプトファイルに書き込まれる內容は、どのやうに解釋されたかによります。端末のキーコードがマップとして認識された場合は、キーコードそのものがスクリプトファイルに書き込まれます。端末コードとして認識された場合は、內部コードがスクリプトファイルに書き込まれます。

{譯注: > スクリプトファイルに書き込まれる...おそらく |-w| の話。}

1.6 特殊文字

Note:
このドキュメントでは、マップや短縮入力を定義するときに、CTRL-V だけが特殊な文字として觸れられてゐますが、’cpoptions’ が ’B’ を含んでゐない場合は、バックスラッシュも CTRL-V と同樣の特殊な働きをします。|<>| 表記も問題なく使用できます。しかし、"<C-V>" を CTRL-V と同じやうに、(マップを入力するときに) 次の文字をエスケープする目的で使ふことはできません。

バックスラッシュにマップしたり、バックスラッシュをそのまま {rhs} に使ひたい場合は、特別文字 "<Bslash>" を使ひます。マップを入れ子にした場合などにバックスラッシュを二重にする必要がなくなります。

CTRL-C を {lhs} で使ふことはできますが、それは Vim がキー入力を待機中のときだけ機能します。Vim がビジー狀態 (何かを實行中) のときは機能しません。Vim がビジー狀態の場合、CTRL-C は實行中のコマンドを中斷します。

MS-Windows の GUI 環境では、CTRL-C にマップすることができるので、クリップボードにコピーする機能を割り當てることができます。Vim の動作を中斷するには CTRL-Break を使ひます。

{lhs} に空白文字を含めるには CTRL-V を前置してください (空白文字の前で CTRL-V を 2 度押しで入力)。

{rhs} を空白文字で開始するには "<Space>" を使つてください。Vi との互換性を完全に保ちたい場合は |<>| 表記を使はずに、{rhs} の直前に CTRL-V (CTRL-V を 2 度押しで入力)を前置してください。

CTRL-V を 1 つだけ入力した後に (CTRL-V を 2 度押しで入力) 何も入力しないことで空の {rhs} を作ることもできます。殘念ながら vimrc ファイル內ではこの方法は使用できません。

空のマップを作るには {rhs} に "<Nop>" を指定する方法が簡單です。これは |<>| 表記を使へるやうにしてゐれば動作します。例へば、ファンクションキー 8 は何もしない、としたい場合は次のやうにします:

:map  <F8>  <Nop>
:map! <F8>  <Nop>

マルチバイト文字をマップすることができます。ただし、マルチバイト文字の一部のバイトだけをマップすることはできません。それは次のやうな問題が起こるのを防ぐためです:

:set encoding=latin1
:imap <M-C> foo
:set encoding=utf-8

latin1 環境で文字「Ã」(0xc3 または <M-C>) をマップしてゐます。例へば、「á」(0xe1 または <M-a>) は UTF-8 では 0xc3 0xa1 の 2 バイトで表現されるので、0xc3 をマップしてしまふと á が入力できなくなつてしまひます。

マップコマンドで特別な文字列 "<Leader>" を使用すると、その部分が變數 "mapleader" に設定された文字列で置き換はります。"mapleader" が空文字列のときや設定されてゐない場合にはバックスラッシュが使用されます。例:

:map <Leader>A  oanother line<Esc>

これは次のものと同じ意味です: >

:map \A  oanother line<Esc>

しかし次のやうに設定したあとでは:

:let mapleader = ","

次のものと同じ意味になります:

:map ,A  oanother line<Esc>

Note:
變數 "mapleader" はマップを定義するときに使用されます。"mapleader" を變更しても、すでに定義されてゐるマップには影響しません。

<LocalLeader> は <Leader> に似てゐますが、"mapleader" ではなく "maplocalleader" を使用します。<LocalLeader> はバッファローカルのマップに使用するといいでせう。例:

:map <buffer> <LocalLeader>A  oanother line<Esc>

グローバルプラグインでは <Leader> を使用し、ファイルタイププラグインでは <LocalLeader> を使用するといいでせう。"mapleader" と "maplocalleader" の設定は同じでも構ひませんが、別の値を設定すれば、グローバルプラグインとファイルタイププラグインのマップが重なる可能性が低くなります。設定例としては、"mapleader" をバックスラッシュのままにしておいて、"maplocalleader" をアンダースコア (_) にするなど。

特別な文字列 "<SID>" を使つてスクリプトローカルなマップを定義できます。詳細は |<SID>| を參照してください。

特別な文字列 "<Plug>" を使つてスクリプトの內部作業用のマップを定義できます。これはどのキー入力にもマッチしません。プラグインを作成するときに便利です |using-<Plug>|。

<Char> を使つて、文字を 10 進數、8 進數、16 進數の數値指定でマップできます:

これは ’keymap’ ファイルで (マルチバイト) 文字を定義するのに便利です。表記は大文字でも小文字でも構ひません。

マップコマンドでは ’"’ (ダブルクォート) も {lhs} や {rhs} の一部と見なされるため、マップコマンドの後ろにコメントを置くことはできません。しかし、|" を使ふことができます。これはコメント付きの空の新しいコマンドを開始するからです。

’|’ 文字は、マップコマンドと次のコマンドを分けるために使はれるので、’|’ 文字を {rhs} に含めるには特殊な方法が必要です。次の 3 つの方法があります:

(ここで ^V は CTRL-V を表します。1 つの CTRL-V を插入するには CTRL-V を 2 度押しで入力します。この用途では、|<>| 表記を使つて "<C-V>" とすることはできません)。

’cpoptions’ が標準設定のままなら、3 つ全ての方法が使用できます。

’cpoptions’ に ’b’ が含まれてゐる場合、"\|" は、’\’ で終はるマップコマンドの後に、別のコマンドが續いてゐるとみなされます。これは Vi 互換ですが、他のコマンドの場合を考へるとあまり論理的ではありません。

マップに Ex コマンドを含める場合、そのコマンドラインを實行するために改行文字を插入する必要があります。これには <CR> を使ふことが推奬されてゐます (參照 |<>|)。例:

:map  _ls  :!ls -l %:S<CR>:echo "the end"<CR>

插入モードやコマンドラインモードで、入力する文字がマップされないやうにするには、その文字を入力する前に CTRL-V を (1 回) 押してください。’paste’ がオンの場合には、插入モードでマップを使用できません。

Note:
マップを使用したときに、エラーが起きた場合 (エラーメッセージやビープ音が出ます)、マップのまだ實行されてゐない部分は實行されません。これは Vi 互換です。

Note:
コマンド「@zZtTfF[]rm’‘"v」と CTRL-X の引數にはマップは適用されません。どのやうなマップがあつても、レジスタやマークを指定できるやうにするためです。

1.7 マップに使ふキー

マップを定義するときに {lhs} に指定するキーを選ぶことができますが、Vim のコマンドに使はれてゐるキーをマップしてしまふとそれらのコマンドを使用できなくなります。そこで、いくつかの提案があります:

• ファンクションキー (<F2>、<F3>など) や Shift+ファンクションキー(<S-F1>、<S-F2> など) を使用する。<F1> には既にヘルプコマンドが割り當てられてゐます。
• Meta キー (ALTキー) を使用する。あなたのキーボードのアクセント記號付き文字の使用頻度に依存します。|:map-alt-keys|
• "_" や "," などの文字と別の文字を組み合はせて使用する。コマンド "_" と"," はすでに存在してゐますが (|_| と |,| を參照)、使ふ機會はあまりないでせう。
• 他に類するコマンドがあるキーを使用する。例へば、CTRL-P と CTRL-N。さらに多くのマップを使用するには、複數文字を使用します。
• <Leader> と 1 つまたは複數のキーを組み合はせて使用する。これは特にスクリプトで便利です。|mapleader|

標準のキー操作を損なふことなくマップできるキーや、使はれてゐないキーを探すには |index.txt| を參照してください。":help {key}^D" を使用してそのキーが使はれてゐるかどうかを調べることもできます ({key} は調べたいキー、^D は CTRL-D の入力)。

1.8 例

マップの例をいくつか示します (見た通り入力してください。"<CR>" は 4 文字です。このやうな表記(|<>|)は ’cpoptions’ に ’<’ が含まれてゐると使用できません)。

:map <F3>  o#include
:map <M-g> /foo<CR>cwbar<Esc>
:map _x    d/END/e<CR>
:map! qq   quadrillion questions

カウント指定の掛け算

マップの展開前にカウント指定が入力されると、そのカウントは {lhs} の前に入力されたものとして扱はれます。例へば、次のマップを定義したとき:

:map <F4>  3w

2<F4> は "23w" となります。つまり、2 * 3 單語移動するのではなく、23 單語の移動になります。カウントを掛けたい場合は式レジスタを使つてください:

:map <F4>  @='3w'<CR>

クォートで圍まれた部分が實行される式です。|@=|

1.9 マップを使ふ

Vim は、入力されたキーで始まるマップがあるかどうかを調べ、そのやうなマップがある場合は、入力とマップが完全に一致するか一致しないと判斷できるまで、次の入力を待ちます。

例へば、"qq" といふマップがあるとして、最初に入力した ’q’ は、次の文字を入力するまで實際に入力されません。なぜなら、Vim には次に入力される文字が ’q’ であるかさうでないかを知ることができないからです。

’timeout’ がオンになつてゐると (標準設定はオンです)、Vim は 1 秒閒 (または ’timeoutlen’ で指定されてゐる時閒) だけ待機します。待機した後に、’‘q’’ といふ文字が入力されたのだと判斷します。

ゆつくり入力したい場合や、遲いシステムを使用してゐる場合は、’timeout’ をオフにしてください。’ttimeout’ を設定するのもいいでせう。

バッファローカルなマップ (|:map-<buffer>| を使用して定義された) はどのグローバルなマップよりも優先されます。バッファローカルなマップがグローバルなマップと同じ場合、Vim はバッファローカルなマップを使用します。

加へて、<nowait> で定義された場合はより長いマップが同じ接頭辭を持つてゐるとしても、直ちに完了したマップを使用します。例へば、次の 2 つのマップがあるとします:

:map <buffer> <nowait> \a   :echo "Local \a"<CR>
:map                   \abc :echo "Global \abc"<CR>

\a を入力するとバッファローカルなマップが直ちに使用されます。Vim はユーザーが \abc を入力するかどうかを知るためにそれ以上の文字を待つことはしません。

次のやうな狀況では、キーコードが認識されないことがあります:

• Vim がキーコードを部分的にしか讀めない。これは最初の文字だけ讀める場合が多いです。特定の Unix 版と xterm の組み合はせで起こります。
• 文字(列)の後にキーコードがあるマップ。例、"<F1><F1>" や "g<F1>"。

このやうに、キーコードが認識されない狀況では、そのやうなマップを使用することができません。對處方が 2 つあります:

• ’cpoptions’ から ’K’ フラグを除く。さうすると Vim はファンクションキーの殘りのコードを待つやうになります。
• <F1> から <F4> のキーによつて生成される實際のキーコードが <xF1> から <xF4> と同じ場合があります。<xF1> を <F1> へ、<xF2> を <F2> へ、といつたマップが存在しますが、これはマップの後半では認識されません。<F1> から <F4> のキーのキーコードを正しく設定してください:

  :set <F1>=<type CTRL-V><type F1>
  

  <F1> を 4 文字として入力してください。"=" の後の部分は文字通りにではなく、實際のキーを入力してください。

  マップを定義するときに 2 番目の特殊キーを實際のキーコードで指定することでも解決できます:

  :map <F1><Esc>OP :echo "yes"<CR>
  

  本物の <Esc> を入力しないでください。Vim がキーコードを認識し、<F1> に置き換へてしまひます。

他にも、ALT や Meta キーを押しながらキーを入力したときに、コードの 8 ビット目をセットする代はりにそのキーに ESC を前置するやうな端末で問題が起こることがあります。|:map-alt-keys| を參照。

{rhs} の中に {lhs} を含めて、再歸マップを作成できます。{lhs} を入力すると {rhs} に置き換へられ、{rhs} の中に {lhs} があるとその {lhs} がさらに {rhs} に置き換へられ、さらに {rhs} の中の {lhs} が置き換へられ...。といふやうにコマンドを無限に繰り返すことができます。エラーを生じさせないと止めることができないのが唯一の問題です。

例外として、{rhs} が {lhs} で始まつてゐる場合は、その文字は再歸的にマップされません (これは Vi 互換です)。

例へば次のマップは:

:map ab abcd

"a" コマンドを實行して "bcd" を插入します。{rhs} の中の "ab" は再歸的にマップされません。

2 つのキーの意味を入れ換へるやうな場合は :noremap を使つてください。例へば:

:noremap k j
:noremap j k

これは、カーソルの上下移動のコマンドを入れ換へます。

普通の :map コマンドでマップを定義した場合、’remap’ オプションがオンになつてゐると、そのマップが使用された後のテキスト ({rhs}) に {lhs} が含まれてゐる限り、マップが再歸的に繰り返されます。例へば、次のやうなマップを使用する場合:

:map x y
:map y x

Vim はまづ、x を y で置き換へ、それから y を x で置き換へ、...。これを ’maxmapdepth’ に設定された回數だけ (標準設定は 1000 回) 繰り返し、"recursive mapping" といふエラーメッセージを表示します。

マップされたもの ({rhs}) がアンドゥコマンドを含んでゐると、その操作を實行する前の狀態に戾すことになります。アンドゥが 1 回だけなら、その動作はオリジナルの Vi 互換です (オリジナルの Vi では、2 回アンドゥしても意味がなく、最初のアンドゥを實行する前の狀態に戾るだけです)。

1.10 ALT キーを使つたマップ

GUI では、Vim は Alt キーを直接取り扱ふので、ALT キーを使つたマップは常に機能します。CUI 端末では、Vim は受け取つたバイト列から、ALT キーが押されてゐるかどうかを割り出さなければなりません。

端末が modifyOtherKeys モードをサポートし、有效になつてゐる場合、Vim はより多くのキーの組み合はせを認識できます。|modifyOtherKeys| 以下を參照してください。

初期設定では、ALT キーが押されてゐるときは、文字の 8 ビット目が設定されるものと假定してゐます。xterm, aterm, rxvt など、ほとんどの端末はこの方法で問題ありません。<A-k> のやうなマップが動作しない場合は、その端末が、文字の前に ESC を付けてゐるのかもしれません。ユーザーが文字の前に ESC を入力することもできますから、Vim は何が起きたか知ることはできません (ただし、ESC と文字の閒に延滯があるかどうかをチェックする方法はあります。確實な方法ではありませんが)。

現在、gnome-terminal や konsole などの主要な端末が ESC を前置します。代はりに 8 ビット目を使ふやうに設定する方法はないやうです。Xterm では設定なしで機能します。Aterm と rxvt では "--meta8" 引數を使へば機能します。"metaSendsEscape", "eightBitInput", eightBitOutput" のやうなリソースを設定することでも動作を變更できます。

Linux コンソールでは、"setmetamode" コマンドで動作を切り替へることができます。ESC の前置を使はないやうにすると、他のプログラムで問題が起こる可能性があるので注意してください。bash の "convert-meta" が "on" になつてゐることを確認し、Meta キーバインディングが動作するやうにしてください。(システム固有の設定變更をしてゐなければ、これは readline の標準の動作です)次の行を ~/.inputrc に追加すると、その設定をすることができます:

set convert-meta on

ファイルをはじめて作成した場合は、システム全體の設定を維持するために、次の行を最初に加へる必要があるかもしれません(そのファイルがシステムにある場合):

$include /etc/inputrc

このやうに設定すると、ウムラウトのやうな特殊な文字を入力できなくなるかもしれません。その場合は、文字の前に CTRL-V を入力してください。

convert-meta は UTF-8 ロケールでは問題を起こすことがすでに報告されてゐます。xterm のやうな端末では、起動してゐるときに、メニューの "Main Options" から "metaSendsEscape" リソースを設定できます。メニューは端末を Ctrl-LeftClick すると表示できます。他のアプリケーションでは ESC を使ひ、Vim では使ひたくない、といふ場合にこのリソースを使ふと便利です。

1.11 modifyOtherKeys モードのマップ

xterm と他のいくつかの端末は、修飾子付きのキーが特別なエスケープコードで送信されるモードにすることができます。Vim はこれらのコードを認識し、Backspace が文字の 8 を送信した場合でも、CTRL-H と Backspace を區別できます。さらに多くの特別なキーがあります。

xterm の場合、組み込みの termcap エントリで modifyOtherKeys が有效になつてゐます。これを使用しない場合は、vimrc にこれらの行を追加して modifyOtherKeys を有效にできます:

let &t_TI = "\<Esc>[>4;2m"
let &t_TE = "\<Esc>[>4;m"

modifyOtherKeys モードで問題が發生する場合は、無效にすることができます:

let &t_TI = ""
let &t_TE = ""

これはすぐには有效になりません。Vim を再起動せずにこの作業を行ふには、シェルコマンドを實行します。例: ‘!ls‘

modifyOtherKeys が有效になつてゐるのなら、<C-[> と <C-S-{> をマップすることができます:

imap <C-[> [[[
imap <C-S-{> {{{

modifyOtherKeys の <C-[> と <C-S-{> がないと Esc と區別がつきません。

既知の副作用として、插入モードでは、CTRL-V キーの後に生のエスケープシーケンスが插入されます。これは、modifyOtherKeys が有效になつてゐるかどうかを確認するために使用できます。插入モードで CTRL-V CTRL-V と入力し、1 バイトを取得したら modifyOtherKeys をオフにし、<1b>27;5;118~ を取得したらオンにします。

’esckeys’ オプションがオフのとき、modifyOtherKeys は、插入モードを終了するやうな要因のあるすべてのキーを囘避するために、插入モードでは無效にされるでせう。

1.12 オペレータの作成

オペレータは {motion} コマンドと合はせて使はれます。獨自のオペレータを定義するには、最初に ’operatorfunc’ を設定し、そして、|g@| オペレータを呼びます。ユーザーが {motion} コマンドを實行した後、設定した函數が實行されます。

g@{motion}

’operatorfunc’ に設定された函數を實行します。’[ マークに {motion} で選擇された範圍の最初の位置が設定されます。’] マークには選擇範圍の最後の位置が設定されます。函數の引數には、文字列が 1 つ渡されます:

"line" {motion}	は行單位 |linewise|
"char" {motion}	は文字單位 |characterwise|
"block" {motion}	は矩形 |blockwise-visual|

"block" はたまにしか使はれません。ビジュアルモードの場合だけ渡されるのですが、"g@" と合はせてもそれほど便利ではないからです。

{|+eval| が有效な場合のみ利用できます}

例を示します。これは <F4> を使つてスペースの數を數へます:

nmap <silent> <F4> :set opfunc=CountSpaces<CR>g@
vmap <silent> <F4> :<C-U>call CountSpaces(visualmode(), 1)<CR>

function! CountSpaces(type, ...)
  let sel_save = &selection
  let &selection = "inclusive"
  let reg_save = @@

  if a:0  " ビジュアルモードから呼び出すのに、gv コマンドを使用します。
    silent exe "normal! gvy"
  elseif a:type == 'line'
    silent exe "normal! '[V']y"
  else
    silent exe "normal! `[v`]y"
  endif

  echomsg strlen(substitute(@@, '[^ ]', '', 'g'))

  let &selection = sel_save
  let @@ = reg_save
endfunction

Note:
一時的に ’selection’ を "inclusive" に設定し、’[ から ’] まで選擇した範圍を正しくヤンクできるやうにしてゐます。

Note:
ビジュアルモードのために別のマップを定義してゐます。ビジュアルモードで ":" を押した場合に插入される "’<,’>" を削除し、函數に visualmode() の値と追加の引數を渡してゐます。

2. 短縮入力 (Abbreviations)

短縮入力は、插入モード、置換モード、コマンドラインモードで使へます。短縮入力として登錄されてゐる單語を入力すると、それが表す單語に置き換へられます。よく使ふ長い單語を打ち込むときのタイプ數を減らしたり、明確なスペルミスを自動的に修正するのに使へます。

例:

:iab ms Microsoft
:iab tihs this

短縮入力には 3 つの種類があります:

full-id

"full-id" タイプは完全なキーワード文字から構成されます(’iskeyword’ オプションに含まれる文字です)。最も一般的な短縮入力です。

例:

"foo", "g3", "-1"

end-id

"end-id" タイプはキーワード文字で終はりますが、他の文字はキーワード文字ではありません。

例:

"#i", "..f", "$/7"

non-id

"non-id" タイプは非キーワード文字で終はります。他の文字はスペースとタブ文字以外のどんな文字でもよいです。

{Vi では、このタイプはサポートされてゐません}

例:

"def#", "4/7$"

短縮入力にできない文字列の例: "a.b", "#def", "a b", "_$r"

短縮入力は非キーワード文字を入力したときに展開されます。これは、插入モードを終はらせる <Esc> を入力したり、コマンドを終はらせる <CR> を入力したときにも起こります。短縮入力を終はらせる非キーワード文字は、短縮入力を展開した後に插入されます。<C-]> 文字は例外で、短縮入力だけが展開され插入されます。

例:

:ab hh	hello

カーソルの前の文字が短縮入力とマッチする場合のみ機能します。短縮入力の種類によつて、さらに條件があります:

full-id

マッチした場所の前が非キーワード文字、行頭、插入を開始した場所、であること。例外: 短縮入力が 1 文字の場合、その前の文字がスペース、タブ、以外の非キーワード文字なら短縮入力は展開されません。ただし、コマンドラインにおける "’<,’>" (もしくはその他のマーク) は無視され、コマンドラインがその後から始まつてゐるやうに動作します。

end-id

マッチした場所の前が非キーワード文字、スペース、タブ、行頭、插入を開始した場所、であること。

non-id

マッチした場所の前がタブ、行頭、插入を開始した場所、であること。

例: ({CURSOR} は非キーワード文字を入力する場所です)

:ab foo   four old otters

:ab #i #include

:ab ;; <endofline>

插入モードで短縮入力の展開を避けるには、短縮入力を發動する可能性のある文字を入力する前に CTRL-V を押します。 例: CTRL-V <Space> もしくは短縮入力の一部を入力してから插入モードを <Esc> で拔け、再度插入モードに "a" で入つて殘りを入力します。

コマンドラインモードで短縮入力の展開を避けるには、短縮入力の文字の途中で CTRL-V を入力します (CTRL-V を 2 度押し)。展開されなかつた場合、普通の文字の前の CTRL-V は普通は無視されます。

短縮入力の後で、カーソルを動かすこともできます:

:iab if if ()<Left>

これは、’cpoptions’ に ’<’ フラグが含まれてゐると、うまく動作しません。|<>|

さらに手の込んだこともできます。例へば、短縮入力を展開するときに入力したスペースを消してしまふには:

func Eatchar(pat)
   let c = nr2char(getchar(0))
   return (c =~ a:pat) ? '' : c
endfunc
iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR>

標準設定されてゐる短縮入力はありません。

短縮入力の展開は再歸的には行はれません。":ab f f-o-o" といふ短縮入力を問題なく使ふことができます。しかし、展開された文字にはマップが適用されます。{Vi のいくつかのバージョンで再歸的な短縮入力をサポートしてゐますが、そこになんら明確な理由はありません}

’paste’ オプションがオンの場合、短縮入力は使用できません。

マップと同じやうに、バッファローカルな短縮入力を作成できます。これは主に |filetype-plugin| などで使用されます。C 言語用プラグインの例:

:abb <buffer> FF  for (i = 0; i < ; ++i)

:ab[breviate]

すべての短縮入力を一覽表示します。行頭の文字は、その短縮入力を使用できるモードを示してゐます: ’i’ は插入モード、’c’ はコマンドラインモード、’!’ はその兩方。マップの一覽表示と同じです。|map-listing| を參照。

’verbose’ がゼロ以外のときに短縮入力一覽を表示すると、どこで定義されたのかも表示されます。例:

:verbose abbreviate

!  teh           the
        Last set from /home/abcd/vim/abbr.vim

詳しくは |:verbose-cmd| を參照してください。

:ab[breviate] {lhs}

{lhs} で始まる短縮入力を一覽表示します。{lhs} に入力した文字が短縮入力として展開されないやうにするには CTRL-V (2 度押しで入力する) を插入します。さうしないとコマンドライン用の短縮入力があつた場合にそれが展開されてしまひます。

:ab[breviate] [<expr>] [<buffer>] {lhs} {rhs}

{rhs} の短縮入力を {lhs} として定義します。既に {lhs} が定義されてゐると、新しい {rhs} で置き換へられます。{rhs} はスペースを含んでゐてもかまひません。

<expr> 引數については |:map-<expr>| を參照してください。

<buffer> 引數については |:map-<buffer>| を參照してください。

:una[bbreviate] {lhs}

{lhs} といふ短縮入力を全て削除します。見つからなかつた場合は、{lhs} に入力した文字を各短縮入力の {rhs} から探して見つかつたものを削除します。これは短縮入力が展開されてしまつた狀態でも削除できるやうにするためです。短縮入力の展開を防ぐには CTRL-V (2 度押しで入力する) を插入します。

:norea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]

":ab" と同じですが、展開後にマップを適用しません。

:ca[bbrev] [<expr>] [<buffer>] [lhs] [rhs]

":ab" と同じですが、コマンドラインモード用の短縮入力のみ對象です。

:cuna[bbrev] {lhs}

":una" と同じですが、コマンドラインモード用の短縮入力のみ對象です。

:cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]

":ab" と同じですが、コマンドラインモード用の短縮入力のみ對象で、展開後にマップを適用しません。

:ia[bbrev] [<expr>] [<buffer>] [lhs] [rhs]

":ab" と同じですが、插入モード用の短縮入力のみ對象です。

:iuna[bbrev] {lhs}

":una" と同じですが、插入モード用の短縮入力のみ對象です。

:inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]

":ab" と同じですが、插入モード用の短縮入力のみ對象で、展開後にマップを適用しません。

:abc[lear] [<buffer>]

すべての短縮入力を削除します。

:iabc[lear] [<buffer>]

插入モード用の短縮入力を削除します。

:cabc[lear] [<buffer>]

コマンドラインモード用の短縮入力を削除します。

特殊な文字を短縮入力の {rhs} で使ふことができます。非印字可能文字の特殊な意味を打ち消す(クォートする)には、CTRL-V を使用します。必要な CTRL-V の數は、どのやうな短縮入力を作成するかによります。これはマップでも同樣です。例を示します。

"esc" を實際の <Esc> 文字を插入する短縮入力にしたいとしませう。Vim で ":ab" コマンドを使ふときには、次のやうにしなければなりません: (ここで ^V は CTRL-V で、^[ は <Esc> です)

入力: ab esc ^V^V^V^V^V^[

キー入力はすべて ^V によるクォートが適用されます。つまり、1 番目、3 番目、5 番目の ^V は、2 番目と 4 番目の ^V と、^[ がコマンドラインに入力されるやうにしてゐます。

見え方: ab esc ^V^V^[

コマンドラインには實際には 2 つの ^V と ^[ が表示されてゐます。もしさうするつもりがあれば、これは .exrc ファイルでの見え方になるはずです。始めの ^V は 2 番目の ^V をクォートするためにあります。:ab コマンドは ^V をクォート文字として扱ひますので、短縮入力の中で、クォートされた空白文字や ’|’ 文字を使ふことができます。:ab コマンドは ^[ に對しては何も特殊な處理は行ひません。だからクォートする必要もないです。(クォートしても問題はありません。上の例は 7 ( 8 はだめです！) 個の ^V を入力しても動作します)。

格納: esc ^V^[

コマンドが解析された後、短い形式 ("esc") と長い形式 ("^V^[" の 2 文字) として、短縮入力の一覽に加へられます。:ab コマンドを引數なしで實行したときに、この形の短縮入力が表示されます。

あとで、ユーザーが "esc" を入力し、短縮入力が展開されたとき、長い形式は實際のキー入力と同樣に ^V によるクォートが適用されます。つまり、^V が ^[ をクォートし、"插入モードから拔ける" 文字として解釋されることを防ぐのです。その代はりに、^[ がテキストに插入されます。

展開: ^[

[例は Steve Kirkendall によつて提供されました]

3. ローカルマップとローカル函數 (Local mappings and functions)

いくつかの Vim script を倂用すると、あるスクリプトで使はれてゐるマップや函數と同じ名前のものが別のスクリプトでも使用される恐れがあります。それを避けるには、スクリプトローカルなマップや函數を使用します。

マップやメニューに "<SID>" といふ特別な文字列を使用できます。これは ’cpoptions’にフラグ ’<’ が含まれてゐると利用できません。マップコマンドを實行すると、"<SID>" は、<SNR> といふ特別なキーコードとスクリプト固有の番號、そしてアンダースコアに置換されます。例:

:map <SID>Add

これは "<SNR>23_Add" といつたマップを定義します。

スクリプトで函數を作成するときに、函數名の前に "s:" を付けると、ローカル函數を作成できます。しかし、その函數をマップで使用する場合、そのマップをスクリプト以外の場所で實行すると、その函數がどのスクリプトで定義されたのか分かりません。これを解決するには、マップ中で "s:" ではなく "<SID>" を使用します。この場合も "<SID>" は上記の例と同じやうに置換されます。これでローカル函數の呼び出しを含むマップを定義できます。

ローカル函數は、その函數を定義したスクリプトのコンテキストで實行されます。そのため、その函數內で新たに定義した函數やマップにも "s:" や "<SID>" を使用できます。その場合、その函數自身と同じスクリプト番號が使用されます。"s:var" といつたスクリプトローカル變數も同樣です。

自動コマンドやユーザー定義コマンドもそれを定義したスクリプトのコンテキストで實行されます。そのコマンドからローカル函數を呼び出したり、ローカルマップを使用することができます。

スクリプト以外の場所で "<SID>" を使ふとエラーになります。

複雜な處理をするスクリプトで、スクリプト番號が必要な場合は、次の函數で番號を得られます:

function s:SID()
  return matchstr(expand('<sfile>'), '<SNR>\zs\d\+\ze_SID$')
endfun

函數やマップを一覽表示するときには "<SNR>" も表示されます。それらがどのやうに定義されてゐるのか調べるときに便利です。

コマンド |:scriptnames| を使つて、それまでに實行されたスクリプトとそのスクリプト番號を確認できます。

これらはすべて {|+eval| が有效な場合のみ利用できます}

4. ユーザー定義コマンド (User-defined command)

ユーザー獨自の Ex コマンドを定義することできます。ユーザー定義コマンドはビルトインコマンドと同樣に振る舞ふことができます (範圍指定や、引數を取ることができます。引數の入力では、ファイル名、バッファ名などを補完できます)。違ひは、コマンドが實行されると、通常の Ex コマンドに變換してから實行されるといふことです。

まづはユーザーマニュアルの |40.2| を參照してください。

すべてのユーザー定義コマンドは大文字で開始する必要があります。これはビルトインコマンドと混同しないやうにするためです。特例として次のやうなビルトインコマンドもありますが:

:Next
:X

これらの名前もユーザー定義コマンドには使へません。":Print" コマンドも存在しますがこれは非推奬 (deprecated) になつてをり、上書きすることができます。

ユーザーコマンドの開始文字以外は、大文字であつても小文字であつても、數字であつてもかまひません。數字を使ふ場合、數字を引數に取る他のコマンドが曖昧になるかもしれないので注意してください。例へば、"Cc2" コマンドは ":Cc2" といふ引數なしのユーザーコマンドとしても、"2" といふ引數を取つた ":Cc" コマンドとしても解釋できます。これらの問題を避けるため、コマンド名と引數の閒にスペースを插入することを勸めます。

ユーザー定義コマンドを使ふときに、コマンドの省略形を使ふこともできます。しかしながら、その省略形が唯一でなければエラーが起きます。加へて、ビルトインコマンドが常に優先されます。

例:

:command Rename ...
:command Renumber ...
:Rena                           " "Rename" を意味します
:Renu                           " "Renumber" を意味します
:Ren                            " エラー - 曖昧
:command Paste ...
:P                              " ビルトインコマンドの:Print です

スクリプトの中で使ふときは、ユーザー定義コマンドの完全な名前を使ふやうにしませう。

:com[mand]

すべてのユーザー定義コマンドを一覽表示します。表示中の行頭の文字は次の意味です:

!	-bang 屬性を持つコマンド
"	-register 屬性を持つコマンド
|	-bar 屬性を持つコマンド
b	カレントバッファのローカルコマンド

(屬性に關する詳細は下記參照)

一覽は |:filter| を用ゐてコマンド名でフィルタできます。例へば名前に "Pyth" を含む全コマンドを一覽するならば次のやうにします:

filter Pyth command

:com[mand] {cmd}

{cmd} で始まるユーザー定義コマンドを一覽表示します。

’verbose’ がゼロ以外のときにコマンド一覽を表示すると、どこで定義されたのかも表示されます。例:

:verbose command TOhtml

Name        Args Range Complete  Definition
TOhtml      0    %               :call Convert2HTML(<line1>, <line2>)
    Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim

詳しくは |:verbose-cmd| を參照してください。

:com[mand][!] [{attr}...] {cmd} {rep}

ユーザー定義コマンドを定義します。コマンド名は {cmd} でそれを置き換へるテキストが {rep} です。{attr} はコマンド屬性 (下記參照) です。既にコマンドが存在してゐる場合はエラーになります。! を指定した場合は再定義されます。

1 つ例外があります: スクリプトを再讀み込みする場合、そのスクリプトで以前に定義されてゐたコマンドは、靜かに置き換へられます。

:delc[ommand] {cmd}

ユーザー定義コマンド {cmd} を削除します。

:comc[lear]

すべてのユーザー定義コマンドを削除します。

コマンド屬性

ユーザー定義コマンドは、他のビルトインコマンドと同樣に扱はれます。引數や範圍も指定できます。引數の入力時にはファイル名やバッファ名などを補完することができます。どのやうに動作するかはコマンドを定義するときに指定したコマンド屬性に依存します。

たくさんの屬性がありますが、それらは、引數の扱ひ方、補完の種類、範圍指定の仕方、特殊なケース、の 4 つの分野に分けることができます。以下、分野別に說明します。

引數の扱ひ方

屬性を指定しなかつた場合、ユーザー定義コマンドは引數を取りません (引數が與へられた場合はエラーになります)。-nargs 屬性を指定すると、ユーザー定義コマンドが引數指定できるやうになります。次の屬性が指定できます:

引數は (エスケープされてゐない) スペースやタブ文字で區切られます。ただし、引數を 1 つだけ取る場合は空白は引數の一部として解釋されます。

Note:
引數は Vim script の式としてではなく、テキストとして解釋されることに注意してください。具體的な例を上げると、"s:var" を引數として渡すと、そのコマンドを實行したスクリプトのローカル變數ではなく、そのコマンドを定義したスクリプトのローカル變數が使用されます。例:

script1.vim:
    :let s:error = "None"
    :command -nargs=1 Error echoerr <args>
script2.vim:
    :source script1.vim
    :let s:error = "Wrong!"
    :Error s:error

script2.vim を實行すると "None" が表示されます。期待した結果とは違ふでせう。代はりに函數呼び出しを使つてください。

補完の種類

屬性を指定しない場合、ユーザー定義コマンドの入力時に引數は補完されません。下記の屬性のうちいづれか 1 つを指定することで、引數が補完されるやうになります。

Note:
いくつかの補完方法は環境變數を展開します。

ユーザー定義の補完

補完方法に "custom,{func}"、"customlist,{func}" を指定すると獨自の補完を使用できます。{func}には次のやうな函數を指定します。

:function {func}(ArgLead, CmdLine, CursorPos)

すべての引數を使ふ必要はありません。函數の戾り値として、補完候補のリストを返してください。

"custom" を使つた場合は、補完候補のリストを 1 つずつ改行で區切つてください。

"customlist" を使つた場合は、補完候補のリストを |List| で返してください。リスト中の文字列以外の變數は無視されます。

引數には次の意味があります:

これらの引數を使へば文脈を判斷することができるでせう。"custom" を使つた場合、補完候補のリストから ArgLead にそぐはない候補 (ArgLead で始まらない文字) を取り除く必要はありません。Vim は補完函數を實行した後にふさはしくない候補を取り除きます。おそらくその方がほとんどの場面で有用です。"customlist" を使つた場合、Vim は補完候補のリストをフィルタしません。補完候補のリストを自分でフィルタしてください。

次の例はFingerコマンドでユーザー名を補完します

:com -complete=custom,ListUsers -nargs=1 Finger !finger <args>
:fun ListUsers(A,L,P)
:    return system("cut -d: -f1 /etc/passwd")
:endfun

次の例では、’path’ に指定されたディレクトリのファイル名を補完してゐます:

:com -nargs=1 -bang -complete=customlist,EditFileComplete
\ EditFile edit<bang> <args>
:fun EditFileComplete(A,L,P)
:    return split(globpath(&path, a:A), "\n")
:endfun

この例はファイル名にスペースが含まれてゐると機能しません！

範圍指定

屬性を指定しない場合、ユーザー定義コマンドは行番號による範圍指定を受け付けません。-range 屬性を指定して、コマンドが範圍指定を受け付けるやうにできます。任意のカウント値を取るやうにすることもできます。この場合、行番號の位置 (|:split| コマンドのやうに -range=N) で指定するか、"count" 引數 (|:Next| コマンドのやうに -count=N) で指定します。カウント指定は |<count>| で取得できます。

次の屬性が利用できます:

Note:
-range=N と -count=N は相互に排他的であるといふことに注意してください。どちらか一方のみを指定することができます。

範圍指定には ., $, % といつた特殊文字を含むことができ、それぞれ現在行、最終行、バッファ全體を表します。これらは引數、(ロードされた) バッファ、ウィンドウ及びタブページに關聯付けすることができます。

次の値を利用できます (2 列目は一覽表示で使はれる短い名前です):

特殊なケース

特殊なケースがいくつかあります:

ユーザー定義コマンドの定義に -count や -register が指定された場合に、その省略可能な引數が與へられた場合、それは引數リストから削除され、それぞれの引數に對應する特別な文字列が利用できるやうになります。

Note:
これらの引數は省略できますが、これは廢止される機能です。新しいスクリプトでは完全な名前を使用して下さい。

置き換へテキスト

ユーザー定義コマンドでは、<...> 表記を使つた特別な文字列を使用できます。その文字列はコマンドラインに入力された實際の引數に置き換へられます。その他のテキストは變更されません。そして特別な文字列を實際の引數で置換したものが Ex コマンドとして實行されます。<> 表記が置き換へられないやうにするには、最初の < の代はりに <lt> を使つてください。例へば、"<bang>" をリテラル文字として使ふには "<lt>bang>" とします。

次のものを使用できます

<line1>

コマンド範圍の最初の行

<line2>

コマンド範圍の最後の行

<range>

コマンド範圍を指定するために使はれた要素の數: 0, 1 もしくは 2

<count>

與へられたカウント (’-range’ と ’-count’ 屬性で記述されてゐる)

<bang>

(’-bang’ 屬性を參照) コマンドが ! 修飾子付きで實行された場合に ! に置換されます。指定なしの場合は空文字列になります。

<mods>

指定されてゐる場合はコマンド修飾子。されてゐない場合は何も展開しません。對應してゐる修飾子は次の通り: |:aboveleft|, |:belowright|, |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|, |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:leftabove|, |:lockmarks|, |:noswapfile| |:rightbelow|, |:silent|, |:tab|, |:topleft|, |:verbose| そして |:vertical|。

Note:
次のコマンド修飾子には對應してゐないことに注意してください: |:noautocmd|, |:sandbox| そして |:unsilent|。

例:

command! -nargs=+ -complete=file MyEdit
            \ for f in expand(<q-args>, 0, 1) |
            \ exe '<mods> split ' . f |
            \ endfor

function! SpecialEdit(files, mods)
    for f in expand(a:files, 0, 1)
        exe a:mods . ' split ' . f
    endfor
endfunction
command! -nargs=+ -complete=file Sedit
            \ call SpecialEdit(<q-args>, <q-mods>)

<reg>

(’-register’ 屬性を參照) レジスタ名に置換されます。指定なしの場合は空文字列になります。<register> も同義です。

<args>

與へられた通りのコマンド引數 (上記の通り、カウントやレジスタが指定された場合は <args> に含まれません)。

<lt>

1 つの ’<’ (小なり)文字。特別な文字列を文字どほりに使用したい場合に必要となります。例へば <bang> を得るには <lt>bang> とします。

特別な文字列の始めの2文字が "q-" なら(例へば <q-args>)、引數は式で使へるやうにクォートされます ("で圍まれる)。これは引數を 1 つの値として扱ひます。引數がない場合は <q-args> は空文字列になります。 ユーザー定義コマンドの引數を函數に渡すには、<f-args>("function args") が利用できます。これはコマンドの引數をスペースやタブ文字で區切り、それぞれの引數を別々にクォート ("で圍む) し、コンマで區切つたリストにして <f-args> と置き換へます。下の Mycmd の例をご覽下さい。引數がない場合は <f-args> は取り除かれます。

<f-args> の引數にスペースを含めるには、バックスラッシュを前置します。<f-args> では 2 つのバックスラッシュ (\\) は 1 つのバックスラッシュに置換されます。スペースとバックスラッシュ以外の文字に付いてゐるバックスラッシュはそのまま使はれます。

要約:

例

" 現在行から最後行までを削除します
:com Ddel +,$d

" 現在のバッファ名を變更します
:com -nargs=1 -bang -complete=file Ren f <args>|w<bang>

" 指定された範圍をあるファイルの內容に置き換へます
" (1 行に書きます)
:com -range -nargs=1 -complete=file
      Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d

" 指定された範圍の行數を數へる
:com! -range -nargs=0 Lines  echo <line2> - <line1> + 1 "lines"

" ユーザー函數を呼びます (<f-args> の例)
:com -nargs=* Mycmd call Myfunc(<f-args>)

次のやうに實行された場合は:

:Mycmd arg1 arg2

次のものを實行します:

:call Myfunc("arg1","arg2")

" より現實的な例
:function Allargs(command)
:   let i = 0
:   while i < argc()
:      if filereadable(argv(i))
:         execute "e " . argv(i)
:         execute a:command
:       endif
:       let i = i + 1
:    endwhile
:endfunction
:command -nargs=+ -complete=command Allargs call Allargs(<q-args>)

Allargs コマンドは、引數としてどの Vim コマンドでも取ることができ、引數リスト |argument-list| のすべてのファイルに對して與へられたコマンドを實行します。使ひ方の例 ("e" フラグをつけてエラーを無視してをり、また "update" コマンドで變更されたバッファを書き込んでゐるので注意してください):

:Allargs %s/foo/bar/ge|update

これは、次のものを起動します:

:call Allargs("%s/foo/bar/ge|update")

スクリプトでユーザー定義コマンドを定義するとき、そのスクリプトのローカル函數やローカルマップを使用できます。ユーザー定義コマンドはユーザー定義コマンドを定義したスクリプトのコンテキストで實行されます。これはユーザー定義コマンドで |<SID>| を使用するときに重要です。