15.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を参照)。defcustomはそれぞれこのキーワードにたいする値を指定すること。

:options value-list

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

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

:set setfunction

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

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

:get getfunction

このオプションの値を抽出する方法としてgetfunctionを指定する。関数getfunctionは1つの引数(シンボル)を受け取り、カスタマイズがそのシンボル(シンボルのLisp値である必要はない)にたいするカレント値としてそれを使うべきかどうかをリターンすること。デフォルトは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-delay

この関数はcustom-initialize-setと同様に振る舞うが、実際の初期化をEmacsの次回起動時に遅延させる。これはビルド時ではなく実行時のコンテキストで初期化を行わせるように、事前ロードされるファイル(やautoloadされる変数)で使用すること。これは(遅延された)初期化が:set関数で処理されるという副作用ももつ。Building Emacsを参照のこと。

:local value

valueがtならoptionをバッファーローカルと自動的にマークする。値がpermanentならoptionのpermanent-localプロパティもtにセットする。Creating Buffer-Localを参照のこと。

: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を参照してください。以下は例です:

(defcustom frobnicate-automatically nil
  "Non-nil means automatically frobnicate all buffers."
  :type 'boolean
  :require 'frobnicate-mode
  :group 'frobnicate)

あるカスタマイゼーションアイテムが: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を参照してください。加えてテーマによりセットされた値の記録に使用されるthemed-valueも存在します(Custom Themesを参照)。これらのプロパティは、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で宣言されたことを意味する)変数、または別のカスタマイズ可能変数にたいするエイリアスのことである。