16.5 autoload

オートロード(autoload: 自動ロード)の機能により、定義されているファイルをロードすることなく関数やマクロの存在を登録できます。関数の最初の呼び出しで実際の定義およびその他の関連するコードをインストールするために適切なライブラリーを自動的にロードして、すべてがすでにロードされていたかのように実際の定義を実行します。関数やマクロのドキュメントの参照(Documentation Basicsを参照)、変数名や関数名の補完(以下のAutoload by Prefixを参照)によってもオートロードが発生します。

オートロードされた関数をセットアップするには2つの方法があります。それはautoloadを呼び出す方法と、ソースの実際の定義の前に、“マジック”コメントを記述する方法です。autoloadはオートロードのための低レベルのプリミティブです。任意のLispプログラムが、任意のタイミングでautoloadを呼び出すことができます。Emacsとともにインストールされるパッケージにとって、マジックコメントは関数をオートロードできるようににするための一番便利な方法です。そのコメント自身は何も行いませんが、コマンドupdate-file-autoloadsにたいするガイドの役目を果たします。このコマンドはautoloadの呼び出しを構築して、Emacsビルド時に実行されるようにアレンジします。

Function: autoload function filename &optional docstring interactive type

この関数はfilenameから自動的にロードされるように、functionという名前の関数(かマクロ)を定義する。文字列filenameにはfunctionの実際の定義を取得するファイルを指定する。

filenameがディレクトリー名、またはサフィックス.elと.elcのいずれも含まなければ、この関数はこれらのサフィックスのいずれかを強制的に追加して、サフィックスがないただのfilenameという名前のファイルはロードしない(変数load-suffixesにより要求される正確なサフィックスが指定される)。

引数docstringはその関数のドキュメント文字列である。autoloadの呼び出しでドキュメント文字列を指定することにより、その関数の実際の定義をロードせずにドキュメントを見ることが可能になる。この引数の値は通常は関数定義のドキュメント文字列と等しいこと。もし等しくなければ、その関数定義のドキュメント文字列がロード時に有効になる。

interactiveが非nilなら、その関数はインタラクティブに呼び出すことが可能になる。これによりfunctionの実際の定義をロードせずに、M-xによる補完が機能するようになる。ここでは完全なインタラクティブ仕様は与えられない。完全な仕様はユーザーが実際にfunctionを呼び出すまで必要ない。ユーザーが実際に呼び出したときに、実際の定義がロードされる。

普通の関数と同様、マクロとキーマップをオートロードできる。functionが実際にはマクロならtypeにmacro、キーマップのならtypeにkeymapを指定する。Emacsのさまざまな部分では、実際の定義をロードせずにこれらの情報を知ることが必要とされる。

オートロードされたキーマップは、あるプレフィクスキーがシンボルfunctionにバインドされているとき、キーを探す間に自動的にロードされる。そのキーマップにたいする他の類のアクセスではオートロードは発生しない。特にLispプログラムが変数の値からそのキーマップを取得してdefine-keyを呼び出した場合には、たとえその変数の名前がシンボルfunctionと同じであってもオートロードは発生しない。

functionが非voidのオートロードされたオブジェクトではない関数定義をもつなら、その関数は何も行わずにnilをリターンする。それ以外ならオートロードされたオブジェクト(Autoload Typeを参照)を作成して、それをfunctionにたいする関数定義として格納する。オートロードされたオブジェクトは以下の形式をもつ:

(autoload filename docstring interactive type)

たとえば、

(symbol-function 'run-prolog)
     ⇒ (autoload "prolog" 169681 t nil)

このような場合、"prolog"はロードするファイルの名前、169681はemacs/etc/DOCファイル(Documentation Basicsを参照)内のドキュメント文字列への参照で、tはその関数がインタラクティブであること、nilはそれがマクロやキーマップでないことを意味する。

Function: autoloadp object

この関数はobjectがオートロードされたオブジェクトなら非nilをリターンする。たとえばrun-prologがオートロードされたオブジェクトかチェックするには以下を評価する

(autoloadp (symbol-function 'run-prolog))

オートロードされたファイルは、通常は他の定義を含み1つ以上の機能を必要としたり、あるいは提供するかもしれません。(内容の評価でのエラーにより)そのファイルが完全にロードされていなければ、そのロードの間に行われた関数定義やprovideの呼び出しはアンドゥされます。これはそのファイルからオートロードされる関数にたいして再度呼び出しを試みたときに、そのファイルを確実に再ロードさせるためです。こうしないと、そのファイル内のいくつかの関数はアボートしたロードにより定義されていて、それらはロードされない修正後のファイルで提供される正しいサブルーチンを欠くため、正しく機能しないからです。

オートロードされたファイルが意図したLisp関数またはマクロの定義に失敗すると、データ"Autoloading failed to define function function-name"とともにエラーがシグナルされます。

オートロードのマジックコメント(autoload cookieとも呼ばれる)は、オートロード可能なソースファイル内の実際の定義の直前にある、‘;;;###autoload’だけの行から構成されます。コマンドM-x update-file-autoloadsは、対応するautoload呼び出しをloaddefs.el内に書き込みます(autoload cookieとなる文字列とupdate-file-autoloadsで生成されるファイルの名前は上述のデフォルトから変更可能です。以下参照)。Emacsのビルドではloaddefs.elをロードするためにautoloadを呼び出します。M-x update-directory-autoloadsはより強力です。このコマンドはカレントディレクトリー内のすべてのファイルにたいするオートロードを更新します。

このマジックコメントは任意の種類のフォームをloaddefs.el内にコピーできます。このマジックコメントに続くフォームはそのままコピーされます。しかしオートロード機能が特別に処理するフォームの場合は除外されます(たとえばautoload内への変換)。以下はそのままコピーされないフォームです:

関数や関数風オブジェクトの定義:

defunとdefmacro。cl-defunとcl-defmacro(Argument Lists in Common Lisp Extensionsを参照)、およびdefine-overloadable-function (mode-local.el内のコメントを参照)も該当する。

メジャーモードとマイナーモードの定義:

define-minor-mode、define-globalized-minor-mode、define-generic-mode、define-derived-mode、easy-mmode-define-minor-mode、easy-mmode-define-global-mode、define-compilation-mode、define-global-minor-mode。

その他のタイプの定義:

defcustom、defgroup、defclass (EIEIO in EIEIOを参照)、およびdefine-skeleton (Autotyping in Autotypingを参照)。

ビルド時にそのファイル自身をロードするときにフォームを実行しないようにするためにマジックコメントを使用することもできます。これを行なうにはマジックコメントと同じ行にフォームを記述します。これはコメントなのでソースファイルをロードするときには何も行いません。ただしM-x update-file-autoloadsでは、Emacsビルド時に実行されたものはM-x update-file-autoloadsにコピーします。

以下はマジックコメントによるオートロードのためにdoctorを準備する例です:

;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))

これにより以下がloaddefs.el内に書き込まれます:

(autoload 'doctor "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.

\(fn)" t nil)

ダブルクォートの直後のバックスラッシュと改行は、loaddefs.elのようなプリロードされた未コンパイルのLispファイルだけに使用される慣習です。これはmake-docfileにたいして、ドキュメント文字列をetc/DOCファイルに配置するよう指示します。Building Emacsを参照してください。またlib-src/make-docfile.c内のコメントも参照してください。ドキュメント文字列の使い方(usage part)の中の‘(fn)’は、種々のヘルプ関数(Help Functionsを参照)が表示するときに、その関数の名前に置き換えられます。

関数定義手法として既知ではなく、認められてもいないような、通常とは異なるマクロにより関数定義を記述した場合、通常のオートロードのマジックコメントの使用によって定義全体がloaddefs.el内にコピーされるでしょう。これは期待した動作ではありません。かわりに以下を記述することにより、意図したautoload呼び出しをloaddefs.el内に配置することができます。

;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
  ...)

autoload cookieとしてデフォルト以外の文字列を使用して、デフォルトのloaddefs.elとは異なるファイル内に対応するオートロード呼び出しを記述できます。これを制御するためにEmacsは2つの変数を提供します:

Variable: generate-autoload-cookie

この変数の値はLispコメントの文法に準じた文字列である。M-x update-file-autoloadsはそのcookieの後のLispフォームを、cookieが生成したオートロードファイル内にコピーします。この変数のデフォルト値は";;;###autoload"。

Variable: generated-autoload-file

この変数の値は、オートロード呼び出しが書き込まれるEmacs Lispファイルを命名する。デフォルト値はloaddefs.elだが、(たとえば.elファイル内のセクションLocal Variables))をオーバーライドできる。オートロードファイルは、フォームフィード文字で開始される終端を含んでいると仮定される。

以下の関数はオートロードオブジェクトにより指定されたライブラリーを明示的にロードするために使用されるかもしれません:

Function: autoload-do-load autoload &optional name macro-only

この関数はオートロードオブジェクトautoloadにより指定されたロードを処理する。オプション引数nameに非nilを指定するなら、関数値がautoloadとなるシンボルを指定すること。この場合、この関数のリターン値がそのシンボルの新しい関数値になる。オプション引数macro-onlyの値がmacroなら、この関数は関数ではなくマクロのロードだけを有効にする。