Title: Auto Complete Modeユーザーマニュアル
Numbering: yes
CSS: style.css
Auto Complete Modeユーザーマニュアル
====================================
[Index](index.ja.txt)
\[[English](manual.txt)]
* * * *
{toc}
* * * *
はじめに
--------
Auto Complete Mode（通称、`auto-complete.el`, `auto-complete-mode`）は[GNU Emacs][]（以下Emacs）の補完システムを自動化・高度化する拡張です。従来の補完システムと比べて以下の点で優れています。
* 視覚的な操作感
* 統計的手法による補完オーバーヘッドの削減
* 拡張性
本マニュアルはインストール方法から基本的な使い方・設定方法、また拡張方法までを網羅しています。不明な点があれば開発者まで連絡をください。
なお、Auto Complete Modeは[GPLv3][]のもとでライセンスされています。また、このドキュメントは[GFDL][]のもとでライセンスされています。
ダウンロード
------------
[Auto Complete Modeのトップページ](index.ja.txt)からダウンロードできます。
インストール
------------
### 必要条件 ###
* 800MHz以上のCPU
* 256MB以上のメモリ
* GNU Emacs 22以上
### インストールスクリプト ###
パッケージディレクトリ内の`etc/install.el`というインストールスクリプトを利用すれば簡単にインストールを行うことができます。
起動中のEmacsあるいは新しく起動したEmacsで`M-x load-file RET`と入力してください。なお`auto-complete-mode`をアップグレードする場合は**`-q`オプションで新しく起動したEmacs**でインストールを行ってください。`auto-complete-mode`ロードするファイル名を尋ねられるのでアーカイブを展開したディレクトリに`/etc/install.el`を追加したフルパスを入力します。例えば展開したディレクトリのパスが`~/tmp/auto-complete-1.2`である場合、`~/tmp/auto-complete-1.2/etc/install.el`と入力します。
次にインストール先のディレクトリを尋ねられますので、お好みディレクトリを入力してください。このディレクトリが`load-path`に設定されていない場合は後で設定する必要があります。デフォルトでは`~/.emacs.d`です。
最後に`RET`を押してインストールを開始してください。インストールが完了すると次のようなバッファが表示されるので、指示に従って`.emacs`を編集してください。
あるいは、次のようにターミナルからインストールすることもできます。
$ make install
$ # あるいはディレクトリをあらかじめ指定して
$ make install DIR=$HOME/.emacs.d/
GNU Makeがない場合は次のようにします。
$ emacs -batch -l etc/install.el
**インストール後のメッセージ例（\*Installation Result*バッファ）**
Successfully installed!
Add the following code to your .emacs:
(add-to-list 'load-path "~/.emacs.d") ; load-pathにすでに設定されている場合は表れません
(add-to-list 'ac-dictionary-directories "~/.emacs.d/ac-dict")
(require 'auto-complete-config)
(ac-config-default)
### 手動によるインストール ###
ディレクトリ構成と設定が正しければ手動によるインストールも可能です。まず展開したディレクトリにおいて全ての`.el`ファイルに対してバイトコンパイルを実行してください。UNIX系OSであれば同封の`Makefile`を利用できると思います。
$ make byte-compile
`Makefile`を利用できない場合は、Emacsから`C-x d`で展開したディレクトリを開き`* . el RET B RET`で`.el`ファイルをバイトコンパイルしてください。
次に全て`.el`ファイルと`.elc`ファイルを`load-path`が通ったディレクトリにコピーします。例えばそのディレクトリが`~/.emacs.d`であれば次のようなコマンドを実行します。
$ cp *.el *.elc ~/.emacs.d
次に辞書ファイルをインストールします。このファイルがなくても動作しますが、特に理由がなければインストールしたほうがよいでしょう。辞書ファイルは`dict`ディレクトリに格納されており、`auto-complete.el`がインストールされたディレクトリと同じディレクトリにインストールされる必要があります。例えば`auto-complete.el`を`~/.emacs.d`にインストールしたのであれば、`~/.emacs.d`に`dict`ディレクトリをコピーします。この際、既存のファイルを上書きしないようにしてください。おそらくそのようなケースは起こらないと思いますが、上記のインストールスクリプトでは`ac-dict`という名前のディレクトリに辞書ファイルを格納することにより、他のファイルを上書きしたり干渉する可能性を最小限にしています。
$ cp -r dict ~/.emacs.d
最後に`.emacs`に次のような設定を記述します。
(add-to-list 'ac-dictionary-directories "~/.emacs.d/dict")
(require 'auto-complete-config)
(ac-config-default)
`load-path`の設定が行われていない場合は次のコードも記述する必要があります。
(add-to-list 'load-path "~/.emacs.d")
### 動作確認 ###
Emacsを再起動するか新規に起動して\*scratch\*バッファで適当な文字を入力してください。補完メニューが表われて補完が開始されればインストール成功です。エラーが出たり補完が開始されない場合は以下のことを確認した後、開発者に連絡してください。
* `load-path`は正しいか
`auto-complete.el`をインストールしたディレクトリが`load-path`に設定されているかどうか。
* モードラインに`AC`という文字があるか
モードライン（バッファ下部の灰色の行）に`AC`という文字がない場合は`auto-complete-mode`が有効になっていない可能性があります。`M-x auto-complete-mode`で有効にして再度試してください。
* エラーが発生
\*Backtrace*バッファにエラーが表示されたり、ミニバッファ（フレーム下部の入力欄）にエラーメッセージが表示された場合は、その内容を添付のうえ開発者に連絡してください。
基本的な使い方
--------------
出鼻をくじくようですが、ある意味では`auto-complete-mode`には「使い方」が存在しません。というのも、Emacsの編集システムに自然に溶け込むように`auto-complete-mode`が設計されているからです。ユーザーは快適な編集操作を邪魔されることなく、高度な補完機能を自動的に享受することができるのです。究極的には、ユーザーのいかなる指示もなしにユーザーが望むように自動的に補完することが目標となりますが、100%の補完推測は現実的に不可能です。その点をカバーするために若干の「使い方」が存在します。この節ではその「使い方」を説明します。
### 文字入力 ###
まず基本となるのが文字入力です。文字が入力されなければ補完もできません。ではどの文字が入力されたときに補完が開始されるのかという疑問がわくと思いますが、それを説明するのは難しいのでここでは割愛します。簡単に言えば、キーの押し込みによる単純な文字追加時に補完が開始されます。詳しくは[`ac-trigger-commands`](#)を参照してください。
### TABによる補完 ####
補完が開始されるとTABによる補完が一時的に有効になります。TABによる補完は`auto-complete-mode`において最も重要で最もよく使う操作です。TABは状況によって様々な意味を持ちます。
* 補完候補が一つしかない場合
補完候補が一つの場合は、その補完候補で補完を実行します。
* 補完候補に共通部分がある場合
例えばsという単語の補完候補が全てsetではじまる場合、その共通部分はsetであると解釈され、TABによってsetまで展開されます。
* その他の場合
その他の場合、TABを押すごとに補完候補を先頭から順繰りで選択していきます。補完候補の末尾にきたら再び補完候補の先頭から選択していきます。
設定によって若干挙動が異なりますが、基本的にはこのような挙動になります。このようにTABに様々な意味を持たせるのは、TABのみで全て完結させようという狙いがあります。
### RETによる補完 ###
TABによる補完と似ていますが、RETによる補完は以下の点で異なります。
* 選択中の補完候補で即時補完する
* 補完候補にアクションが設定されている場合に、そのアクションが実行される
TABによる補完では共通部分の展開などで何度かTABを押す必要があります。RETによる補完では選択中の補完候補で即時に補完されるので、目的の補完候補であると視認したならRETを押すとよいでしょう。その際、アクションというのものが実行される可能性がありますが、ここでは詳しくは触れません。アクションの例としては、標準添付の略語補完が分かりやすいでしょう。wwwをWorld Wide Webと展開する略語が登録されている時、wという単語でwwwを補完することができますが、RETによる補完の場合は、さらに略語展開を行いWorld Wide Webと補完します。つまりTABによる補完ではwwwが最終的な補完結果になり、RETによる補完ではWorld Wide Webが最終的な補完結果になります。
### 補完候補の選択 ###
`auto-complete-mode`の考え方に従えば、補完候補の選択は推奨されるものではありません。なぜなら、その時点でユーザーの補完推測に失敗しており、さらにユーザーに補完候補を選択させるというオーバーヘッドの高い操作を要求しているからです。補完候補の選択はTABによる補完でもある程度補うことができ、さらに最近のバージョンでは統計的手法によって補完推測の精度があがっているので、補完候補の選択が必要になるケースはそれほど多くないと考えられます。しかし、実際にそのようなケースは存在するので、補完候補の選択方法を覚えておくのも悪いことではないかもしれません。
前置きが長いですが、補完候補の選択自体は難しい操作ではありません。補完中にカーソルキーあるいは`M-p`, `M-n`で前後に選択することができます。設定によりますが、補完候補の選択が行われた後はTABによる補完がRETによる補完に近い挙動に変化します。詳しくは[`ac-dwim`](#)を参照してください。
その他の方法としてMetaキーと数字の組合せで選択することもできます。例えば`M-1`を押せば1番目の候補を選択して補完します。これもオーバーヘッドが大きいので極力使わないでください。
### ヘルプ ###
`auto-complete-mode`には*クイックヘルプ*と*バッファヘルプ*の二つのヘルプ機能が備え付けられています。両者の違いは見せ方だけです。クイックヘルプは補完メニューのすぐ隣に表示するので、視線の移動が最小限で済むというメリットがありますが、表示領域が狭すぎると可読性が低くなるというデメリットがあります。またクイックヘルプは補完メニューを表示してからしばらく待つと自動的に表示されます。クイックヘルプを利用するには[`ac-use-quick-help`](#)を`t`にしておく必要があります。表示までの時間は[`ac-quick-help-delay`](#)で制御できます。
一方、ユーザーが明示的に命令することで表示されるのがバッファヘルプです。バッファヘルプはその名の通り、別ウィンドウにヘルプ用バッファを表示します。クイックヘルプに比べて視線の移動が大きい分、、可読性に優れています。バッファヘルプを表示するには補完中に`C-?`あるいは`f1`を押します。バッファヘルプ表示後はさらに`C-M-v`あるいは`C-M-S-v`でバッファヘルプの上下スクロールが可能です。それ以外の命令の場合はバッファヘルプを閉じてフォールバックします。
### まとめ ###
補完は文字の入力によって開始されます。補完が開始されると次の表に示す操作が時的に有効になります。補完が完了したら、これらの操作は無効になります。
| キー | コマンド | 説明 |
|-----------|-------------|--------------------------|
| TAB, C-i | ac-expand | TABによる補完を実行する |
| RET, C-m | ac-complete | RETによる補完を実行する |
| down, M-n | ac-next | 次の候補を選択する |
| up, M-p | ac-previous | 前の候補を選択する |
| C-?, f1 | ac-help | バッファヘルプを表示する |
補完を途中で中断するには`C-g`を使うとよいでしょう。
高度な使い方
------------
前節に引き続いて、もう少し高度な使い方を説明します。とはいってもあくまでユーザーの視点での話なので、`auto-complete-mode`を意のままに操りたいという方は、次節以降を読み進めるとよいでしょう。
### `auto-complete`コマンド ###
基本的に`auto-complete-mode`は自動的に補完を開始するという前提がありますが、その限りではない場合もあります。例えば、文字は入力しないけど補完はしたいという場合や、設定によって自動的に補完が開始されないようにしている場合などです。そのような時に利用するのが`auto-complete`というコマンドで、普通は何らかのキーに割り当てて利用します。例えば従来の`M-TAB`による補完を、`auto-complete-mode`が提供するより高度な補完に切り替えるには次のコードを評価します。
(define-key ac-mode-map (kbd "M-TAB") 'auto-complete)
さて、`auto-complete`コマンドに関してですが、これは通常の自動的な補完とは若干異なる挙動になっています。
* 補完候補が一つしかない場合
補完メニューを表示しないで、そのまま補完を実行します。
* 補完候補が一つもない場合
曖昧マッチによる補完を試みます。詳しくは[曖昧マッチによる補完](#)を参照してください。
* その他の場合
その他の場合、全体共通部分を展開しつつ補完メニューを表示して補完を開始します。その後の操作は自動的に補完が開始された場合と同じになります。[`ac-show-menu-immediately-on-auto-complete`](#)と[`ac-expand-on-auto-complete`](#)も参照してください。
### 曖昧マッチによる補完 ###
`auto-complete`コマンドで補完候補が一つもない場合や`ac-fuzzy-complete`コマンドが実行された場合、通常の確実なマッチではなく曖昧なマッチによって補完を試みます。曖昧マッチのパラメータはあらかじめ最適化されているのでユーザーが変更する必要はありませんが、内部を知りたい場合は`fuzzy.el`を参照してください。曖昧マッチによる補完を利用すれば、タイポも補完の一環として修正することができます。例えば適当なバッファでmessaegと入力して`M-x auto-complete`あるいは`M-x ac-fuzzy-complete`してください。曖昧マッチに成功したらカーソルの色が赤色に変化し、messaegではなくmessageであると解釈して補完を継続することができます。このようなケースにすぐさま対処するという意味でも`auto-complete`コマンドを何らかのキーに割り当てておくのは決して悪いことではありません。
### 補完候補の絞り込み ###
補完中に`C-s`を押すことで絞り込みを開始できます。絞り込みが開始されるとカーソルの色が青色に変化します。その後に続いて絞り込む文字列を入力していきます。絞り込みはインクリメンタルに更新されるので直感的に理解できると思います。絞り込みの最中でもTABによる補完や候補選択を行うことができます。その際、カーソルの色が元に戻りますが、これは絞り込みが終了したことを意味しています。再度`C-s`を押したときは、前回の絞り込み文字列が復元されます。絞り込み文字列を削除するには`DEL`または`C-h`を押してください。それ以外の一般的な編集操作はここでは利用できません。
### トリガーキー ###
`auto-complete`コマンドをどのキーに割り当てるかは結構難しい問題です。補完という操作は頻繁に行うため、できるだけ押しやすいキーに割り当てるべきです。しかし押しやすいキーはすでに他のコマンドに割り当てられているというのはEmacsでは非常によくあることなのです。そういうケースに対処するため`auto-complete-mode`はトリガーキーと呼ばれる機能を提供しています。トリガーキーを利用すれば、任意のキーを必要なときに一時的にのっとって`auto-complete`コマンドに割り当てることができます。例えばTABをトリガーキーに設定するには次のようになります。
(ac-set-trigger-key "TAB")
トリガーキーは文字入力の直後に有効になります。それ以外の場合は通常のコマンドが実行されます（TABならインデント）。通常、トリガーキーは`ac-auto-start`を`nil`にして利用します。
(setq ac-auto-start nil)
`ac-auto-start`に関しては[自動的に補完しない](#)あるいは[`ac-auto-start`](#)を参照してください。
### 補完推測機能 ###
`auto-complete-mode`はユーザーの補完行動を逐一解析して、可能な限り補完のオーバーヘッドを削減しようとします。具体的には、例えば何度か`foobar`が補完されれば、次回以降は`foobar`が補完候補の上位に配置され、一回あるいは数回以内のTABで補完できる環境を作ります。内部的には`comphist`と呼ばれる機構を使っており、`ac-use-comphist`が`t`の場合にこの機能が有効になります。デフォルトでは有効になっています。収集された行動データは`user-emacs-directory`あるいは`~/.emacs.d`に`ac-comphist.dat`というファイル名で永続化され、次回以降も再利用されます。
優れた補完推測を実現するため、次の二つのデータを収集します。
* その補完候補が補完された回数
* その補完候補が補完された位置
簡単に言えば、単純に補完回数を数えるのではなく、補完位置ごとに補完回数を数えていき、その補完候補のスコアは補完されている位置との比較でうまく重み付けされます。例えばfと入力して`find-file`を補完するという行動を何度か繰り返せば、fを入力した段階で`find-file`が上位に配置されます。ただ、続けてfind-と入力したときに`find-file`が先ほどと同じスコアになるかといえば、そういうわけではなく、先ほどと位置として4離れているわけですから、それだけ重み付けが軽くなります。逆にfind-の後に`find-library`が補完されやすい場合は、そちらの補完候補のスコアのほうが上位に来る可能性が高くなるので、結果的にfの時点では`find-file`が上位に、find-の時点では`find-library`が上位に来るといった、ユーザーの行動を学習したかのような推測が可能になるわけです。
ユーザーはこの機能をできるだけ活用するために、よく入力する単語はできるだけ前の位置で補完するように心がけてください。また、できるだけ行動は一貫してください。補完位置が毎回変わるようではうまく学習できないからです。おそらくあまり気にせず使っていれば、自動的にそのような行動になるでしょう。
### 辞書による補完 ###
辞書とは単純な文字列のリストのことであり、それぞれユーザー定義辞書、メジャーモード辞書、拡張子辞書の3つがあります。なお、辞書による補完を利用するには情報源に`ac-source-dictionary`を設定しておく必要があります（デフォルトでは設定済み）。詳しくは[情報源](#)を参照してください。
#### ユーザー定義辞書 ####
ユーザー定義辞書は`ac-user-dictionary`に設定された文字列リストおよび`ac-user-dictionary-files`で指定された辞書ファイルで構築されます。辞書ファイルは改行で区切られた単語の一覧です。ユーザー定義辞書は全てのバッファで共通です。例えば自分のメールアドレスを辞書に登録する場合、次のように`ac-user-dictionary`に単語を追加します。
(add-to-list 'ac-user-dictionary "[email protected]")
設定は直ちに反映されます。試しに適当なバッファで`foo`と入力してください。`[email protected]`が補完候補になると思います。この設定はEmacsを終了したら消去されます。永続化させるためには`.emacs`に記述しておく必要があります。
(setq ac-user-dictionary '("[email protected]" "[email protected]"))
もっと分かりやすいのは辞書ファイルを利用する方法です。`ac-user-dictionary-files`に指定されているファイルは辞書ファイルとして扱われます。デフォルトで`~/.dict`が辞書ファイルになるので、`~/.dict`を開いて次のように記述してください。
[email protected]
[email protected]
前述したように改行が単語の区切りになります。保存してもすぐには反映されません。コストの高い辞書ファイルの読み込みを抑えるためにキャッシュを使っているからです。キャッシュを消去するには`M-x ac-clear-dictionary-cache`を実行します。後は先ほどと同じように適当なバッファで文字を入力すれば定義した単語を補完できるようになると思います。
言うまでもないかもしれませんが、`ac-user-dictionary-files`に任意の辞書ファイルを追加することで、違う辞書ファイルを読み込むことも可能です。
#### メジャーモード辞書・拡張子辞書 ####
メジャーモードや拡張子ごとに違う辞書を利用することもできます。辞書は`ac-dictionary-directories`に設定されたディレクトリから読み込まれます。`ac-dictionary-directories`は[インストール](#)時に次のように設定しているはずです。
(add-to-list 'ac-dictionary-directories "~/.emacs.d/ac-dict")
このディレクトリにはc++-modeのようなメジャーモードのための辞書ファイルやtxtのような拡張子のための辞書ファイルが格納されています。例えば`a.cpp`というバッファで辞書による補完を利用する場合、上記の設定を前提にすれば、`~/.emacs.d/ac-dict/c++-mode`と`~/.emacs.d/ac-dict/cpp`から辞書が読み込まれます。ユーザーはこれらの辞書ファイルを変更することができますし、また新しく追加することもできます。さらに、同様の構成のディレクトリを作成して`ac-dictionary-directories`に追加することで、辞書ファイルを追加することも可能です。この際、`ac-dictionary-directories`の先頭にあるディレクトリが優先されることに気をつけてください。
ユーザー定義辞書と同様、辞書の追加・編集後は`M-x ac-clear-dictionary-cache`でキャッシュを消去してください。
情報源
------
`auto-complete-mode`の拡張性を保証しているのがこの情報源という概念です。*情報源*とは簡単に言えば、下記する事柄をひとまとめに記述したものと言えます。
* どのような補完候補を生成するか
* どのように補完するか
* どのように表示するか
Emacs Lispについて若干の知識があれば誰でも簡単に情報源を定義することができます。情報源の定義に関しては[拡張方法](#)を参照してください。ここでは情報源の利用方法と標準添付されている情報源について説明します。
情報源の名前は`ac-source-`で始まる慣習となっています。そのため`apropos`を使ってどのような情報源が定義されているか調べることができます（`M-x apropos RET ^ac-source-`)。`ac-source-filename`や`ac-source-dictionary`などが見付かると思いますが、これらが情報源と呼ばれる実体になっています。
### 情報源を利用する ###
`.emacs`に`(ac-config-default)`を記述している場合、デフォルトで最適な設定が使われるので、おそらく情報源の設定を変更するケースはまれだと思いますが、一応簡単に触れておきます。情報源は`ac-sources`という変数にリストとして設定されます。インストール直後に\*scracth*で`ac-sources`を評価すると次のような結果になると思います。
;; 整形済み
(ac-source-filename
ac-source-functions
ac-source-yasnippet
ac-source-variables
ac-source-symbols
ac-source-features
ac-source-abbrev
ac-source-words-in-same-mode-buffers
ac-source-dictionary)
見てのとおり、\*scratch\*バッファの`ac-sources`には6つの情報源が設定されていることがわかります。それぞれの説明は後述しますが、大体の意味は推測できるでしょう。大事なことなので記憶しておいてほしいのですが、`ac-sources`はバッファーローカル変数になっており、バッファごとに独立した設定を許可しています。つまりあるバッファで`ac-sources`を変更しても、他のバッファには影響がないことになります。
例を示します。今、\*scratch\*バッファにいると考えてください。上記のように、このバッファには多くの情報源が設定されています。多機能すぎると感じるユーザーもいるでしょう。そこで、もう少し機能を制限するために`ac-sources`の変更を考えます。変更方法は簡単で、次のようなコードを\*scratch\*バッファあるいは`M-:`で評価するだけです。
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers))
この例では、`ac-sources`を減らして、シンボル補完と同一メジャーモード間での単語補完のみを有効にしました。さて、これを次のEmacsの起動時にも有効にするにはどうしたらよいのでしょうか。\*scratch\*バッファ作成時に`emacs-lisp-mode-hook`というフックが実行されるので、このフックに適当な関数を追加するのがよいでしょう。
(defun my-ac-emacs-lisp-mode ()
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
(add-hook 'emacs-lisp-mode-hook 'my-ac-emacs-lisp-mode)
`.emacs`に`(ac-config-default)`が記述されている場合は、上記の方法では正しく動作しないかもしれません。というのも`(ac-config-default)`内部で同様のことを行っているので、どちらかが設定を上書きしてしまうからです。その場合は`(ac-config-default)`で利用する関数を再定義してしまうのがよいでしょう。`emacs-lisp-mode`の場合は、その関数名は`ac-emacs-lisp-mode-setup`です。詳しくは`auto-complete-config.el`を参照してください。
(defun ac-emacs-lisp-mode-setup ()
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
さて、これで特定のメジャーモードで情報源を変更する方法が分かったと思います。まとめると次のようになるでしょう。
1. `ac-sources`を変更する関数を定義する
2. `add-hook`で適当なモードフックにその関数を登録する（`c++-mode-hook`, `ruby-mode-hook`, `python-mode-hook`など）
では、全てのバッファに対して`ac-sources`を設定するにはどうしたらよいのでしょうか。その場合は`setq`ではなく`setq-default`で`ac-sources`を設定します。そうするとバッファローカル変数である`ac-sources`のデフォルト値が設定した値になります。
(setq-default ac-sources '(ac-source-words-in-all-buffer))
他にも方法があります。`(ac-config-default)`は`auto-complete-mode`のフックである`auto-complete-mode-hook`に関数を追加することにより、`setq-default`によるデフォルト値の変更に近いことをやっています。その関数は`ac-common-setup`であり、`ac-sources`の先頭に`ac-source-filename`という情報源を追加しています。これにより`auto-complete-mode`が有効な全てのバッファで`ac-source-filename`が情報源の先頭に追加されます。なぜ先頭なのかというと、これにはオムニ補完の仕様が関係しているのですが、とりあえずここでは気にしなくてもいいです。つまるところ、`(ac-config-default)`を使っていて共通して`ac-sources`を変更したい場合は、この`ac-common-setup`関数を再定義することも一つの手段となります。
;; 全てのバッファの`ac-sources`の末尾に辞書情報源を追加
(defun ac-common-setup ()
(setq ac-sources (append ac-sources '(ac-source-dictionary))))
### 標準情報源 ###
`auto-complete.el`および`auto-complete-config.el`に定義されている情報源の一覧です。
#### `ac-source-abbrev` ####
Emacsの略語機能のための情報源です。略語機能に関しては`info emacs Abbrevs`を参照してください。
#### `ac-source-css-property` ####
CSSプロパティのための情報源です。
#### `ac-source-dictionary` ####
辞書のための情報源です。辞書に関しては[辞書による補完](#)を参照してください。
#### `ac-source-eclim` ####
[Emacs-eclim](http://github.com/senny/emacs-eclim)のための情報源です。
#### `ac-source-features` ####
`(require '`で有効なfeatureを補完するための情報源です。
#### `ac-source-filename` ####
ファイル名を補完するための情報源です。`/`を入力した時点で補完が開始されます。
#### `ac-source-files-in-current-dir` ####
カレントディレクトリのファイルを補完するための情報源です。`eshell`などで便利かもしれません。
#### `ac-source-functions` ####
Emacs Lispの関数を補完するための情報源です。`(`の直後で有効です。
#### `ac-source-gtags` ####
[Global](http://www.tamacom.com/global.html)のタグを補完するための情報源です。
#### `ac-source-imenu` ####
`imenu`ノードを補完するための情報源です。詳しくは`info emacs imenu`を参照してください。
#### `ac-source-semantic` ####
[Semantic](http://cedet.sourceforge.net/semantic.shtml)のための情報源です。C/C++でメンバー名補完として利用できます。
#### `ac-source-semantic-raw` ####
`ac-source-semantic`と違って、この情報源は生の名前空間でシンボルを補完するのに使います。
#### `ac-source-symbols` ####
Emacs Lispのシンボルを補完するための情報源です。
#### `ac-source-variables` ####
Emacs Lispの変数を補完するための情報源です。
#### `ac-source-words-in-all-buffer` ####
全てのバッファの単語を補完するための情報源です。[`ac-source-words-in-same-mode-buffers`](#)と違って、メジャーモードを考慮しません。
#### `ac-source-words-in-buffer` ####
現在のバッファの単語を補完するための情報源です。
#### `ac-source-words-in-same-mode-buffers` ####
現在のバッファと同じメジャーモードの全てのバッファの単語を補完するための情報源です。例えば`a.cpp`と`b.cpp`では単語が共有されますが、`a.pl`と`b.cpp`ではメジャーモードが異なるので単語が共有されません。通常は[`ac-source-words-in-all-buffer`](#)よりこちらのほうが使い勝手がよいでしょう。
#### `ac-source-yasnippet` ####
[Yasnippet](http://code.google.com/p/yasnippet/)のスニペットを補完・展開するための情報源です。
Tips
----
### 自動的に補完しない ###
補完メニューが現われたり消えたりすると、編集操作に集中できないというユーザーがいます。私の経験では得てしてEmacsの上級ユーザーなのですが、とにかく`auto-complete-mode`はそのような用途も想定しています。次のように`ac-auto-start`をnilにすることにより自動的に補完されなくなります。
(setq ac-auto-start nil)
この際、`auto-complete`コマンドを何らかのキーに割り当ておくべきです（じゃないと補完できないので）。例えば次のように`ac-mode-map`（`auto-complete-mode`が有効なバッファで利用できるキーマップ）に割り当てたり、
(define-key ac-mode-map (kbd "M-TAB") 'auto-complete)
あるいはグローバルキーマップに割り当てるのもよいでしょう。
(global-set-key "\M-/" 'auto-complete)
また、自動的に補完してもいいけど、もう少し長い単語のときだけ補完を開始するということも可能です。例えば4文字以上の単語のときに補完を開始するには`ac-auto-start`に4を設定します。
(setq ac-auto-start 4)
`ac-auto-start`を大きめの数値に設定するのはパフォーマンスに良い影響をもたらします。`ac-auto-start`が小さい数値だと、必然的に補完候補数が増えるので、それだけ補完候補の生成にかかるコストが大きくなります。もし`auto-complete-mode`が重いと感じるなら`ac-auto-start`に大きめの数値を設定するか`nil`を設定するとよいでしょう。
`ac-auto-start`に関しては[`ac-auto-start`](#)を参照してください。
また[トリガーキー](#)を利用も考慮してみてください。
### 補完メニューを自動で表示しない ###
補完メニューによって集中力が削がれる問題のもう一つの対処としては、補完メニューを表示しないという方法が考えられます。補完メニューを非表示にするには[`ac-auto-show-menu`](#)を`nil`にします。
(setq ac-auto-show-menu nil)
これで補完メニューは自動で表示されなくなりますが、補完候補の選択や絞り込みを行うと補完メニューは表示されます。
あるいは補完メニューの表示を遅延させることにより、補完メニューが必要な時だけ自動で表示させるようにすることも可能です。そのためには`ac-auto-show-menu`に実数で遅延する時間を秒単位で設定します。
;; 0.8秒後に自動で表示
(setq ac-auto-show-menu 0.8)
このインターフェースはデフォルトの完全自動補完と上記した非自動補完のよいところだけを組合せたものと言えます。将来はこれがデフォルトになるかもしれません。
### 補完を中止する ###
補完の中止は`C-g`で行うことができますが、マクロ定義中などは`C-g`したくないでしょう。そのような場合は`ac-completing-map`に補完を中止するキーを割り当てるとよいでしょう。
(define-key ac-completing-map "\M-/" 'ac-stop)
これで補完中でも`M-/`で中止することができます。
### TABで補完を完了する ###
上記したようにTABには様々な挙動が定義されています。`auto-complete-mode`を正しく使いこなすにはTABとRETによる補完を使いわけなければなりませんが、RETはそのまま改行でTABで補完完了するといった単純な操作方法も十分考えられます。。そのような場合は次のように設定します。
(define-key ac-completing-map "\t" 'ac-complete)
(define-key ac-completing-map "\r" nil)
### 補完メニュー表示時のみC-n/C-pで補完候補を選択する ###
次のコードを評価することでC-n/C-pで補完候補を選択できますが、これでは邪魔だと感じることがあります。
;; 良くない設定
(define-key ac-completing-map "\C-n" 'ac-next)
(define-key ac-completing-map "\C-p" 'ac-previous)
そこで補完メニュー表示時のみにC-n/C-pで補完候補を選択できるようにして、キー入力を極力奪わないようにしてみます。`ac-menu-map`は補完メニューが表示されているときに利用されるキーマップで、`ac-use-menu-map`が`t`のときに有効になります。
(setq ac-use-menu-map t)
;; デフォルトで設定済み
(define-key ac-menu-map "\C-n" 'ac-next)
(define-key ac-menu-map "\C-p" 'ac-previous)
詳しくは[`ac-use-menu-map`](#)および[`ac-menu-map`](#)を参照してください。
### クイックヘルプを利用しない ###
補完中に1秒ほど待ったときに出てくるツールチップヘルプをクイックヘルプと呼んでいますが、これを利用したくない場合は次のように設定します。
(setq ac-use-quick-help nil)
### 補完メニューの高さを変更する ###
`ac-menu-height`に行数を設定します。
;; 20行分表示
(setq ac-menu-height 20)
### 特定のモードで自動で`auto-complete-mode`を有効にする ###
`ac-modes`に設定されていないモードでは自動で`auto-complete-mode`が有効になりません。適宜設定してください。
(add-to-list 'ac-modes 'brandnew-mode)
### 大文字・小文字を区別したい/したくない ###
大文字・小文字の区別方法を設定するには`ac-ignore-case`に次のように設定します。
;; 大文字・小文字を区別しない
(setq ac-ignore-case t)
;; 補完対象に大文字が含まれる場合のみ区別する
(setq ac-ignore-case 'smart)
;; 大文字・小文字を区別する
(setq ac-ignore-case nil)
デフォルトは`smart`です。
### 特定の単語を入力したら補完を自動的に中止する ###
`ac-ignores`に自動的に補完を中止する単語を設定します。例えばRubyでendと入力した後に自動的に補完を中止するには以下のようにします。
(add-hook 'ruby-mode-hook
(lambda ()
(make-local-variable 'ac-ignores)
(add-to-list 'ac-ignores "end")))
`ac-ignores`はバッファローカル変数ではないので、バッファ特有の設定にする場合は`make-local-variable`で適宜バッファローカルにする必要があります。
### 色を変更する ###
色の設定はそれぞれ次のようになっています。
| フェイス名 | 説明 |
|----------------------|------------------------|
| `ac-completion-face` | インライン補完の文字色 |
| `ac-candidate-face` | 補完メニューの背景色 |
| `ac-selection-face` | 補完メニューの選択色 |
フェイスの背景色を変更するには`set-face-background`、前景色を変更するには`set-face-foreground`、下線の設定には`set-face-underline`を使います。
;; 設定例
(set-face-background 'ac-candidate-face "lightgray")
(set-face-underline 'ac-candidate-face "darkgray")
(set-face-background 'ac-selection-face "steelblue")
### デフォルトの情報源を変更する ###
情報源について分からない場合は最初に[情報源](#)を参照してください。デフォルトの情報源（全てのバッファに共通）を変更するには`setq-default`を使います。
(setq-default ac-sources '(ac-source-words-in-all-buffer))
### 特定のメジャーモードで情報源を変更する ###
例えばC++のバッファでは特定の情報源を利用したいということがあるでしょう。その場合は`add-hook`でフックを登録して、適宜`ac-sources`を変更するにようします。
(add-hook 'c++-mode (lambda () (add-to-list 'ac-sources 'ac-source-semantic)))
### 特定の情報源で補完する ###
特定の情報源で補完することも可能です。例えばファイル名補完を行いたい場合は`M-x ac-complete-filename`とします。あるいはC/C++のメンバー名補完を行いたい場合は`M-x ac-complete-semantic`とします。普通は次のようにこれらのコマンドをキーバインドします。
;; C++モードにもC-c .でメンバー名補完
(add-hook 'c++-mode-hook
(lambda ()
(local-set-key (kbd "C-c .") 'ac-complete-semantic)))
;; C-c /でファイル名補完
(global-set-key (kbd "C-c /") 'ac-complete-filename)
一般的に、このようなコマンドは自動的に定義されます。例えば`ac-source-foobar`という情報源を定義しているとすれば、`ac-complete-foobar`というコマンドも同時に自動的に定義されるのです。利用可能なコマンドは[標準情報源](#)を参照してください。
一つの補完コマンドで複数の情報源を使うには次のように別途定義する必要があります。
(defun semantic-and-gtags-complete ()
(interactive)
(auto-complete '(ac-source-semantic ac-source-gtags)))
`auto-complete`関数は`ac-sources`の代替を引数として取ることができます。
### 永続的にヘルプを表示する ###
`ac-help`の代わりに`ac-persist-help`を使ってください。デフォルトで`M-<f1>`と`C-M-?`に割り当てられています。
### 最後に補完したヘルプを表示する ###
`ac-last-help`コマンドは最後に補完した候補のヘルプを`ac-help`（バッファヘルプ）と同じ形式で表示してくれます。`C-u`で引数をあたえるか`ac-last-persist-help`を呼び出すことで、そのヘルプバッファを永続的に表示することも可能です。
`ac-last-quick-help`コマンドは最後に補完した候補のヘルプを`ac-quick-help`（クイックヘルプ）と同じ形式で表示してくれます。例えば、後から関数のドキュメントを見るときなどに便利です。
これらのコマンドは次のようにキーバインドするとよいでしょう。
(define-key ac-mode-map (kbd "C-c h") 'ac-last-quick-help)
(define-key ac-mode-map (kbd "C-c H") 'ac-last-help)
### ヘルプを綺麗に表示する ###
[pos-tip.el](http://www.emacswiki.org/emacs-en/PosTip)がインストールされている場合、`auto-complete-mode`は従来のレンダリングエンジンの代わりに、`pos-tip.el`が提供するネイティブレンダリングエンジンを利用してヘルプを表示します。
設定項目
--------
それぞれの設定項目は`.emacs`で変更するか`M-x customize-group RET auto-complete RET`で変更可能です。
### `ac-delay` ###
補完可能になるまでの遅延時間（秒）を実数で指定します。小さいほど瞬時に反応しますが、パフォーマンスの低下につながります。
### `ac-auto-show-menu` ###
補完時に自動的に補完メニューを表示するかどうかです。`t`の場合は常に自動的に表示します。`nil`の場合は絶対に表示されません。実数を指定すると表示までの遅延時間を秒数で指定できます。
### `ac-show-menu-immediately-on-auto-complete` ###
`auto-complete`時にただちに補完メニューを表示するかどうかです。すでにインライン補完が表示されている場合は、この設定は無視されます。
### `ac-expand-on-auto-complete` ###
`auto-complete`時に補完候補全体の共通部分を展開するかどうかです。
### `ac-disable-faces` ###
自動補完を無効にするフェイス名をシンボルのリストで指定します。カーソル位置のフェイステキストプロパティがそのリストに含まれる場合に自動補完が無効になる仕組みです。
### `ac-stop-flymake-on-completing` ###
補完時にFlymakeを中止するかどうかです。
### `ac-use-fuzzy` ###
[曖昧マッチによる補完](#)を利用するかどうかです。
### `ac-fuzzy-cursor-color` ###
[曖昧マッチによる補完](#)時にカーソルの指定した色に変更します。`nil`の場合は変更しません。利用できる色は`M-x list-colors-display`で確認できます。
### `ac-use-comphist` ###
[補完推測機能](#)を利用するかどうかです。`nil`にすると利用しませんが、パフォーマンスが向上する可能性があります。
### `ac-comphist-threshold` ###
低いスコアの補完候補を排除する閾値をパーセンテージで指定します。スコアの全体を100%とします。
### `ac-comphist-file` ###
[補完推測機能](#)のデータを永続化するファイルを指定します。
### `ac-use-quick-help` ###
クイックヘルプを利用するかどうかです。
### `ac-quick-help-delay` ###
クイックヘルプを表示するまでの時間（秒）を実数で指定します。
### `ac-menu-height` ###
補完メニューの行数を整数で指定します。
### `ac-quick-help-height` ###
クイックヘルプの行数を整数で指定します。
### `ac-candidate-limit` ###
補完候補数を制限します。整数が指定されている場合は、その値を表示する補完候補数の上限にします。`nil`の場合は無制限です。
### `ac-modes` ###
`global-auto-complete-mode`が有効な時に`auto-complete-mode`が自動的に有効になるモードをシンボルのリストで指定します。
### `ac-compatible-packages-regexp` ###
自動補完を開始するコマンドのパッケージを正規表現で指定します。
### `ac-trigger-commands` ###
自動補完を開始するコマンドをシンボルのリストで指定します。`self-insert-command`がデフォルトですが、まれに文字の挿入を独自のコマンドに設定しているモードがあるので、その対応のための設定項目です。
### `ac-trigger-commands-on-completing` ###
[`ac-trigger-commands`](#)と同様ですが、補完中に使用される点が異なります。
### `ac-trigger-key` ###
[トリガーキー](#)を指定します。
### `ac-auto-start` ###
補完が自動的に開始されるかどうかを指定します。`t`の場合は常に自動的に開始されます。`nil`の場合は絶対に自動的に開始されません。整数の場合は、補完対象文字列の長さがその値以上になるまで自動的に開始されません。
### `ac-ignores` ###
補完しない文字列を文字列のリストで指定します。
### `ac-ignore-case` ###
補完時に大文字・小文字を区別するかどうかです。`t`の場合は常に無視します。`nil`の場合は無視しません。シンボルで`smart`が指定された場合は、補完対象文字列に大文字が含まれる場合のみ区別します。
### `ac-dwim` ###
"Do What I Mean"機能です。`t`の場合は次の挙動になります。
* 補完選択時にTABがRETの挙動に変化する
* 補完候補が一つしかないときにTABをするとRETの挙動になる
### `ac-use-menu-map` ###
補完メニュー表示時に特別なキーマップ（`ac-menu-map`）を有効にするかどうかです。`t`かつ次の条件を満たしたときに`ac-menu-map`が有効になります。
* `ac-auto-start`および`ac-auto-show-menu`が`nil`でなく、補完を開始してから一定時間後にメニューが表示されたとき
* `auto-complete`コマンドでメニューが表示されたとき
* `ac-isearch`コマンドでメニューが表示されたとき
### `ac-use-overriding-local-map` ###
補完の選択などの補完中のキー入力が効かない場合に利用します。内部的には`overriding-local-map`を使いますが、効果が強力すぎて他の拡張と干渉することがあるので、極力利用しないでください。
### `ac-completion-face` ###
インライン補完のためのフェイスです。
### `ac-candidate-face` ###
補完候補の背景のためのフェイスです。
### `ac-selection-face` ###
選択された補完候補のフェイスです。
### `global-auto-complete-mode` ###
グローバルに`auto-complete-mode`を利用するかどうかです。
### `ac-user-dictionary` ###
[辞書による補完](#)のための辞書を文字列のリストで指定します。
### `ac-user-dictionary-files` ###
[辞書による補完](#)のための辞書ファイルを文字列のリストで指定します。
### `ac-dictionary-directories` ###
[辞書による補完](#)のための辞書ファイルディレクトリを文字列のリストで指定します。
### `ac-sources` ###
使用する[情報源](#)をリストで指定します。これはバッファローカル変数です。
### `ac-completing-map` ###
補完中に使用するキーマップです。
### `ac-menu-map` ###
メニュー表示時に使用するキーマップです。[`ac-use-menu-map`](#)も参照してください。
### `ac-mode-map` ###
`auto-complete-mode`が有効なバッファで使用するキーマップです。
拡張方法
--------
`auto-complete-mode`を拡張するとはつまり[情報源](#)を定義することです。この節では情報源の定義の仕方を説明します。
### 雛形 ###
情報源はおおまかに言って次のような形をとります。
(defvar ac-source-mysource1
'((prop . value)
...))
見てわかる通り情報源とは単なる連想リストでしかないのです。あらかじめ定義されたプロパティ名と正しい値のペアを連想リストとして組合せるだけで情報源が定義できてしまうのです。
### 簡単な例 ###
情報源で一番重要なプロパティは[`candidates`](#)プロパティです。このプロパティに関数あるいは式、変数を与えることで補完候補の生成を行います。プロパティの評価結果は文字列のリストであるべきです。例として補完候補としてFoo, Bar, Bazを生成する情報源を定義してみましょう。
(defvar ac-source-mysource1
'((candidates . (list "Foo" "Bar" "Baz"))))
次にこの情報源を`ac-sources`に設定して実際に補完してみましょう。
(setq ac-sources '(ac-source-mysource1))
Bと入力してBar, Bazが補完候補として現われれば成功です。上記の例では`candidates`プロパティに`(list ...)`という式を指定しました。ここで指定した式はバイトコンパイルされないので、よほど簡単なものでないかぎり式で指定するのはパフォーマンスの悪化をもたらします。代替策・正攻法としては関数を利用するのがよいでしょう。
(defun mysource1-candidates ()
'("Foo" "Bar" "Baz"))
(defvar ac-source-mysource1
'((candidates . mysource1-candidates)))
`candidates`プロパティに指定した関数は引数なしで補完が更新される度に呼び出されます。その他の方法として変数を直接指定することもできます。
### 初期化 ###
補完が開始されたときに一度だけ初期化処理を行いたいということがあります。そのためには`init`プロパティを利用します。`candidates`プロパティ同様、引数なしの関数あるいは式を指定します。次に簡単な例を示します。
(defvar mysource2-cache nil)
(defun mysource2-init ()
(setq mysource2-cache '("Huge" "Processing" "Is" "Done" "Here")))
(defvar ac-source-mysource2
'((init . mysource2-init)
(candidates . mysource2-cache)))
この例では`mysource2-init`関数で大規模な処理を行い、`mysource2-cache`変数にその結果を保存しています。そして`candidates`プロパティにその変数を指定することで、補完が更新される度に大規模な処理が行われるのを防いでいます。この例の他にも次のような用途が考えられます。
* `require`する
* バッファを開いておく
### キャッシュ ###
`auto-complete-mode`ではキャッシュの戦略が重要になります。その方法として、前節で触れた`init`プロパティによるものと、この節で説明する`cache`プロパティによるものが基本となります。情報源の定義に`cache`プロパティを設定しておくと、初回の`candidates`プロパティの結果が内部的にキャッシュされ、それ以降は`candidates`プロパティを評価する代わりに、そのキャッシュを利用するにようになります。
前節の例を`cache`プロパティを利用して書き直してみます。
(defun mysource2-candidates ()
'("Huge" "Processing" "Is" "Done" "Here"))
(defvar ac-source-mysource2
'((candidates . mysource2-candidates)
(cache)))
`candidates`プロパティに大規模な処理が必要な関数が指定されていますが、初回のみ実行されるのでパフォーマンスの問題は軽減されます。
#### キャッシュの寿命 ####
`init`プロパティや`cache`プロパティより大きいスコープでキャッシュを保持することがあります。例えば滅多に変更のない関数名のリストなどがそうです。その場合にパフォーマンスを犠牲にすることなく、適度にキャッシュをクリアするにはどうすればよいのでしょうか。`auto-complete-mode`はキャッシュの寿命を管理する機構を持っており、ユーザーはそこにキャッシュ用の変数を登録しておくことにより、適当なイベントごとにキャッシュがクリアされます。
バッファが保存されるたびにキャッシュをクリアするには`ac-clear-variable-after-save`で変数を登録します。簡単な例を示します。
(defvar mysource3-cache nil)
(ac-clear-variable-after-save 'mysource3-cache)
(defun mysource3-candidates ()
(or mysource3-cache
(setq mysource3-cache (list (format "Time %s" (current-time-string))))))
(defvar ac-source-mysource3
'((candidates . mysource3-candidates)))
これを`ac-sources`に設定してTimeで補完を行ってください。すると補完候補に補完時の時間が表示されると思います。二度目以降も同じ時間が表示されるのは`mysource3-candidates`は可能な限りキャッシュを返すようになっているからです。それでは一度そのバッファを保存して、再びTimeで補完を行ってください。今度は新しい時間に更新されたと思います。この情報源のキモは`ac-clear-variable-after-save`でキャッシュ用変数を登録しているところにあります。
さらに定期的にキャッシュをクリアすることも可能です。そのためには`ac-clear-variable-every-minute`で変数を登録します。使い方は`ac-clear-variable-after-save`と同じですが、一分ごとに定期的にキャッシュがクリアされる点が異なります。標準の情報源である`ac-source-functions`などがこの機能を利用しています。
### アクション ###
[RETによる補完](#)の場合、`action`プロパティで指定された関数あるいは式が評価されます。標準情報源では`ac-source-abbrev`や`ac-source-yasnippet`が利用しています。
### オムニ補完 ###
*オムニ補完*とは現在編集中のコンテキストを考慮して行う補完のことです。スラッシュを検出して行うファイル名補完や、ドットを検出して行うC/C++のメンバー補完は、このオムニ補完であると言えます。情報源をオムニ補完に対応させるには`prefix`プロパティを使います。`prefix`プロパティは補完対象文字列の開始位置をポイントで返さなければなりません。`nil`を返した場合は、その情報源が現在のコンテキストでは無効であると解釈します。
例として`To: `の後にメールアドレスを補完する情報源を考えてみましょう。まず、これまでの知識からメールアドレスを補完する情報源を定義します。
(defvar ac-source-to-mailaddr
'((candidates . (list "[email protected]"
"[email protected]"
"[email protected]"))))
(setq ac-sources '(ac-source-to-mailaddr))
ここまでは簡単です。次に`prefix`プロパティを使って`To: `の後にのみ補完が開始されるようにします。`prefix`プロパティには次の三つが指定できます。
* 正規表現
* 関数
* 式
正規表現を指定した場合、その正規表現を使って`re-search-backward`を行い[^1]、マッチしたグループ1あるいはグループ0の先頭位置を補完対象文字列の開始位置とします。もう少し複雑な制御が必要な場合は関数あるいは式を指定します。ここで評価された開始位置は[`ac-point`](#)に格納されます。先の例では次の正規表現で事足ります。
^To: \(.*\)
グループ1をキャプチャしているのは`To: `を補完対象文字列に含めないためです。これを`prefix`プロパティに設定した最終的な情報源は次のようになります。
(defvar ac-source-to-mailaddr
'((candidates . (list "[email protected]"
"[email protected]"
"[email protected]"))
(prefix . "^To: \\(.*\\)")))
試しに`To: `と入力してみましょう。メールアドレスが補完できるようになったら成功です。
[^1]: 厳密にはその正規表現の末尾にカーソルを意味する\=を付与したもので`re-search-backward`されます
### `ac-define-source` ###
これまでは`defvar`で情報源を定義してきましたが、`ac-define-source`というユーティリティマクロを使って定義することも可能です。
(ac-define-source mysource3
'((candidates . (list "Foo" "Bar" "Baz"))))
このマクロは次のように展開されます。
(defvar ac-source-mysource3
'((candidates . (list "Foo" "Bar" "Baz"))))
(defun ac-complete-mysource3 ()
(interactive)
(auto-complete '(ac-source-mysource3)))
`defvar`は従来通り定義され、続いてその情報源のみで補完を行うコマンドが定義されます。`auto-complete`は引数なしで呼び出された場合は`ac-sources`を情報源として使い、引数ありで呼び出された場合はその値を情報源として使います。`defvar`か`ac-define-source`かどちらを使うかは微妙ですが、後方互換性を保持するなら`defvar`のほうが無難でしょう。ちなみに標準情報源は全て`ac-define-source`で定義されています。つまり`ac-complete-filename`などを他のキーに割り当てて個別に利用することができます。
### 情報源プロパティ一覧 ###
#### `init` ####
補完開始時に一度だけ指定された関数あるいは式を評価します。
#### `candidates` ####
補完更新時に指定された関数あるいは式、変数を評価します。評価結果は文字列のリストであるべきです。[`cache`](#)プロパティが有効な場合は、その補完では二度目以降評価されません。
#### `prefix` ####
指定された正規表現、関数あるいは式を評価して、[オムニ補完](#)のための補完対象文字列の開始位置を取得します。`nil`を返した場合はその情報源は無視されます。正規表現が指定された場合、グループ1の開始位置あるいはグループ0の開始位置が評価値として使われます。
#### `requires` ####
情報源が有効になる補完対象文字列の文字数を指定します。指定のない場合は[`ac-auto-start`](#)の値が利用されます。
#### `action` ####
[RETによる補完](#)時に実行する[アクション](#)を関数あるいは式で指定します。
#### `limit` ####
補完候補の上限数を設定します。`ac-candidate-limit`を部分的に上書きします。
#### `symbol` ####
補完候補の意味を現わす記号を一文字の文字列で指定します。指定する記号は任意ですが、基本的に以下の慣習に従うべきです。
| 記号 | 意味 |
|------|----------------|
| s | シンボル |
| f | 関数・メソッド |
| v | 変数 |
| c | 定数 |
| a | 略語 |
| d | 辞書 |
#### `summary` ####
補完候補のサマリを文字列で指定します。これは補完候補を簡潔に説明するために使うべきです。
#### `cache` ####
[キャッシュ](#)を利用します。
#### `require` ####
整数あるいは`nil`を指定します。整数が指定された場合、その値が補完対象文字列の長さより大きい場合は、その情報源は無視されます。`nil`の場合は常に有効になります。
#### `candidate-face` ####
補完候補のフェイスを指定します。[`ac-candidate-face`](#)を部分的に上書きします。
#### `selection-face` ####
選択された補完候補のフェイスを指定します。[`ac-selection-face`](#)を部分的に上書きします。
#### `depends` ####
依存するfeature（`require`される）をリストで指定します。
#### `available` ####
この情報源が利用できるかを示す関数あるいは式を指定します。
### 変数一覧 ###
情報源でよく利用する変数を一覧します。
#### `ac-buffer` ####
補完が開始されたバッファです。
#### `ac-point` ####
補完対象文字列の開始位置です。
#### `ac-prefix` ####
補完対象文字列です。
#### `ac-limit` ####
現在の情報源の候補上限数です。[`ac-candidate-limit`](#)や[`limit`](#)プロパティで制御されます。
#### `ac-candidates` ####
補完候補のリストです。
トラブルシューティング
----------------------
### レスポンスが遅い ###
十分なレスポンス性能を確保するのは`auto-complete-mode`にとって大変重要なことですが、よく知られているように、それは機能性とのトレードオフでもあります。以下にレスポンス性能に関連する設定項目を挙げるので、もし問題があれば参照してください。
#### `ac-auto-start` #### {#trouble_ac-auto-start}
[`ac-auto-start`](#)に大きめの数値を設定することで、補完候補の生成コストを軽減するができます。あるいは`nil`に設定することで、本当に必要な時だけ補完を実行することもできます。詳しくは[自動的に補完しない](#)を参照してください。
#### `ac-delay` #### {#trouble_ac-delay}
[`ac-delay`](#)に大きめの数値を設定することで、補完開始コストを軽減することができます。
#### `ac-auto-show-menu` #### {#trouble_ac-auto-show-menu}
[`ac-auto-show-menu`](#)に大きめの数値を設定することで、補完メニューの表示コストを軽減することができます。
#### `ac-use-comphist` #### {#trouble_ac-use-comphist}
[`ac-use-comphist`](#)に`nil`を設定して[補完推測機能](#)を無効にすることで、推測のための計算コストを軽減することができます。
#### `ac-candidate-limit` #### {#trouble_ac-candidate-limit}
[`ac-candidate-limit`](#)に適切な数値を設定することで、多量の計算を行わないようにすることができます。
### 補完メニューの表示が崩れる ###
補完メニューの表示が崩れる問題には大きく分けて二つあります。
#### カラム計算の問題 ####
`auto-complete-mode`は補完メニューを正しく表示するのに必須な処理であるカラム計算のコストを軽減するために、正確さをある程度犠牲にした最適化バージョンのカラム計算関数を利用していますが、これが原因で補完メニューの表示が崩れる可能性があります。最適化バージョンを使わないためには次のコードを評価します。
(setq popup-use-optimized-column-computation nil)
#### フォントの問題 ####
Ubuntu 9.10にて[IPAフォント](http://ossipedia.ipa.go.jp/ipafont/)をXftでレンダリングすると、補完メニューの表示が崩れる問題を確認しています。[VLゴシック](http://dicey.org/vlgothic/)などではXftでレンダリングしても正しく表示されるようなので、そちらをお使いください。また、Xftを使わなければIPAフォントも正しくレンダリングできます。
現在のところ完全な対応策は見つかっていませんが、`set-face-font`で補完メニューのフォントサイズを適切なサイズに変更することで対応できる可能性があります。例えばNTEmacsでは日本語を含む補完メニューを表示すると補完メニューの表示が崩れることがあります。これは以下のようにフォントサイズを調整することで対応することができます。
(set-face-font 'ac-candidate-face "MS Gothic 11")
(set-face-font 'ac-selection-face "MS Gothic 11")
既知の問題
----------
### `flyspell-mode`が有効なバッファで自動補完できない ###
`flyspell-mode`の遅延手法が原因で自動補完ができません。これを回避するには`M-x ac-flyspell-workaround`とするか`~/.emacs`に次のように書いてください。
(ac-flyspell-workaround)
バグレポート
------------
[Auto Complete Modeのバグトラッキングシステム](http://cx4a.org/redmine/projects/auto-complete-mode)に新しいチケットを登録してください。
[GNU Emacs]: http://www.gnu.org/software/emacs/
[GPLv3]: http://gplv3.fsf.org/
[GFDL]: http://www.gnu.org/copyleft/fdl.html
