13.13 声明函数为废弃状态

你可以将一个具名函数标记为 废弃(obsolete) 状态,这意味着该函数可能会在未来的某个版本中被移除。当 Emacs 对包含该函数的代码进行字节编译时,或是在显示该函数的文档时,都会发出该函数已废弃的警告。除此之外,废弃函数的其他行为与普通函数完全一致。

将函数标记为废弃最简便的方式,是在函数的 defun 定义中加入 (declare (obsolete …)) 形式的声明。See declare 形式。你也可以使用下文所述的 make-obsolete 函数来实现该功能。

宏(see )也可通过 make-obsolete 标记为废弃状态,其效果与标记函数废弃完全相同。函数或宏的别名同样可以被标记为废弃;这种情况下,被标记为废弃的是别名本身,而非该别名指向的函数或宏。

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

该函数将 obsolete-name 标记为废弃状态。obsolete-name 应为一个符号,代表某个函数、宏,或是函数 / 宏的别名。

current-name 为符号,则警告信息会提示使用 current-name 替代 obsolete-namecurrent-name 无需是 obsolete-name 的别名,也可以是功能相近的另一个函数。current-name 也可为字符串,此时该字符串将直接作为警告信息使用。该信息应以小写字母开头,并以句点结尾;它也可以设为 nil,这种情况下警告信息不会包含任何额外说明。

参数 when 应为字符串类型,用于指明该函数首次被标记为废弃的时间 —— 例如某个日期或版本号。

Macro: define-obsolete-function-alias obsolete-name current-name when &optional 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

该函数将参数列表 signature 声明为调用 function 的正确形式。这样一来,只要 Emacs 字节编译器遇到以其他方式调用 function 的 Emacs Lisp 代码,就会发出警告(但仍然允许这段代码完成字节编译)。when 应为字符串,用于指明该调用方式首次被标记为废弃的时间(通常是版本号字符串)。

例如,在旧版 Emacs 中,sit-for 函数接受三个参数,形式如下:

  (sit-for seconds milliseconds nodisp)

在过渡阶段,该函数仍然支持这三个参数,但会像下面这样将旧的调用方式声明为已弃用:

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

该函数的替代方案是使用 advertised-calling-convention 类型的 declare 声明规范,详见 declare 形式


emacs

Emacs

org-mode

Orgmode

Donations

打赏

Copyright

© 2025 Jasper Hsu

Creative Commons

Creative Commons

Attribute

Attribute

Noncommercial

Noncommercial

Share Alike

Share Alike