Usage ​

The intended use-case for this library is for package developers to add as a dependency in the header. The version of the Compat library mirrors the version of Emacs releases. The current version of Compat corresponds to the current Emacs release.

emacs-lisp
;; Package-Requires: ((emacs "24.4") (compat "30.1.0.1"))

There is no need to depend on emacs 24.4 specifically. One can choose any newer version, if features not provided by Compat necessitate it, for example bug fixes or UI improvements.

In any file where compatibility forms are used, a

emacs-lisp
(require 'compat)

should be added early on. This will load all necessary Compat definitions. Compat loads the seq library which is preloaded by default on Emacs 29. Note that if Compat is installed on a recent version of Emacs, all of the definitions are disabled at compile time, such that no negative performance impact is incurred.

A minimal version of Compat will be present in Emacs version 30 and newer. Packages which are part of Emacs itself and want to take advantage of Compat, can also use (require 'compat). The advantage of the inclusion of a minimal Compat in Emacs is that Compat will not be installed if you require a version older or equal than the current Emacs version. For example, if a package depending on Emacs 25.1 and Compat 29.1 is installed on Emacs 30.1, Compat will not be pulled in as dependency, since Emacs 30.1 already provides the required functionality.

Compat provides replacement functions with extended functionality for functions that are already defined, e.g., sort or assoc. These functions may have changed their calling convention (additional optional arguments) or may have changed their behavior. These functions must be looked up explicitly with compat-function or called explicitly with compat-call. We call them Extended Definitions. In contrast, newly Added Definitions can be called as usual. The Compat manual explicitly documents the calling convention of each compatibility function.

emacs-lisp
(compat-call assoc key alist testfn) ;; Call extended `assoc'
(mapcan fun seq)                     ;; Call newly added `mapcan'

Macro: compat-call fun &rest args ​

This macro calls the compatibility function fun with args. Many functions provided by Compat can be called directly without this macro. However in the case where Compat provides an alternative version of an existing function, the function call has to go through compat-call. This happens for example when the calling convention of a function has changed.

Macro: compat-function fun ​

This macro returns the compatibility function symbol for fun. See compat-call for a more convenient macro to directly call compatibility functions.

If Compat is used in Emacs core packages, the macros compat-call and compat-function will be available in Emacs version 30 and newer.

The macros compat-call and compat-function are introduced by Compat, since Compat does not advise or override existing functions. Generally Compat is written in defensive style which is supposed to reduce potential breakage, and to increase the chances of staying binary compatible across releases. The extensive test coverage ensures that we can maintain high quality, which is crucial for Compat which is not restricted to a namespace like usual libraries.

If you intend to use a compatibility function in your code it is recommended that you take a look at the test suite compat-tests.el. There you can see the supported calling conventions, which are guaranteed to work on the supported Emacs versions. We ensure this using continuous integration. All functions provided by Compat are covered by the test suite. There is a link to the corresponding test on the first line of each definition.

You may want to subscribe to the compat-announce mailing list to be notified when new versions are released or relevant changes are made. We also provide a development mailing list (~pkal/compat-devel@lists.sr.ht).