14.3 カスタマイズ変数の定義

カスタマイズ可能変数(customizable variable)はユーザーオプション(user option)とも呼ばれ、これはCustomizeインターフェースを通じてセットできるグローバルなLisp変数です。defvar(Defining Variablesを参照)デ定義される他のグローバル変数と異なり、カスタマイズ可能変数はdefcustomマクロを使用して定義されます。サブルーチンとしてdefvarを呼び出すことに加えテ、defcustomはCustomizeインターフェースでその変数が表示される方法や、その変数がとることができる値などを明示します。

Macro: defcustom option standard doc [keyword value]…

このマクロはユーザーオプション(かカスタマイズ可能変数)としてoptionを宣言する。optionはクォートしないこと。

引数standardはoptionの標準値を指定する式である。defcustomフォームの評価によりstandardが評価されるが、その値にそのオプションをバインドする必要はない。optionがすでにデフォルト値をもつなら、それは変更されずに残る。ユーザーがすでにoptionにたいするカスタマイゼーションを保存していれば、ユーザーによりカスタマイズされた値がデフォルト値としてインストールされる。それ以外ならstandardを評価した結果がデフォルト値としてインストールされる。

defvarと同様、このマクロはoptionをスペシャル変数 — 常にダイナミックにバインドされることを意味する — としてマークする。optionがすでにレキシカルバインドをもつなら、そのレキシカルバインドはバインディング構文を抜けるまで効果をもつ。Variable Scopingを参照のこと。

式standardは別の様々な機会 — カスタマイゼーション機能がoptionの標準値を知る必要があるときは常に — にも評価される可能性がある。そのため任意回数の評価を行ても安全な式を使用するように留意されたい。

引数docはその変数にたいするドキュメント文字列を指定する。

defcustomが何も:groupを指定しなければ、同じファイル内でdefgroupによって最後に定義されたグループが使用される。この方法ではほとんどのdefcustomは明示的な:groupが不必要になる。

Emacs LispモードでC-M-x(eval-defun)でdefcustomフォームを評価するとき、eval-defunの特別な機能は変数の値がvoidかどうかテストせずに、無条件に変数をセットするよう段取りする(同じ機能はdefvarにも適用される。Defining Variablesを参照)。すでに定義されたdefcustomでeval-defunを使用することにより、(もしあれば):set関数(以下参照)が呼び出される。

事前ロード(pre-loaded)されたEmacs Lispファイル(Building Emacsを参照)にdefcustomを配置すると、ダンプ時にインストールされた標準値は正しくない — たとえば依存している他の変数がまだ正しい値を割り当てられていない —　かもしれない。この場合はEmacs起動後に標準値を再評価するために、以下で説明するcustom-reevaluate-settingを使用する。

Common Keywordsにリストされたキーワードに加えて、このマクロには以下のキーワードを指定できる

:type type

このオプションのデータ型として、typeを使用します。これはどんな値が適正なのか、その値をどのように表示するかを指定します(Customization Typesを参照してください)。

:options value-list

このオプションに使用する適正な値のリストを指定する。ユーザーが使用できる値はこれらの値に限定されないが、これらは便利な値の選択肢を提示する。

これは特定の型にたいしてのみ意味をもち現在のところhook、plist、alistが含まれる。:optionsを使用する方法は個別の型の定義を参照のこと。

:set setfunction

Customizeインターフェースを使用してこのオプションの値を変更する方法としてsetfunctionを指定する。関数setfunctionは2つの引数 — シンボル(オプション名)と新しい値 — を受け取り、このオプションにたいして正しく値を更新するために必要なことは何であれ行うこと(これはおそらくLisp変数として単にオプションをセットすることを意味しない)。この関数は引数の値を破壊的に変更しないことが望ましい。setfunctionのデフォルトはset-default。

このキーワードを指定すると、その変数のドキュメント文字列には手入力のLispコードで同じことを行う方法が記載されること。

:get getfunction

このオプションの値を抽出する方法として、getfunctionを指定します。関数getfunctionは1つの引数(シンボル)をとり、カスタマイズがそのシンボル(シンボルのLisp値である必要はない)にたいする“カレント値”としてそれを使うべきかreturnするべきです。デフォルトはdefault-valueです。

:getを正しく使用するためには、Customの機能を真に理解する必要がある。これは変数としてCustom内で扱われる値のためのものだが、実際にはLisp変数には格納されない。実際にLisp変数に格納されている値にgetfunctionを指定するのは、ほとんどの場合は誤りである。

:initialize function

functionはdefcustomが評価されるときに変数を初期化するために使用される関数であること。これは2つの引数 — オプション名(シンボル)と値を受け取る。この方法での使用のために事前定義された関数がいくつかある:

custom-initialize-set

変数の初期化にその変数の:set関数を使用するが、値がすでに非voidなら再初期化を行わない。

custom-initialize-default

custom-initialize-setと同様だが、その変数の:setのかわりに関数set-defaultを使用して変数をセットする。これは変数の:set関数がマイナーモードを有効または無効にする場合の通常の選択である。この選択により変数の定義ではマイナーモード関数を呼び出しは行わないが、変数をカスタマイズしたときはマイナーモード関数を呼び出すだろう。

custom-initialize-reset

変数の初期化に常に:set関数を使用する。変数がすでに非voidなら、(:getメソッドでリターンされる)カレント値を使用して:set関数を呼び出して変数をリセットする。これはデフォルトの:initialize関数である。

custom-initialize-changed

変数がすでにセットされている、またはカスタマイズされているなら、変数の初期化のために:set関数を使用して、それ以外なら単にset-defaultを使用する。

custom-initialize-safe-set

custom-initialize-safe-default

これらのn関数はcustom-initialize-set、custom-initialize-defaultと同様に振る舞うがエラーをcatchする。初期化中にエラーが発生したら、set-defaultを使用して変数をnilにセットして、エラーのシグナルはしない。

これらの関数は事前ロードされたファイルで定義されたオプションのためのものである(requireされた変数や関数がまだ定義されていないため、standard式はエラーをシグナルするかもしれない)。その値は通常はstartup.elで更新され、defcustomにより計算された値は無視される。startup後にその値をunsetしてdefcustomを再評価すれば、エラーなしでstandardは評価される。

:risky value

その変数のrisky-local-variableプロパティーをvalueにセットする(File Local Variablesを参照)。

:safe function

その変数のsafe-local-variableプロパティーをfunctionにセットします(File Local Variablesを参照)。

:set-after variables

保存されたカスタマイゼーションに合わせて変数をセッティングするときは、その前に変数variables確実にセット — つまりこれら他のものが処理される後までセッティングを遅延 — すること。これら他の変数が意図された値をもっていない場合に、この変数のセッティングが正しく機能しなければ:set-afterを使用すること。

特定の機能を“オンに切り替える”オプションにたいしては、:requireキーワードを指定すると便利です。これは、その機能がまだロードされていないときは、そのオプションがセットされるとEmacsがその機能をロードするようにします。Common Keywordsを参照してください。以下はライブラリーsaveplace.elの例です:

(defcustom save-place nil
  "Non-nil means automatically save place in each file..."
  :type 'boolean
  :require 'saveplace
  :group 'save-place)

あるカスタマイゼーションアイテムが:optionsがサポートするhookやalistのような型をもつなら、custom-add-frequent-valueを呼び出すことによってdefcustom宣言の外部から別途値を追加できます。たとえばemacs-lisp-mode-hookから呼び出されることを意図した関数my-lisp-mode-initializationを定義する場合は、emacs-lisp-mode-hookにたいする正当な値として、その定義を編集することなくその関数をリストに追加したいと思うかもしれません。これは以下のようにして行うことができます:

(custom-add-frequent-value 'emacs-lisp-mode-hook
   'my-lisp-mode-initialization)

Function: custom-add-frequent-value symbol value

カスタマイズオプションsymbolにたいして正当な値のリストにvalueを追加する。

追加による正確な効果はsymbolのカスタマイズ型に依存する。

defcustomは内部的に、標準値にたいする式の記録にシンボルプロパティstandard-value、カスタマイゼーションバッファーでユーザーが保存した値の記録にsaved-value、カスタマイゼーションバッファーでユーザーがセットして未保存の値の記録にcustomized-valueを使用します。Symbol Propertiesを参照してください。これらのプロパティは、carがその値を評価する式であるようなリストです。

Function: custom-reevaluate-setting symbol

この関数はdefcustomを通じて宣言されたユーザーオプションsymbolの標準値を再評価する。変数がカスタマイズされたなら、この関数はかわりに保存された値を再評価する。それからこの関数はその値に、(もし定義されていればそのオプションの:setプロパティーを使用して)ユーザーオプションをセットする。

これは値が正しく計算される前に定義されたカスタマイズ可能オプションにたいして有用である。たとえばstartupの間、Emacsは事前ロードされたEmacs Lispファイルで定義されたユーザーオプションにたいしてこの関数を呼び出すが、これらの初期値は実行時だけ利用可能な情報に依存する。

Function: custom-variable-p arg

この関数はargがカスタマイズ可能変数なら非nilをリターンする。カスタマイズ可能変数とは、standard-valueかcustom-autoloadプロパティーをもつ(通常はdefcustomで宣言されたことを意味する)変数、または別のカスタマイズ可能変数にたいするエイリアスのことである。