14.3 Defining Customization Variables

カスタマイズ可能変数(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メソッドでreturnされる)カレント値を使用して: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を使用します。Symbol Propertiesを参照してください。これらのプロパティーは、carがその値を評価する式であるようなリストです。

Function: custom-reevaluate-setting symbol

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

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

Function: custom-variable-p arg

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