anything.el のソースを読んで、何が書いてあるのかを訳してみたよ！
実際に anything の source を作ってみた記事一覧
修正履歴
-
2009/10/16: 誤字の訂正
-
2009/10/16: ソースにリンクを張っていただくとおっしゃられているので、anything ソース作成記事へのリンクを貼り付ける(thanks to id:rubikitch !)
要素
-
name (必須)
-
source の名前。この値は source からヒットしたリストの上に表示されるタイトルでもある。この値はユニークである必要がある。
-
header-name (オプション)
-
ヘッダーで表示される文字列を返す関数。この関数の引数は source の名前である。この要素は source の名前に情報を追加するときに便利である。
-
candidates (candidates-in-buffer 要素を指定しなかった場合、必須)
-
source から候補を取得するための方法を指定する。この要素に指定できるのは、変数、引数なしの関数、あるいは実際の候補のリストである。
リストは文字列のリストでなければならず、そのため必要であれば候補を文字列に変換するのは source の責任である。
仮に候補が非同期で取得されなければならない場合(例えばコマンド終了までに時間がかかる外部コマンドで取得するような場合)には、その関数は外部コマンドを非同期で実行し、 the associated process object を戻す必要がある。
Anything はそのプロセスを管理する(そのプロセスから出力を受け取り、必要であればそのプロセスを停止する、など)。プロセスは現在のパターンにマッチする候補を返さなければならない(anything-pattern を参照すること)。
注意: 非同期の source からの結果は anything-sources 中の位置に関係なく、 anything のバッファーの最後に表示される。
-
action (type 要素が指定されなかった場合、必須)
-
action 要素は「(表示文字列 . 関数)ペアー」のリストである。指定された関数は選択された候補を引数として呼び出される。
現在選択されている候補のためのデフォルト以外のアクションがこのリストから選ばれる(デフォルトでは TAB キーで)。 DISPLAY 文字列は、補完バッファーで表示され、アクションが選択されたときに関数が呼び出される。リスト中の先頭ののアクションがデフォルト・アクションになる。
-
type (action 要素が指定された場合、オプション)
-
source が返すアイテムの種類を示す。
Merge attributes not specified in the source itself from `anything-type-attributes’.
This attribute is implemented by plug-in.
-
init (オプション)
-
anything が実行された際に引数なしで呼び出される関数。この要素は、候補のリストを作成するために現在の状況を収集するのに便利である。
例えば、 source がカレントディレクトリを対象とした場合、init 要素に指定することでカレントディレクトリの情報を収集することができる。なぜならば、それ以降 anything はミニバッファーと anything-buffer で動作し、カレントディレクトリが変わる可能性が出てくるからである。
-
match (オプション)
-
候補を引数として呼び出される関数のリスト。関数は、候補が現在のパターンにマッチする場合、non-nilを返さなければならない(anything-pattern変数を参照すること)。
この要素は source が文字列のマッチに基づくデフォルトのパターンマッチを上書きすることを許す。例えば、この要素はファイル名の source を実装し、ファイルのベースネームでパターンマッチをする場合に用いられる。というのも、そのファイルのパス上の文字列の代わりに、ベースネームの一部をタイプする可能性の方が高いからだ。
仮にリストが一つ以上の関数を含んでいた場合、 source から候補をマッチさせるリストは可能性のあるすべての候補に対して最初の関数を呼び出した結果に、次の関数を呼び出しといったようにしてできた結果をまとめたものである。最初の関数によって提供されるマッチング用の候補が最初に結果のリストに現れ、次に別の関数の結果に個別に表示される。
この要素は非同期の source には効力を持たない(candidates 要素を参照)。なぜなら、非同期の source はパターンマッチングを自分自身で行うからだ。
-
candidate-transformer (オプション)
-
source から補完リストが作成された際に引数を一つとって呼び出される関数である。その引数は source から取得された候補のリストである。実際の補完に用いられる変換済み候補のリストを返さなければならない。
この要素は候補のリストからアイテムを変更したり、取り除いたりするために用いることができる。
この関数は「(表示文字列 . 実際の文字列)」という対のリストを返すことで、候補を修正することができる。この場合、「表示文字列」は Anything バッファーで表示されるが、「実際の文字列」は候補が選択されたときの action の引数に用いられる。このことによって、例えば候補があまりに長ければより読みやすくすることができるし、他の候補と共通の部分があり表示のために短縮した文字列に安全に置換できるようになる。
注意: 仮に「(表示文字列 . 実際の文字列)」という形式が用いられた場合、パターンマッチは表示文字列で行われ、実際の値では実施されない。
-
filtered-candidate-transformer (オプション)
-
この要素は、候補のリストと source の二つの引数を取る以外、candidate-transformerと同じ形式である。
この transformer は現在のパターンによってフィルタリングされた候補のリストを対象に実施される。 candidate-transformer が一度しか実行されないのに対して、 filtered-candidate-transformer は入力されたパターンが変更された際にいつも実行される。
filtered-candidate-transformer は、例えば現在のパターンに基づき、候補のリストを動的に変更するのに用いられる。
いくつかの場合では、パターンが変更された場合に常に実施されるにもかかわらず、 candidate-transformer ではなく、この filtered-candidate-transformer で候補を変更する方が効率がいい。例えば、候補のセットが非常に巨大な場合、 すべての候補を対象に変更が行われるが、 anything-candidate-number-limit の制限により候補のすべてが表示されるわけではないからだ。
注意: candidate-transformer がすでに実行されているので、指定する変更用の関数は「(表示用文字列 . 実際の文字列)」という形式の候補を扱うことが出来る必要がある。
このオプションは非同期の source には効果がない(少なくとも、今のところはね)
-
action-transformer (オプション)
-
この要素には、source からのアクションリストが集められたときに、二つの引数で呼び出される関数を指定する。最初の引数はアクションのリストで、二つ目の引数は現在選択しているアイテムである。
この関数は変換されたアクションのリストを返さなければならない。
この要素は現在選択されている候補に基づいてアクションのリストをカスタマイズするために用いることが出来る。
-
delayed (オプション)
-
source からの候補はユーザーが入力をやめ、 anything-idle-delay 秒だけアイドルであった場合にだけ表示される。
-
volatile (オプション)
-
source が候補のリストを動的に収集していることを示す。そのため、単独の Anything 呼び出しではキャッシュされない。この要素は同期的な source にのみ適用することが出来る。なぜなら、非同期の source はキャッシュしないからだ。
-
requires-pattern (オプション)
-
もしこの要素が存在すれば、 source からのマッチがパターンが空でないときにのみ表示される。オプションとして、整数のパラメータを指定することで、多くの候補がある source の場合に役立つ入力の制限字数を指定することが出来る。
-
persistent-action (オプション)
-
選択された候補を引数として呼び出される関数を指定する。
anything-execute-persistent-action で実行されるアクション。指定しなければ、デフォルトのアクションを用いる。
-
candidates-in-buffer (オプション)
-
バッファーを活用することで、候補を作成し、狭めるためのショートカットのための要素。この新規に導入された要素を用いることで、 volatile 要素と match 要素を追加するのをうっかり忘れることを防いでくれる。
anything-candidates-in-buffer のドック・ストリングを参照。
(candidates-in-buffer) は、次に示す三つの要素を指定するのと同じことであり、(candidates-in-buffer . candidates-function) は以下に示す要素を指定するのと同じことである。この要素はプラグインによって実装されている。
;; (candidates-in-buffer)
(candidates . anything-candidates-in-buffer)
(volatile)
(match identity)
;; (candidates-in-buffer . candidates-function)
(candidates . candidates-function)
(volatile)
(match identity)
-
search (オプション)
-
re-search-forward や search-forward のような関数のリスト。 anything-candidates-in-buffer で用いられるバッファー検索関数。デフォルトでは、 anything-candidates-in-buffer は re-search-forward を用いる。この要素は以下の要素と一緒に用いることが意図されている:
(candidates . anything-candidates-in-buffer)
;; もしくは短く書いて
(candidates-in-buffer)
-
search-from-end (オプション)
-
バッファーの最後から anything-candidates-in-buffer の検索を行う。この要素が指定されると、 anything-candidates-in-buffer は re-search-backward を代わりに用いるようになる。
-
get-line (オプション)
-
buffer-substring-no-properties や buffer-substring のような関数。この関数は、 anything-candidates-in-buffer で計算される候補を表す行頭と行末のポイントを変換する。デフォルトでは、 anything-candidates-in-buffer は buffer-substring-no-properties を用いる。
-
display-to-real (オプション)
-
この要素には、選択された候補を引数にとって呼び出される関数を指定する。
その関数は選択された候補を変換し、結果がアクション用の関数に渡される。この display-to-real 要素は Anything バッファーで表示された文字列とは異なる文字列を渡すもう一つの方法を提供する。
これまでは候補、 candidate-transformer、あるいは filtered-candidate-transformer 関数に「(表示文字列 . 実際の文字列)」というリストを返すようにすることができた。しかし、実際の文字列が表示文字列から生成しうるのであれば、 display-to-real はより便利で早くなる。
-
cleanup (オプション)
-
その「*anything*バッファー」が閉じているときに、引数無しで呼び出される関数。必要ではない候補用のバッファーを閉じるときに便利である。
注意: この館数はアクションを実施する前に実行される。
-
candidate-number-limit (オプション)
-
この source のためだけに anything-candidate-number-limit を上書きする。
-
dummy (オプション)
-
anything-pattern を候補にセットする。この要素が指定されると、 candidates 要素が無視される。
この要素はプラグインによって実装されている。