helm、便利ですよね。あまりに便利なのでちょくちょく自分でオリジナルのhelmコマンドを作りたくなるのですが、引数に何を渡せばよいかすぐ忘れてしまう上にあまりまとまった情報が無かったのでメモしておきます。
基本
helmコマンドで表示する候補やキーマップをカスタマイズするには、必要な情報をプロパティリスト(:keyword1 value1 :keyword2 value2 ....)形式で渡します。(プロパティリストではなく通常の引数を渡す形式もありますが、わかりづらいので割愛)
例：単純な文字列の候補から選択する
(helm :sources '((name . "Helm Sample")
(candidates . ("AAA" "BBB" "CCC"))
(action . kill-new)))
helmコマンドの主な引数
| キーワード | 説明 | デフォルト値 |
|---|---|---|
| :sources | helmバッファに表示する候補情報(以下、情報源)のリスト。詳細は後述。 | (未確認) |
| :input | 候補を絞り込むパターンの初期値。何らかの値を指定すると、helmバッファにあらかじめこの値で絞り込まれた候補一覧が表示される。 | "" |
| :prompt | ミニバッファに表示されるプロンプト。 | "pattern: " |
| :buffer | 候補を表示されるバッファ名。バッファ名を分けておくと他のhelmコマンドを実行しても候補バッファが上書きされないので、C-u M-x helm-resumeでhelmセッションを再開できる。 | "helm" |
| :default | デフォルトの絞り込み条件。ミニバッファには表示されないが何か入力するまでこの値で絞り込まれた状態となる。 | thing-at-pointの結果 |
| :keymap | ミニバッファで使用するキーマップ。 | helm-map |
| :allow-nest | 他のhelmセッションからのネスト呼び出しを許可するか。 | nil |
:sourcesで指定する情報源
:sourcesの中身はhelmバッファに表示する情報源のリストです。個々の情報源は以下のようなキーと値を持つ連想配列の形式で表現されます。
情報源の基本的な定義
| キー | 説明 |
|---|---|
| name | 情報源の名前(先述の例の図で"Helm Sample"と表示されている箇所に入る文字列) |
| init | 初期化処理を行う関数 |
| candidates | 候補となる文字列リスト |
| action | 選択した候補に対して実行する関数(またはそのリスト) |
バッファの中身を候補にする
helmバッファに表示される候補の基本は情報源のcandidatesとして定義されたリストの中身ですが、特定のバッファの各行を候補とすることもできます。文字列リストをcandidatesに指定するよりも、バッファ内の文字列を候補にした方が速度面でだいぶ有利らしいです。
例：lsコマンドの結果をバッファに挿入し、helmの候補とする
(helm :sources '((name . "Helm Sample")
(candidates-in-buffer)
(init . (lambda () (helm-init-candidates-in-buffer 'global (shell-command-to-string "ls -1"))))
(action . find-file)))
candidates-in-buffer属性を指定することで、lsコマンドの結果を格納したバッファの内容を候補として表示しています。候補となる文字列を格納したバッファは、init属性で指定した関数によって初期化されます。
プラグイン
上記の例で挙げたcandidates-in-buffer属性は、実行時に内部でcandidates属性に変換され、候補用バッファの各行の内容が候補として渡されるという仕組みになっています。このように、ある属性を実行時に既存の属性に変換する仕組みをhelmでは プラグイン と呼んでおり、組み込みの (candidates-in-buffer) や (candidates-file) 等のプラグインがある他、ユーザが自分で定義することもできます。
おわりに
ここまでに述べた内容に従えば、最低限自分で使うhelmコマンドを作ることはできると思います。 ただしhelmコマンドの引数や:sourcesの中身については、上記に挙げたものが全てではありません。より実践的な知識を得たい方は、既存のhelmコマンドのソースや、helm自体のソースを読むなどして、より理解を深めていくと良いと思います。
参考
- Emacs Lisp テクニックバイブル 13章にhelmの前身であるanything.elの解説が載っています。anythingの話ですがほとんどhelmにも通じる内容で参考になります。
- M-x describe-function RET helm
- M-x describe-function RET helm-candidates-in-buffer
他にどこかに情報まとまっているのを見かけた方いれば、ぜひ教えていただけるとうれしいです。