プラグインの仕様

プラグインはautoload/neocomplcache/sourcesにインストールしたものが自動的に読み込まれます。 プラグインには、neocomplcache#sources#プラグイン名#define()が絶対必要です。 これはneocomplcacheが初期化するときに呼ばれ、neocomplcacheにディクショナリ変数を渡します。 ここではディクショナリ変数に必要な要素について説明をします。

name

プラグインの名前です。

kind

プラグインの種類を現します。plugin, ftplugin, complfuncの三種類があります。これらの違いについては後述します。

filetypes

ftpluginにのみ存在します。どのファイルタイプで補完するかを表すディクショナリ変数です。

initialize()

プラグインの初期化時に呼ばれます。コマンドの登録等を行います。ftpluginの場合、これが呼ばれるのはfiletypesに対応するバッファで補完されたときです。

finalize()

neocomplcacheの無効化されるときに呼ばれます。ここで不要になったコマンドやautocmdを削除します。

get_keyword_list(cur_keyword_str)

pluginにのみ存在します。a:cur_keyword_strにマッチするリストを返すために呼ばれる関数です。get_keyword_list()が返す補完リストは、特定のキーを含むディクショナリのリストとなっています。詳しくは「補完リストの仕様」の項を参照してください。

get_keyword_pos(cur_text)

ftpluginとcomplfuncに存在します。cur_textにマッチする補完位置を返します。

get_complete_words(cur_keyword_pos, cur_keyword_str)

ftpluginとcomplfuncに存在します。a:cur_keyword_strにマッチするリストを返すために呼ばれます。get_complete_words()が返す補完リストは、特定のキーを含むディクショナリのリストとなっています。詳しくは「補完リストの仕様」の項を参照してください。

補完リストの仕様

get_keyword_list()やget_complete_words()が返す補完リストは、特定のキーを含むディクショナリのリストとなっています。一部のキー以外はVim標準の補完で使用するものと同じです。

word, abbr, menu, info, icase, dup

Vim標準の補完で使用するものと同じです。word以外は省略することができます。詳しい解説は、[Hack #14: ]Insert mode補完 自作編を参照してください。 menuはどのプラグインの候補で補完しているかを[B]のような記号で表す習慣になっています。ftpluginは[vim]や[ghc]のように、長めの文字列を使います。

プラグイン用ヘルパ関数

autoload/neocomplcache.vimには、プラグインから呼び出せるようにヘルパ関数が実装されています。ここでは、よく使われる関数について解説します。

neocomplcache#keyword_filter(list, cur_keyword_str)

get_keyword_list()で使用できる、単純なフィルターです。a:listの中から、a:cur_keyword_strにマッチするリストを返します。filter()とは違って、listは変更されるとは限りません。

neocomplcache#unpack_dictionary(dict)

リストの辞書をリスト化して返します。

neocomplcache#unpack_dictionary_dictionary(dict)

辞書の辞書をリスト化して返します。

neocomplcache#keyword_escape(cur_keyword_str)

a:cur_keyword_strをマッチングに使えるようにエスケープします。

neocomplcache#get_cur_text()

現在のカーソル文字列を取得します。

neocomplcache#get_completion_length(plugin_name)

plugin_nameの自動補完する文字列長を返します。

neocomplcache#set_completion_length(plugin_name)

plugin_nameの自動補完する文字列長を設定します。ただし、これはプラグイン側で初期値を設定するためのもので、ユーザーが補完文字列長を設定している場合、そちらが優先されます。

neocomplcache#get_keyword_pattern_end(filetype)

文字列の最後にマッチするfiletypeのキーワードパターンを返します。filetypeは省略可能で、省略すると現在のバッファのfiletypeを参照します。

neocomplcache#get_keyword_pattern(filetype)

文字列にマッチするfiletypeのキーワードパターンを返します。filetypeは省略可能で、省略すると現在のバッファのfiletypeを参照します。

neocomplcache#is_auto_complete()

自動補完の時に1を返します。

neocomplcache#print_caching(string)

キャッシュ時のメッセージを表示します。

neocomplcache#print_error(string)

エラーメッセージを表示します。

キャッシュ用ヘルパ関数

autoload/neocomplcache/cache.vimには、プラグインから呼び出せるキャッシュのヘルパ関数が含まれます。 量が多いので、ここでは詳しく説明することは避けますが、うまく利用すると簡単にキャッシュを使ったプラグインを記述できます。 ちなみに、neocomplcache Ver.4以降では、ほとんどのプラグインがキャッシュ用ヘルパ関数を使うように書き直されています。

プラグインのサンプル

neocomplcacheに標準添付のプラグインを参考にしても良いのですが、機能が複雑化しているため、プラグイン作りの勉強のために見るのは大変です。 eagletmtさんが作成したghc_completeはfiletype pluginでほどよい長さなので、勉強に最適でしょう。

plugin, ftplugin, complfuncの違い

neocomplcache Ver.3.00より、complfuncが実装され、より自由度の高い補完が実装できるようになりました。 pluginとcomplfuncの違いは、pluginはカーソル前のキーワードから補完しますが、complfuncは独自に補完位置を決定できるというところです。 ftpluginとはneocomplcacheのオムニ補完です。 基本的な仕様はcomplfuncと同じです。ただし、必要な時にのみ初期化や呼び出しされるというところが違います。

インクルード補完とは

インクルード補完とは、バッファ中のインクルード文を解析して、補完候補に加える補完のことです。Vim自体にもインクルード補完が備わっていますが、Perlなど'path'が多数のディレクトリに設定されている言語では重すぎて使いものになりません。neocomplcacheのインクルード補完は結果をキャッシュすることで、Vim標準のインクルード補完に存在する欠点を補うために開発されました。タグ補完と比較すると、インクルードしているファイルだけ解析するので補完候補が多すぎる問題が発生しにくい、あらかじめタグファイルを生成する必要がない、といった利点があります。

インクルード補完の制限

インクルード補完は強力ですが、万能ではありません。'path'や'includeexpr', 'include'といったオプションが適切に設定されている必要があります。特にWindows環境では、ftpluginなどで設定する必要があるかもしれません。インクルード補完ではctagsを利用するので、システムにインストールされている必要があります。ctagsが存在しなかったり、ctagsに対応していない言語の場合(D言語など)はバッファをそのまま解析するので、buffer_completeと動作が同じになります。

今後のインクルード補完

現在実装されているインクルード補完はまだ実験的な意味合いが強いです。 今後は、gtagsへの対応やechodocへの対応、遅延キャッシュなどを考えています。 ただしgtagsはカレントディレクトリにタグファイルを作るらしく、ctagsのように簡単に解析するのは難しそうです。

参考文献

neocomplcache.vim のインクルード補完の使い方 thincaさんのインクルード補完解説記事。neocomplcache Ver.3.06を対象としていて、neocomplcache Ver.5.0がリリースされた現在では変数名等が古くなっていますが、参考になると思います。

Command-line modeの欠点

なぜCommand-line modeが使えないかというと、次のような欠点があるからです。

編集能力が貧弱

Command-line modeは基本的にラインエディタなので、シェル並の編集しかできません。テキストオブジェクトといった便利な機能も使えないのです。

自動補完ができない

もはや筆者は自動補完のある環境が普通になってしまい、neocomplcacheがないと仕事になりませんが、残念ながらCommand-line modeでは使えません。さらに、Command-line modeは補完も貧弱なので、困ったものです。

設定が分散する

Insert modeとCommand-line modeは独立しているので、キーマップ等は別々に定義しなければなりません。これは不便です。

履歴検索が面倒

Command-line modeでは、履歴検索が簡単にはできません。

cnoremap <C-n>          <Down>
cnoremap <C-p>          <Up>

とキーマップを定義する手はあります。これなら現在入力されているものにマッチする候補を検索することができます。しかしvimshellのように一覧から履歴を検索する方法はなく、そもそも設定が面倒です。検索にはfuzzyfinderやkuを使うという手もありますが、この程度のことで外部プラグインに依存するというのもどうでしょうか。

Command-line window

そこで、本HackではCommand-line modeの代わりに、Command-line windowという機能を使うことを提案します。 Command-line windowとは何かというと、Vimに組み込まれている、Ex commandを実行できるバッファのことです。 Command-line windowは'filetype'がvimであるため、Vimのvim filetype pluginがすべて使えます。 特にneocomplcacheはVimのオムニ補完を搭載し、ユーザー定義のコマンドも解析できるため、併用するとneocomplcacheのパワーを存分に発揮することができます。 neocomplcacheは補完だけでなく、コマンドの引数情報をエコー領域に表示することもできます。 neocomplcacheに実装されている、Vimのオムニ補完は仕組みが複雑なので、今後のVim Hacksで詳しく解説する予定です。 Command-line windowについて詳しい情報は、:help cmdwinを参照してください。

Command-line windowを設定する

Command-line windowはウインドウに入ったときにInsert modeにならなかったり、neocomplcacheと相性が悪かったりして使いづらいので、カスタマイズする必要があります。筆者は.vimrc中で、次のように設定しています。この設定では:を入力したときにCommand-line windowに遷移するようにしています。CmdwinEnterにautocmdを設定すれば簡単にカスタマイズできるので、皆さんも最適な設定を探してみてください。

nnoremap <sid>(command-line-enter) q:
xnoremap <sid>(command-line-enter) q:
nnoremap <sid>(command-line-norange) q:<C-u>

nmap :  <sid>(command-line-enter)
xmap :  <sid>(command-line-enter)

autocmd MyAutoCmd CmdwinEnter * call s:init_cmdwin()
function! s:init_cmdwin()
  nnoremap <buffer> q :<C-u>quit<CR>
  nnoremap <buffer> <TAB> :<C-u>quit<CR>
  inoremap <buffer><expr><CR> pumvisible() ? "\<C-y>\<CR>" : "\<CR>"
  inoremap <buffer><expr><C-h> pumvisible() ? "\<C-y>\<C-h>" : "\<C-h>"
  inoremap <buffer><expr><BS> pumvisible() ? "\<C-y>\<C-h>" : "\<C-h>"

  " Completion.
  inoremap <buffer><expr><TAB>  pumvisible() ? "\<C-n>" : "\<TAB>"

  startinsert!
endfunction

追記： Command-line windowでは、altercmdが使用できません。これでは不便なので、tyruさんがCommand-line windowでも使えるように改造したものを公開しているので、こちらを使ってください。 私は次のように設定しています。

function! s:init_cmdwin()
        call altercmd#define('b', 'gr[ep]', 'Grep', 'i')
        " AlterCommand <buffer><mode:i> gr[ep] Grepでも可
endfunction

タグ補完とは

タグ補完とは、’tags’から補完候補を取ってくることで補完することです。 Vim標準では<C-x><C-v>を用います。 neocomplcacheではtags_completeというプラグインによって実装されています。 .や->といったg:neocomplcache_member_prefix_patterns[&filetype]にマッチする入力のあるときに補完を行うと、 クラスのメンバのみが補完候補となる機能を持っています。 要望があったので実装しましたが、私は個人的にタグ補完が好きではありません。なぜなら、タグ補完は候補が多くなりすぎるからです。 候補が多いとneocomplcacheのキャッシュや補完動作が明らかに遅くなります。 そこでtags_complete.vimでは、g:neocomplcache_caching_limit_file_sizeよりも大きいタグファイルは自動的にキャッシュしません。 どうしても使いたいならば、:NeoComplCacheCachingTagsコマンドを実行してください。 ctagsではタグを生成できない言語も多いので、現在ではより高機能なインクルード補完を用いるべきでしょう。インクルード補完については、今後のVim Hacksで解説予定です。

ディクショナリ補完とは

ディクショナリ補完とは、登録された辞書ファイルから補完候補を取ってくることで補完することです。 前回解説したシンタックス補完も一種のディクショナリ補完と言えます。 Vim標準では<C-x><C-k>を用います。 neocomplcacheではdictionary_completeというプラグインによって実装されています。 g:neocomplcache_dictionary_filetype_lists[&filetype]に辞書ファイルを登録しておけば、自動的にキャッシュされます。 例えば、vimshellでは履歴ファイルを辞書ファイルとして登録しておけば便利です。 g:neocomplcache_dictionary_filetype_lists[&filetype]が存在していない場合、自動的に’dictionary’の値が使われます。

シンタックス補完とは

シンタックス補完とは、標準添付プラグインのautoload/syntaxComplete.vimをさらに汎用的にし、neocomplcacheのプラグインとして独自実装したものです。 内部動作としては:syn listの結果を解析し、キーワードを補完候補に加えます。 １度目は候補をキャッシュするので、若干時間がかかりますが、その後は高速に動作します。 Vimの豊富なシンタックスキーワードを有効活用するので、辞書を別途用意する必要はなく、非常に便利です。

autoload/syntaxComplete.vimとの比較

autoload/syntaxComplete.vimはキーワード文字列しか解析できませんが、neocomplcacheのシンタックス補完は正規表現のパターンも解析するので、HaskellやTeXといったファイルタイプでもシンタックス補完が使えます。 ただし()や[]を使った複雑な正規表現では、上手くパースできないことがあります。 ご了承下さい。

Same FileType Completion

シンタックス補完はneocomplcache独自の補完機能である、Same FileType Completionに対応しています。 Same FileType CompletionとはCとC++のように、似たファイルタイプを関連付けて相互参照できるようにす機能です。 これにより、vimshellのiexeから起動したirbのバッファ上でRubyキーワードを補完できます。

使用上の注意

Action scriptやVim Scriptのautocmdを補完するとき、シンタックスの補完候補が小文字になってしまうことがあります。 これはシンタックスファイルの syn case ignore が悪さをしているせいです。プラグイン側では対処しようがないので、気になるようだったら直接シンタックスファイルを修正してください。

キーワード補完とは

neocomplcacheのキーワード補完は、<C-n>や<C-p>で呼び出すことのできるVim組み込みのキーワード補完を模倣して設計されています。 言語ごとにキーワードパターンを定義して、一括して候補を検索できるのが最大の特徴です。 使用するキーワードパターンはg:NeoComplCache_KeywordPatternsで定義されています。

pluginとcomplfuncの違い

neocomplcacheには補完候補を収集するために、pluginとcomplfuncという二つの拡張プラグインが存在します。 それぞれ、autoload/neocomplcache/pluginとautoload/neocomplcache/complfuncに配置します。 pluginはkeyword_complete.vimから一括して呼びだされる拡張プラグインで、単純なため実装が比較的簡単です。 complfuncは補完開始位置を拡張プラグイン側で計算しないといけません。 その代わり、補完開始位置は自由に決定できるので、ファイル名補完のような複雑な補完を実装できます。 初期のneocomplcacheでは、complfuncは一つのプラグインしか呼べないという制限がありました。 現在のバージョンでは、complfuncの候補も統合できるように改良されているため、そのような制限はありません。

標準添付のplugin

buffer_complete.vim

開いているバッファから補完候補を収集するプラグインです。バッファ内の単語を解析することで、使用頻度の学習も行います。

dictionary_complete.vim

g:NeoComplCache_DictionaryFileTypeListsから補完候補を収集するプラグインです。

include_complete.vim

バッファで開いているインクルードファイルから補完候補を収集するプラグインです。Vimにもインクルード補完はありますが、より拡張されています。

snippets_complete.vim

スニペットを補完するプラグインです。補完するだけではなく、単体でスニペット展開プラグインとしても動作します。

syntax_complete.vim

シンタックスファイルからキーワードを補完するプラグインです。Vim標準添付のsyntaxcomplete.vimよりも高機能であり、結果をキャッシュするので高速です。複雑なTeXのシンタックスも解析できます。

tags_complete.vim

タグファイルからキーワードを補完するプラグインです。

標準添付のcomplfunc

completefunc_complete.vim

補完関数を登録することで、自動呼び出しするプラグインです。neocomplcacheはcompletefuncを上書きしてしまうので、その対策に使えます。 手動補完として補完関数を個別に呼び出しすることもできます。

filename_complete.vim

ファイル名を補完するプラグインです。詳しい解説は、[Hack #119: neocomplcache Hacks(2) オムニ補完]を参照してください。

keyword_complete.vim

pluginから候補を収集し、キーワードを補完するプラグインです。

omni_complete.vim

オムニ補完を呼び出し、候補を収集するプラグインです。詳しい解説は、[Hack #119: neocomplcache Hacks(2) オムニ補完]を参照してください。

vim_complete.vim

Vimのオムニ補完機能を提供するプラグインです。Vim標準の<C-x><C-v>よりも機能が拡張されていて、ローカル変数や引数の補完も可能です。

オムニ補完とは

オムニ補完とは、Vim組み込みで用意されている補完とは違い、文脈を解析して行う補完です。関数を'omnifunc'に設定し、<C-x><C-o>のキーシーケンスを入力することで呼び出されます。標準でもいくつかの言語のオムニ補完関数が用意されていますが、ユーザーが自分で定義することができます。

inoremap <expr><C-x><C-o> &filetype == 'vim' ? "\<C-x><C-v><C-p>" : neocomplcache#manual_omni_complete()

私はこのようにキーマッピングを設定し、Vim組み込みのオムニ補完を置き換えています。

拡張機能

neocomplcacheのオムニ補完には次のような拡張機能があります。

自動補完の文脈定義

g:NeoComplCache_OmniPatterns[filetype]を設定すれば、呼び出し条件をカスタマイズしたり、呼び出しを無効化することができます。

多数の言語に対応

AutoComplPopでは標準でPerl/Ruby/html/CSS/Pythoのオムニ補完が可能です。neocomplcacheではPerl以外の確認できたすべての言語に対応しています。キーワードパターンに追加するだけなので、新たな言語に対応させることが容易です。

補完スキップ

g:NeoComplCache_EnableSkipCompletionが1ならば（デフォルト）、候補の取得に時間がかかりすぎる場合、補完をスキップすることができます。

ワイルドカード

ほかの補完と同様、ワイルドカードによる絞り込みに対応しています。

エラーを出さない

特定のオムニ補完では、変な場所で呼び出すとエラーを出したりすることがあります。neocomplcacheではエラーをcatchしているので、neocomplcache内部にバグがない限り、オムニ補完中にエラーになることはありません。

補完環境の厳密な判定

PythonやRubyのオムニ補完は:pythonや:rubyが正常に動作する環境でなければ動作しません。よって、内部で判定しています。

ファイル名補完やバッファ名補完との同時呼び出し

オムニ補完とほかの補完を同時に呼び出せないAutoComplPopとは違い、neocomplcacheのオムニ補完はほかの補完と統合されています。 よって、同時に候補を出すことができるので、さらに便利に使えます。 ただし、オムニ補完の開始パターンが先にマッチした場合、オムニ補完の候補のみが計算されて表示されます。 これはVim自体の仕様です。これを防ぐためには、一度補完のポップアップを閉じて、補完を再呼び出しするしかありません。

キーワードの収集

空文字列でオムニ補完を呼び出してキーワードを収集してキャッシュし、オムニ補完候補として利用することができます。

neocomplcacheからオムニ補完関数を呼び出すときの注意

neocomplcacheは大抵のオムニ補完関数に対応していますが、オムニ補完関数を内部で無理矢理呼んで変換するという動作を行っているので、呼び出す関数によっては補完がうまく働かないことがあります。現在、complete_add()関数を内部で呼んでいる場合には動作がおかしくなることがわかっています。これはオムニ補完関数側がcomplete_add()を呼ばないようにするしかありません。 他に、Rubyのオムニ補完は時々フリーズする現象があることが報告されています。 これはRubyのオムニ補完が外部インタフェースを内部で使用しているためだと思われます。 Vimの外部インタフェース機能は不安定なので、時々エラーをはいたりフリーズすることがあります。 無効にしたい場合は.vimrcで

if !exists('g:NeoComplCache_OmniPatterns')
let g:NeoComplCache_OmniPatterns = {}
endif
let g:NeoComplCache_OmniPatterns['ruby'] = ''

と設定すると、無効にできます。これでは不便なので、Rubyのオムニ補完を書き直してくれる人を現在募集中です。

ファイル名補完とは

ファイル名補完とは、Vim組み込みで用意されているファイル名補完を置き換えるためにneocomplcache上で実装した補完です。Ver.3.0より機能が分離され、neocomplcacheの１プラグインとなっています。を解析して候補を出すため、組み込みのファイル名補完と同じように動作しますが、機能が大幅に拡張されています。特にファイル名を指定するときや、シェル拡張系のプラグインを使用するときに効果を発揮します。

inoremap <expr><C-x><<C-f>  neocomplcache#manual_filename_complete()

私はこのようにキーマッピングを設定し、Vim組み込みのファイル名補完を置き換えています。

拡張機能

neocomplcacheのファイル名補完には次のような拡張機能があります。

ワイルドカードに対応

＊.txtのような、ワイルドカード文字が補完に使えます。 実行ファイル、読み取り専用ファイル、ディレクトリの表示 表示をわかりやすくするため、ファイルの種類を判別し、実行ファイルには＊を、読み取り専用ファイルには[-]を、ディレクトリには/をそれぞれ付加します。 Windowsでは$PATHEXTを参照するので、より正確な判別が可能です。

短縮ファイル名補完

/u/s/lのようにディレクトリの先頭名だけ入力することで、/u＊/s＊/lのように解釈されます。素早く補完したいときに便利ですが、候補が多いと重くなります。

補完スキップ

g:NeoComplCache_EnableSkipCompletionが1ならば（デフォルト）、ファイル名の取得に時間がかかりすぎる場合、補完をスキップすることができます。

Cygwin対応

Vim組み込みのファイル名補完では/cygdrive/の入力で補完が重くなってしまいますが、neocomplcacheのファイル名補完では対策されています。

…->../..変換

…を../..に変換して解釈することができます。上のディレクトリを参照するときに便利です。

_, -, .による区切り補完

_, -, .を区切り文字として曖昧補完ができます。たとえば、h_.txtはh_.txtと同じ意味です。

環境変数を展開しない

組み込みのファイル名補完の場合、環境変数が勝手に展開されてしまうので、逆に邪魔になってしまうことが多々あります。neocomplcacheのファイル名補完は環境変数とマッチする部分はそのままにするので、便利に使うことができます。

zshとの比較

neocomplcacheのファイル名補完は自動的に候補が表示できるのが一番の魅力で、特にvimshellとの連携はすばらしいです。zshでも設定すれば自動補完ができないことはないのですが、誤爆の可能性も高く、おすすめできません。自動でファイル名補完ができることに慣れてしまうと、いちいち<TAB>を連打しなくてはいけないシェルの補完が煩わしく感じることでしょう。

vimshellとの併用

neocomplcacheのファイル名補完は元々vimshell上で利用するために作られました。vimshellとはVim上でシェルを実装したプラグインです。neocomplcacheとは独立していますが、neocomplcacheがインストールされている場合、補完時にneocomplcacheの機能を使用します。vimshellはneocomplcacheと比較しても複雑なプラグインなので、機会があれば詳しく解説したいと思います。

今日は neocomplcache-4.0.3/autoload/neocomplcache.vim を読みました。

勉強会チャットログはこちら: http://lingr.com/room/vim/archives/2009/12/22

特にしっかりと読んだ関数:

• function! neocomplcache#enable()
• function! s:complete()
• function! s:integrate_completion(complete_result)

APIとなるneocomplcache#ではじまる関数群がautoload/neocomplcache.vimの上部にまとめて定義されています。 また、内部で使う関数群が続いて下部にスクリプトローカルで定義されています。

興味深い部分の抜粋:

echo ''
redraw

redraw!だと画面がちらつくので、そういうときはこの二行で、ということだそうです。

まとめ

“neocomplcacheのソースコードは魔界“

コード自体はすばらしく整理されているものの、 Vim自体とその周囲の問題を解決するために涙が止まらない努力が随所に見られます。

• ATOK
• 画面のチラツキ
• 速度 (skip)
• プラグイン
• 補完の統合
• 頻度解析