12.11 Declaring Functions Obsolete

名前つき関数を陳腐化している(obsolete)とマークすることができます。これは、その関数が将来のある時点で削除されるかもしれないことを意味します。陳腐化しているとマークされた関数を含むコードをバイトコンパイルしたとき、Ｅｍａｃｓは警告を発します。また、その関数のヘルプドキュメントは表示されなくなります。他の点においては、陳腐化した関数は他の任意の関数と同様に振る舞います。

関数を陳腐化しているとマークするもっとも簡単な方法は、その関数のdefun定義に(declare (obsolete …))を配置することです。Declare Formを参照してください。かわりに、以下で説明しているmake-obsolete関数を使うこともできます。

make-obsoleteを使用して、マクロ(Macrosを参照してください)を陳腐化しているとマークすることもできます。これは関数のときと同じ効果をもちます。関数またはマクロにたいするエイリアスも、陳腐化しているとマークできます。これはエイリアス自身をマークし、名前解決される関数またはマクロにたいしてではありません。

Function: make-obsolete obsolete-name current-name &optional when

この関数は、obsolete-nameを陳腐化しているとマークします。obsolete-nameには関数またはマクロを名前づけるシンボル、、または関数やマクロにたいするエイリアスを指定します。

current-nameがシンボルの場合は、obsolete-nameのかわりにcurrent-nameの使用を促す警告メッセージになります。current-nameは、obsolete-nameにたいするエイリアスである必要はありません。似たような機能をもつ、別の関数かもしれません。current-nameには、警告メッセージとなる文字列も指定できます。メッセージは小文字で始まりピリオドで終えるべきです。nilも指定でき、この場合には警告メッセージに追加の詳細は提供されません。

whenが与えられた場合、それは最初にその関数が陳腐化する時期を示す文字列 — たとえば火付けやリリース番号を指定します。

Macro: define-obsolete-function-alias obsolete-name current-name &optional when doc

この便利なマクロは関数obsolete-nameを陳腐化しているとマークするとともに、それを関数current-nameのエイリアスにします。これは以下と等価です:

(defalias obsolete-name current-name doc)
(make-obsolete obsolete-name current-name when)

加えて、陳腐化した関数にたいする特定の呼び出し規約をマークできます。

Function: set-advertised-calling-convention function signature when

この関数は、functionを呼び出す正しい方法として、引数リストsignatureを指定します。これにより、Emacs Lispプログラムが他の方法でfunctionを呼び出している場合には、Emacsのバイトコンパイラーが警告を発します(それでもコードはバイトコンパイルされます)。whenには、その変数が最初に陳腐化するときを示す文字列(通常はバージョン番号)を指定します。

たとえば、古いバージョンのEmacsでは、sit-forには以下のように3つの引数を指定していました

  (sit-for seconds milliseconds nodisp)

しかしこの方法によるsit-forの呼び出しは陳腐化していると判断されます(Waitingを参照してください)。以下のように、古い呼び出し規約は推奨されません:

(set-advertised-calling-convention
  'sit-for '(seconds &optional nodisp) "22.1")