"Compat" Manual

Next:   [Contents][Index]

"Compat" Manual

This manual documents the usage of the "Compat" Emacs lisp library, the forward-compatibility library for Emacs Lisp, corresponding to version 30.0.0.0.

Copyright © 2022-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”

Table of Contents


Next: , Previous: , Up: "Compat" Manual   [Contents][Index]

1 Introduction


Next: , Up: Introduction   [Contents][Index]

1.1 Overview

The objective of Compat is to provide "forwards compatibility" library for Emacs Lisp. By using Compat, an Elisp package does not have to make the decision to either use new and useful functionality or support old versions of Emacs.

The library provides support back until Emacs 24.4. The intended audience are package developers that are interested in using newer developments, without having to break compatibility.


Next: , Previous: , Up: Introduction   [Contents][Index]

1.2 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.

;; Package-Requires: ((emacs "24.4") (compat "30.0.0.0"))

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

(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 newer 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.

(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).


Previous: , Up: Introduction   [Contents][Index]

1.3 Limitations

The Compat library has a number of limitations. Complete backwards compatibility cannot be provided due to the scope of Compat and for technical reasons. The scope is intentionally restricted in order to limit the size of Compat and to ensure that the library stays maintainable.

Emacs version 24.4 is chosen as the oldest version supported by Compat, since Elisp has seen significant changes at that version. Since 24.4 Emacs major versions consistently bump the major version number. On the library level, subr-x was introduced in 24.4. Most popular Emacs packages already require 24.4 or even newer versions of Emacs. Supporting for more historical Emacs versions would complicate maintenance while only few packages and users would benefit.

Below we list a number of reasons why certain functionality cannot be provided. Note that in some special cases exceptions can be made and functions can still be added to Compat even if they satisfy the criteria from the list. In case you miss functionality which you think should belong here, a report would be much appreciated.

  • The additional functionality is a command or a user-facing minor or major mode. Compat is limited to functionality on the “library level”. Generally functions provided by Compat are non-interactive, such that the user interface (M-x) is unaffected by the presence of Compat.
  • The function is not useful for package authors or not intended to be used by packages, but is only useful on the configuration level. The macro setopt is such an example.
  • Private (double dashed) functions are not ported back. If Compat includes some private functions, they are meant purely for internal usage.
  • The added or extended function belongs to the “application level” and not the “library level”. Features which are not preloaded often belong to the “application level”. Application examples are programming modes or modes like Dired, IRC and Gnus. If these modes are extended with new functions, these are not ported back.
  • An existing function or macro was extended by some new functionality. To support these cases, the function or macro would have to be advised. Since this is invasive and adds significant overhead, even when the new feature is not used, Compat does not use advices. As a compromise, compatibility functions and macros with a changed calling convention or behavior can be accessed via the compat-function and compat-call macros. In this manual we call such definitions Extended Definitions. An example is the function plist-get. Note that extended functions are subject to closer scrutiny, since their usage via compat-call is not completely painless. If a particular extended function does not see much usage or the extension yields only marginal benefits, we may not provide it as part of Compat.
  • Bug fixes are usually not ported back as part of Compat. Sometimes library functions show wrong behavior for edge cases. In those cases Compat could in principle provide a compatibility function which is invoked via compat-call. Such extended definitions would increase the maintenance burden of Compat. At the same time the benefits would be small given that Compat does not override existing definitions.
  • The definition belongs to an Emacs core package, which is also distributed via ELPA. Compat does not have to provide backward compatibility for core packages since the updated package can be installed directly from ELPA. Examples include the libraries xref, project, seq, map and transient.
  • New functionality depends on an entire new, non-trivial core library, which is infeasible to duplicate within Compat. If a backport of such a library is required, the preferred approach is to either release the library separately on GNU ELPA as a core package or as a separately maintained GNU ELPA package. An example is the iso8601 library.
  • New functionality was implemented in the C core, or depends on external libraries that cannot be reasonably duplicated in the scope of a compatibility library. Sometimes new functions on the C level rely on internal data structures, which we cannot access, rendering a backport impossible. For example a missing libxml or libtreesitter cannot be emulated.
  • The semantics of Elisp changed on a deep level. For example the addition of big integer support in Emacs 27.1 cannot be replicated on the level of Compat.

Next: , Previous: , Up: "Compat" Manual   [Contents][Index]

2 Support

This section goes into the features that Compat manages and doesn’t manage to provide for each Emacs version.


Next: , Up: Support   [Contents][Index]

2.1 Emacs 25.1

2.1.1 Added Definitions

The following functions and macros are implemented in Emacs 25.1. These functions are made available by Compat on Emacs versions older than 25.1.

User Option: text-quoting-style

The value of this user option is a symbol that specifies the style Emacs should use for single quotes in the wording of help and messages. If the option’s value is curve, the style is ‘like this’ with curved single quotes. If the value is straight, the style is 'like this' with straight apostrophes. If the value is grave, quotes are not translated and the style is `like this' with grave accent and apostrophe, the standard style before Emacs version 25. The default value nil acts like curve if curved single quotes seem to be displayable, and like grave otherwise.

This option is useful on platforms that have problems with curved quotes. You can customize it freely according to your personal preference.

Function: region-bounds

Return the boundaries of the region. Value is a list of one or more cons cells of the form (start . end). It will have more than one cons cell when the region is non-contiguous, see region-noncontiguous-p and extract-rectangle-bounds.

Function: region-noncontiguous-p

Return non-nil if the region contains several pieces. An example is a rectangular region handled as a list of separate contiguous regions for each line.

Macro: save-mark-and-excursion body…

This macro is like save-excursion, but also saves and restores the mark location and mark-active. This macro does what save-excursion did before Emacs 25.1.

Function: format-message string &rest objects

This function acts like format, except it also converts any grave accents (`) and apostrophes (') in string as per the value of text-quoting-style.

Typically grave accent and apostrophe in the format translate to matching curved quotes, e.g., "Missing `%s'" might result in "Missing ‘foo’". See (elisp)Text Quoting Style, for how to influence or inhibit this translation.

(elisp)Formatting Strings.

Function: directory-name-p filename

This function returns non-nil if filename ends with a directory separator character. This is the forward slash ‘/’ on GNU and other POSIX-like systems; MS-Windows and MS-DOS recognize both the forward slash and the backslash ‘\’ as directory separators.

See (elisp)Directory Names.

Function: string-greaterp string1 string2

This function returns the result of comparing string1 and string2 in the opposite order, i.e., it is equivalent to calling (string-lessp string2 string1).

See (elisp)Text Comparison.

Macro: with-file-modes mode body…

This macro evaluates the body forms with the default permissions for new files temporarily set to modes (whose value is as for set-file-modes above). When finished, it restores the original default file permissions, and returns the value of the last form in body.

This is useful for creating private files, for example.

See (elisp)Changing Files.

Function: alist-get key alist &optional default remove

This function is similar to assq. It finds the first association (key . value) by comparing key with alist elements, and, if found, returns the value of that association. If no association is found, the function returns default.

This is a generalized variable (see (elisp)Generalized Variables) that can be used to change a value with setf. When using it to set a value, optional argument remove non-nil means to remove key’s association from alist if the new value is eql to default.

(elisp)Association Lists.

Macro: if-let (bindings…) then &rest else…

As with let*, bindings will consist of (symbol value-form) entries that are evaluated and bound sequentially. If all value-form evaluate to non-nil values, then then is evaluated as were the case with a regular let* expression, with all the variables bound. If any value-form evaluates to nil, else is evaluated, without any bound variables.

A binding may also optionally drop the symbol, and simplify to (value-form) if only the test is of interest.

For the sake of backwards compatibility, it is possible to write a single binding without a binding list:

(if-let* (symbol (test)) foo bar)
≡
(if-let* ((symbol (test))) foo bar)
Macro: when-let (bindings…) &rest body

As with when, if one is only interested in the case where all bindings are non-nil. Otherwise bindings are interpreted just as they are by if-let*.

Function: hash-table-empty hash-table

Check whether hash-table is empty (has 0 elements).

Macro: thread-first &rest forms

Combine forms into a single expression by “threading” each element as the first argument of their successor. Elements of forms can either be an list of an atom.

For example, consider the threading expression and it’s equivalent macro expansion:

(thread-first
  5
  (+ 20)
  (/ 25)
  -
  (+ 40))
≡
(+ (- (/ (+ 5 20) 25)) 40)

Note how the single - got converted into a list before threading. This example uses arithmetic functions, but thread-first is not restricted to arithmetic or side-effect free code.

Macro: thread-last &rest forms

Combine forms into a single expression by “threading” each element as the last argument of their successor. Elements of forms can either be an list of an atom.

For example, consider the threading expression and it’s equivalent macro expansion:

(thread-first
  5
  (+ 20)
  (/ 25)
  -
  (+ 40))
≡
(+ 40 (- (/ 25 (+ 20 5))))

Note how the single - got converted into a list before threading. This example uses arithmetic functions, but thread-last is not restricted to arithmetic or side-effect free code.

Function: macroexpand-1 form &optional environment

This function expands macros like macroexpand, but it only performs one step of the expansion: if the result is another macro call, macroexpand-1 will not expand it.

See (elisp)Expansion.

Function: macroexp-quote e

Return an expression e such that (eval e) is v.

Function: macroexp-parse body

Parse a function body into (declarations . exps).

Function: bool-vector &rest objects

This function creates and returns a bool-vector whose elements are the arguments, objects.

See (elisp)Bool-Vectors.

2.1.2 Missing Definitions

Compat does not provide support for the following Lisp features implemented in 25.1:

  • The function macroexp-macroexpand.
  • The macro macroexp-let2*.
  • The function directory-files-recursively.
  • New pcase patterns.
  • The hook prefix-command-echo-keystrokes-functions and prefix-command-preserve-state-hook.
  • The hook pre-redisplay-functions.
  • The function make-process.
  • Support for the variable inhibit-message.
  • The define-inline functionality.
  • The functions string-collate-lessp and string-collate-equalp.
  • The function funcall-interactively.
  • The function buffer-substring-with-bidi-context.
  • The function font-info.
  • The function default-font-width.
  • The function window-font-height and window-font-width.
  • The function window-max-chars-per-line.
  • The function set-binary-mode.
  • The functions bufferpos-to-filepos and filepos-to-bufferpos.
  • The thunk library.

Next: , Previous: , Up: Support   [Contents][Index]

2.2 Emacs 26.1

2.2.1 Added Definitions

The following functions and macros are implemented in Emacs 26.1. These functions are made available by Compat on Emacs versions older than 26.1.

Function: assoc-delete-all key alist

This function is like assq-delete-all except that it uses equal to compare elements.

Function: read-answer question answers

This function prompts the user with text in question, which should end in the ‘SPC’ character. The function includes in the prompt the possible responses in answers by appending them to the end of question. The possible responses are provided in answers as an alist whose elements are of the following form:

(long-answer short-answer help-message)

where long-answer is the complete text of the user response, a string; short-answer is a short form of the same response, a single character or a function key; and help-message is the text that describes the meaning of the answer. If the variable read-answer-short is non-nil, the prompt will show the short variants of the possible answers and the user is expected to type the single characters/keys shown in the prompt; otherwise the prompt will show the long variants of the answers, and the user is expected to type the full text of one of the answers and end by pressing RET. If use-dialog-box is non-nil, and this function was invoked by mouse events, the question and the answers will be displayed in a GUI dialog box.

The function returns the text of the long-answer selected by the user, regardless of whether long or short answers were shown in the prompt and typed by the user.

Here is an example of using this function:

(let ((read-answer-short t))
  (read-answer "Foo "
     '(("yes"  ?y "perform the action")
       ("no"   ?n "skip to the next")
       ("all"  ?! "perform for the rest without more questions")
       ("help" ?h "show help")
       ("quit" ?q "exit"))))
Function: mapcan function sequence

This function applies function to each element of sequence, like mapcar, but instead of collecting the results into a list, it returns a single list with all the elements of the results (which must be lists), by altering the results (using nconc; see (elisp)Rearrangement). Like with mapcar, sequence can be of any type except a char-table.

;; Contrast this: (mapcar #'list '(a b c d)) ⇒ ((a) (b) (c)
(d)) ;; with this: (mapcan #'list '(a b c d)) ⇒ (a b c d)

See (elisp)Mapping Functions.

Function: cXXXr
Function: cXXXXr

See (elisp)List Elements.

Function: gensym &optional prefix

This function returns a symbol using make-symbol, whose name is made by appending gensym-counter to prefix and incrementing that counter, guaranteeing that no two calls to this function will generate a symbol with the same name. The prefix defaults to "g".

Variable: gensym-counter

See gensym.

Function: buffer-hash &optional buffer-or-name

Return a hash of buffer-or-name. If nil, this defaults to the current buffer. As opposed to secure-hash, this function computes the hash based on the internal representation of the buffer, disregarding any coding systems. It’s therefore only useful when comparing two buffers running in the same Emacs, and is not guaranteed to return the same hash between different Emacs versions. It should be somewhat more efficient on larger buffers than secure-hash is, and should not allocate more memory.

Macro: file-name-unquote name

This macro removes the quotation prefix ‘/:’ from the file name, if any. If name is a remote file name, the local part of name is unquoted.

Function: file-name-quoted-p name

This macro returns non-nil, when name is quoted with the prefix ‘/:’. If name is a remote file name, the local part of name is checked.

See (elisp)File Name Expansion.

Function: file-name-quote name

This macro adds the quotation prefix ‘/:’ to the file name. For a local file name, it prefixes name with ‘/:’. If name is a remote file name, the local part of name (see (elisp)Magic File Names) is quoted. If name is already a quoted file name, name is returned unchanged.

(substitute-in-file-name (compat-call file-name-quote "bar/~/foo")) ⇒
     "/:bar/~/foo"

(substitute-in-file-name (compat-call file-name-quote "/ssh:host:bar/~/foo"))
     ⇒ "/ssh:host:/:bar/~/foo"

The macro cannot be used to suppress file name handlers from magic file names (see (elisp)Magic File Names).

See (elisp)File Name Expansion.

Function: make-nearby-temp-file prefix &optional dir-flag suffix

This function is similar to make-temp-file, but it creates a temporary file as close as possible to default-directory. If prefix is a relative file name, and default-directory is a remote file name or located on a mounted file systems, the temporary file is created in the directory returned by the function temporary-file-directory. Otherwise, the function make-temp-file is used. prefix, dir-flag and suffix have the same meaning as in make-temp-file.

(let ((default-directory "/ssh:remotehost:")) (make-nearby-temp-file
  "foo")) ⇒ "/ssh:remotehost:/tmp/foo232J6v"
Variable: mounted-file-systems

A regular expression matching files names that are probably on a mounted file system.

Function: temporary-file-directory

The directory for writing temporary files via make-nearby-temp-file. In case of a remote default-directory, this is a directory for temporary files on that remote host. If such a directory does not exist, or default-directory ought to be located on a mounted file system (see mounted-file-systems), the function returns default-directory. For a non-remote and non-mounted default-directory, the value of the variable temporary-file-directory is returned.

See (elisp)Unique File Names.

Macro: if-let* (bindings…) then &rest else

if-let* is mostly equivalent to if-let, with the exception that the legacy (if (var (test)) foo bar) syntax is not permitted.

Macro: when-let* (bindings…) then &rest else

when-let* is mostly equivalent to when-let, with the exception that the legacy (when-let (var (test)) foo bar) syntax is not permitted.

Macro: and-let* (bindings…) &rest body

A combination of let* and and, analogous to when-let*. If all bindings are non-nil and body is nil, then the result of the and-let* form will be the last value bound in bindings.

Please Note: The implementation provided by Compat does not include a bug that was observed with Emacs 26 (see https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31840).

Function: file-local-name filename

This function returns the local part of filename. This is the part of the file’s name that identifies it on the remote host, and is typically obtained by removing from the remote file name the parts that specify the remote host and the method of accessing it. For example:

(file-local-name "/ssh:user@host:/foo/bar") ⇒
     "/foo/bar"

For a remote filename, this function returns a file name which could be used directly as an argument of a remote process (see (elisp)Asynchronous Processes, and see (elisp)Synchronous Processes), and as the program to run on the remote host. If filename is local, this function returns it unchanged.

See (elisp)Magic File Names.

Function: read-multiple-choice prompt choices

Ask user a multiple choice question. prompt should be a string that will be displayed as the prompt.

choices is an alist where the first element in each entry is a character to be entered, the second element is a short name for the entry to be displayed while prompting (if there’s room, it might be shortened), and the third, optional entry is a longer explanation that will be displayed in a help buffer if the user requests more help.

See (elisp)Reading One Event.

Function: image-property

Defined in image.el.

This function can also be used as a generalised variable.

Function: file-attribute-type

Return the field type as generated by file-attributes.

See (elisp)File Attributes.

Return the field link-number as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-user-id

Return the field user-id as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-group-id

Return the field group-id as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-access-time

Return the field access-time as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-modification-time

Return the field modification-time as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-status-change-time

Return the field modification-time as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-size

Return the field size as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-modes

Return the field modes as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-inode-number

Return the field inode-number as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-device-number

Return the field device-number as generated by file-attributes.

See (elisp)File Attributes.

Function: file-attribute-collect attributes &rest attr-names

Filter the file attributes attributes, as generated by file-attributes, according to attr-names.

Valid attribute names for attr-names are: type, link-number, user-id, group-id, access-time, modification-time, status-change-time, size, modes, inode-number and device-number.

(file-attributes ".") ⇒ (t 1 1000 1000 (25329 18215 325481 96000) (25325 15364 530263 840000) (25325 15364 530263 840000) 788 "drwxr-xr-x" t 137819 40)
(file-attribute-collect (file-attributes ".") 'type 'modes
'inode-number) ⇒ (t "drwxr-xr-x" 137819)

2.2.2 Extended Definitions

These functions must be called explicitly via compat-call, since their calling convention or behavior was extended in Emacs 26.1:

Function: compat-call make-temp-file prefix &optional dir-flag suffix text

This function creates a temporary file and returns its name. Emacs creates the temporary file’s name by adding to prefix some random characters that are different in each Emacs job. The result is guaranteed to be a newly created file, containing text if that’s given as a string and empty otherwise. On MS-DOS, this function can truncate prefix to fit into the 8+3 file-name limits. If prefix is a relative file name, it is expanded against temporary-file-directory.

The compatibility version adds support for handling the optional argument TEXT.

(make-temp-file "foo")
     ⇒ "/tmp/foo232J6v"

When make-temp-file returns, the file has been created and is empty. At that point, you should write the intended contents into the file.

If dir-flag is non-nil, make-temp-file creates an empty directory instead of an empty file. It returns the file name, not the directory name, of that directory. See (elisp)Directory Names.

If suffix is non-nil, make-temp-file adds it at the end of the file name.

If text is a string, make-temp-file inserts it in the file.

To prevent conflicts among different libraries running in the same Emacs, each Lisp program that uses make-temp-file should have its own prefix. The number added to the end of prefix distinguishes between the same application running in different Emacs jobs. Additional added characters permit a large number of distinct names even in one Emacs job.

Function: compat-call assoc key alist &optional testfn

This function returns the first association for key in alist, comparing key against the alist elements using testfn if it is a function, and equal otherwise (see (elisp)Equality Predicates). If testfn is a function, it is called with two arguments: the CAR of an element from alist and key. The function returns nil if no association in alist has a CAR equal to key, as tested by testfn.

See (elisp)Association Lists.

The compatibility version adds support for handling the optional argument testfn.

Function: compat-call line-number-at-pos &optional pos absolute

This function returns the line number in the current buffer corresponding to the buffer position pos. If pos is nil or omitted, the current buffer position is used. If absolute is nil, the default, counting starts at (point-min), so the value refers to the contents of the accessible portion of the (potentially narrowed) buffer. If absolute is non-nil, ignore any narrowing and return

See (elisp)Text Lines.

The compatibility version adds support for handling the optional argument absolute.

Function: compat-call alist-get key alist &optional default remove testfn

See (elisp)Association Lists. This function is similar to assq. It finds the first association (key . value) by comparing key with alist elements, and, if found, returns the value of that association. If no association is found, the function returns default. Comparison of key against alist elements uses the function specified by testfn, defaulting to eq.

See (elisp)Association Lists.

The compatibility version handles the optional argument testfn. It can also be used as a (elisp)Generalized Variables.

Function: compat-call string-trim-left string &optional regexp

Remove the leading text that matches regexp from string. regexp defaults to ‘[ \t\n\r]+’.

See (elisp)Creating Strings.

The compatibility version handles the optional argument regexp.

Function: compat-call string-trim-right string &optional regexp

Remove the trailing text that matches regexp from string. regexp defaults to ‘[ \t\n\r]+’.

See (elisp)Creating Strings.

The compatibility version handles the optional argument regexp.

Function: compat-call string-trim string &optional trim-left trim-right

Remove the leading text that matches trim-left and trailing text that matches trim-right from string. Both regexps default to ‘[ \t\n\r]+’.

See (elisp)Creating Strings.

The compatibility version handles the optional arguments trim-left and trim-right.

2.2.3 Missing Definitions

Compat does not provide support for the following Lisp features implemented in 26.1:

  • The function func-arity.
  • The function secure-hash-algorithms.
  • The function gnutls-available-p.
  • Support for records and record functions.
  • The function mapbacktrace.
  • The function file-name-case-insensitive-p.
  • The additional elements of parse-partial-sexp.
  • The function add-variable-watcher.
  • The function undo-amalgamate-change-group.
  • The function char-from-name
  • Signalling errors when length or member deal with list cycles.
  • The function frame-list-z-order.
  • The function frame-restack.
  • All changes related to display-buffer.
  • The function window-swap-states.
  • The function string-version-lessp.
  • The xdg library.
  • The svg library (published separately as a :core package).

Next: , Previous: , Up: Support   [Contents][Index]

2.3 Emacs 27.1

2.3.1 Added Definitions

The following functions and macros are implemented in Emacs 27.1. These functions are made available by Compat on Emacs versions older than 27.1.

Function: major-mode-suspend

This function works like fundamental-mode, in that it kills all buffer-local variables, but it also records the major mode in effect, so that it could subsequently be restored. This function and major-mode-restore (described next) are useful when you need to put a buffer under some specialized mode other than the one Emacs chooses for it automatically, but would also like to be able to switch back to the original mode later.

Function: major-mode-restore &optional avoided-modes

This function restores the major mode recorded by major-mode-suspend. If no major mode was recorded, this function calls normal-mode, but tries to force it not to choose any modes in avoided-modes, if that argument is non-nil.

Function: ring-resize ring size

Set the size of ring to size. If the new size is smaller, then the oldest items in the ring are discarded.

Function: minibuffer-history-value

Return the value of the minibuffer input history list. If minibuffer-history-variable points to a buffer-local variable and the minibuffer is active, return the buffer-local value for the buffer that was current when the minibuffer was activated."

Macro: with-minibuffer-selected-window &rest body

Execute the forms in body from the minibuffer in its original window. When used in a minibuffer window, select the window selected just before the minibuffer was activated, and execute the forms.

Function: read-char-from-minibuffer prompt &optional chars history

This function uses the minibuffer to read and return a single character. Optionally, it ignores any input that is not a member of chars, a list of accepted characters. The history argument specifies the history list symbol to use; if it is omitted or nil, this function doesn’t use the history.

If you bind help-form to a non-nil value while calling read-char-from-minibuffer, then pressing help-char causes it to evaluate help-form and display the result.

Function: bignump object

This predicate tests whether its argument is a large integer, and returns t if so, nil otherwise. Unlike small integers, large integers can be = or eql even if they are not eq.

Function: fixnump object

This predicate tests whether its argument is a small integer, and returns t if so, nil otherwise. Small integers can be compared with eq.

Special Form: with-suppressed-warnings warnings body…

In execution, this is equivalent to (progn body...), but the compiler does not issue warnings for the specified conditions in body. warnings is an association list of warning symbols and function/variable symbols they apply to. For instance, if you wish to call an obsolete function called foo, but want to suppress the compilation warning, say:

(with-suppressed-warnings ((obsolete foo))
  (foo ...))
Function: proper-list-p object

This function returns the length of object if it is a proper list, nil otherwise (see (elisp)Cons Cells). In addition to satisfying listp, a proper list is neither circular nor dotted.

(proper-list-p '(a b c)) ⇒ 3
(proper-list-p '(a b . c)) ⇒ nil

See (elisp)List-related Predicates.

Function: string-distance string1 string2 &optional bytecompare

This function returns the Levenshtein distance between the source string string1 and the target string string2. The Levenshtein distance is the number of single-character changes—deletions, insertions, or replacements—required to transform the source string into the target string; it is one possible definition of the edit distance between strings.

Letter-case of the strings is significant for the computed distance, but their text properties are ignored. If the optional argument bytecompare is non-nil, the function calculates the distance in terms of bytes instead of characters. The byte-wise comparison uses the internal Emacs representation of characters, so it will produce inaccurate results for multibyte strings that include raw bytes (see (elisp)Text Representations); make the strings unibyte by encoding them (see (elisp)Explicit Encoding) if you need accurate results with raw bytes.

See (elisp)Text Comparison.

Macro: ignore-errors body…

This construct executes body, ignoring any errors that occur during its execution. If the execution is without error, ignore-errors returns the value of the last form in body; otherwise, it returns nil.

Here’s the example at the beginning of this subsection rewritten using ignore-errors:

  (ignore-errors (delete-file filename))

See (elisp)Handling Errors.

Macro: dolist-with-progress-reporter (var count [result]) reporter-or-message body…

This is another convenience macro that works the same way as dolist does, but also reports loop progress using the functions described above. As in dotimes-with-progress-reporter, reporter-or-message can be a progress reporter or a string. You can rewrite the previous example with this macro as follows:

(dolist-with-progress-reporter (k (number-sequence 0 500)) "Collecting
    some mana for Emacs..."  (sit-for 0.01))

See (elisp)Progress.

Function: flatten-tree tree

This function returns a “flattened” copy of tree, that is, a list containing all the non-nil terminal nodes, or leaves, of the tree of cons cells rooted at tree. Leaves in the returned list are in the same order as in tree.

(flatten-tree '(1 (2 . 3) nil (4 5 (6)) 7)) ⇒(1 2 3 4 5 6 7)

See (elisp)Building Lists.

Function: xor condition1 condition2

This function returns the boolean exclusive-or of condition1 and condition2. That is, xor returns nil if either both arguments are nil, or both are non-nil. Otherwise, it returns the value of that argument which is non-nil.

Note that in contrast to or, both arguments are always evaluated.

See (elisp)Combining Conditions.

Variable: regexp-unmatchable

This variable contains a regexp that is guaranteed not to match any string at all. It is particularly useful as default value for variables that may be set to a pattern that actually matches something.

See (elisp)Regexp Functions

Function: decoded-time-second time

Return the seconds field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-minute time

Return the minute field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-hour time

Return the hour field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-day time

Return the day field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-month time

Return the month field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-year time

Return the year field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-weekday time

Return the weekday field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-dst time

Return the dst (daylight saving time indicator) field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: decoded-time-zone time

Return the zone field of a decoded-time record time. It can also be used as a (elisp)Generalized Variables.

Function: package-get-version

Return the version number of the package in which this is used.

Function: time-equal-p t1 t2

This returns t if the two time values t1 and t2 are equal.

See (elisp)Time Calculations.

Function: date-days-in-month year month

Return the number of days in month in year. For instance, February 2020 has 29 days.

See (elisp)Time Calculations. This function requires the time-date feature to be loaded.

Function: date-ordinal-to-time year ordinal

Convert a year/ordinal to the equivalent decoded-time structure. ordinal is the number of days since the start of the year, with January 1st being 1.

See (elisp)Time Calculations. This function requires the time-date feature to be loaded.

User Option: exec-path

The value of this variable is a list of directories to search for programs to run in subprocesses. Each element is either the name of a directory (i.e., a string), or nil, which stands for the default directory (which is the value of default-directory). See (elisp)executable-find, for the details of this search.

The value of exec-path is used by call-process and start-process when the program argument is not an absolute file name.

Generally, you should not modify exec-path directly. Instead, ensure that your PATH environment variable is set appropriately before starting Emacs. Trying to modify exec-path independently of PATH can lead to confusing results.

See (elisp)Subprocess Creation.

Function: provided-mode-derived-p mode &rest modes

This function returns non-nil if mode is derived from any of the major modes given by the symbols modes.

Function: file-size-human-readable-iec size

Human-readable string for size bytes, using IEC prefixes.

Function: make-empty-file filename &optional parents

This function creates an empty file named filename. As make-directory, this function creates parent directories if parents is non-nil. If filename already exists, this function signals an error.

Function: text-property-search-forward prop &optional value predicate not-current

Search for the next region that has text property prop set to value according to predicate.

This function is modeled after search-forward and friends in that it moves point, but it returns a structure that describes the match instead of returning it in match-beginning and friends.

If the text property can’t be found, the function returns nil. If it’s found, point is placed at the end of the region that has this text property match, and a prop-match structure is returned.

predicate can either be t (which is a synonym for equal), nil (which means “not equal”), or a predicate that will be called with two parameters: The first is value, and the second is the value of the text property we’re inspecting.

If not-current, if point is in a region where we have a match, then skip past that and find the next instance instead.

The prop-match structure has the following accessors: prop-match-beginning (the start of the match), prop-match-end (the end of the match), and prop-match-value (the value of property at the start of the match).

In the examples below, imagine that you’re in a buffer that looks like this:

This is a bold and here's bolditalic and this is the end.

That is, the “bold” words are the bold face, and the “italic” word is in the italic face.

With point at the start:

(while (setq match (text-property-search-forward 'face 'bold t))
  (push (buffer-substring (prop-match-beginning match)
                          (prop-match-end match))
        words))

This will pick out all the words that use the bold face.

(while (setq match (text-property-search-forward 'face nil t))
  (push (buffer-substring (prop-match-beginning match)
                          (prop-match-end match))
        words))

This will pick out all the bits that have no face properties, which will result in the list ‘("This is a " "and here's " "and this is the end")’ (only reversed, since we used push).

(while (setq match (text-property-search-forward 'face nil nil))
  (push (buffer-substring (prop-match-beginning match)
                          (prop-match-end match))
        words))

This will pick out all the regions where face is set to something, but this is split up into where the properties change, so the result here will be ‘("bold" "bold" "italic")’.

For a more realistic example where you might use this, consider that you have a buffer where certain sections represent URLs, and these are tagged with shr-url.

(while (setq match (text-property-search-forward 'shr-url nil nil))
  (push (prop-match-value match) urls))

This will give you a list of all those URLs.

See (Property Search)elisp.

Function: text-property-search-backward prop &optional value predicate not-current

This is just like text-property-search-forward, but searches backward instead. Point is placed at the beginning of the matched region instead of the end, though.

See (Property Search)elisp.

2.3.2 Extended Definitions

These functions must be called explicitly via compat-call, since their calling convention or behavior was extended in Emacs 27.1:

Function: compat-call recenter &optional count redisplay

This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does not move point with respect to the text.

See (elisp)Textual Scrolling.

This compatibility version adds support for the optional argument redisplay.

Function: compat-call lookup-key keymap key &optional accept-defaults

This function returns the definition of key in keymap. If the string or vector key is not a valid key sequence according to the prefix keys specified in keymap, it must be too long and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of key that compose a complete key.

See (elisp)Low-Level Key Binding.

This compatibility version allows for keymap to be a list of keymaps, instead of just a singular keymap.

Macro: compat-call setq-local &rest pairs

pairs is a list of variable and value pairs. This macro creates a buffer-local binding in the current buffer for each of the variables, and gives them a buffer-local value. It is equivalent to calling make-local-variable followed by setq for each of the variables. The variables should be unquoted symbols.

(setq-local var1 "value1"
            var2 "value2")

See (elisp)Creating Buffer-Local.

This compatibility version allows for more than one variable to be set at once, as can be done with setq.

Function: compat-call regexp-opt strings &optional paren

This function returns an efficient regular expression that will match any of the strings in the list strings. This is useful when you need to make matching or searching as fast as possible—for example, for Font Lock mode.

See (elisp)Regexp Functions.

The compatibility version of this functions handles the case where strings in an empty list. In that case, a regular expression is generated that never matches anything (see regexp-unmatchable).

Function: compat-call file-size-human-readable file-size &optional flavor space unit

Return a string with a human readable representation of file-size.

The optional second argument flavor controls the units and the display format. If flavor is…

  • si, each kilobyte is 1000 bytes and the produced suffixes are k, M, G, T, etc.
  • iec, each kilobyte is 1024 bytes and the produced suffixes are KiB, MiB, GiB, TiB, etc.
  • nil or omitted, each kilobyte is 1024 bytes and the produced suffixes are k, M, G, T, etc.

The compatibility version handles the optional third (space) and forth (unit) arguments. The argument space can be a string that is placed between the number and the unit. The argument unit determines the unit to use. By default it will be an empty string, unless flavor is iec, in which case it will be B.

Function: compat-call assoc-delete-all key alist &optional test

This function is like assq-delete-all except that it accepts an optional argument test, a predicate function to compare the keys in alist. If omitted or nil, test defaults to equal. As assq-delete-all, this function often modifies the original list structure of alist.

See (elisp)Association Lists.

This compatibility version handles the optional third (testfn) argument.

Function: compat-call executable-find program &optional remote

This function searches for the executable file of the named program and returns the absolute file name of the executable, including its file-name extensions, if any. It returns nil if the file is not found. The function searches in all the directories in exec-path, and tries all the file-name extensions in exec-suffixes (see (elisp)Subprocess Creation).

If remote is non-nil, and default-directory is a remote directory, program is searched on the respective remote host.

See (elisp)Locating Files.

This compatibility version adds support to handle the optional second (remote) argument.

2.3.3 Missing Definitions

Compat does not provide support for the following Lisp features implemented in 27.1:

  • The functions base64url-encode-*.
  • The function decoded-time-add.
  • The function decoded-time-set-defaults.
  • The function time-convert.
  • The macro benchmark-progn.
  • Support for condition-case to handle t.
  • The function file-system-info.
  • The function group-name.
  • The function face-extend-p and set-face-extend.
  • Additional format-spec modifiers.
  • Support for additional body forms for define-globalized-minor-mode.
  • The macro with-connection-local-variables and related functionality.
  • The iso8601 library.
  • The exif library.
  • The image-converter library.

Next: , Previous: , Up: Support   [Contents][Index]

2.4 Emacs 28.1

2.4.1 Added Definitions

The following functions and macros are implemented in Emacs 28.1. These functions are made available by Compat on Emacs versions older than 28.1.

The defcustom type natnum introduced in Emacs 28.1 is made available by Compat.

Function: process-lines-ignore-status program &rest args

This function is just like process-lines, but does not signal an error if program exits with a non-zero exit status.

Function: process-lines-handling-status program status-handler &rest args

Execute program with args, returning its output as a list of lines. If status-handler is non-nil, it must be a function with one argument, which will be called with the exit status of the program before the output is collected. If status-handler is nil, an error is signaled if the program returns with a non-zero exit status.

Function: text-quoting-style

You should not read the value of the variable text-quoting-style directly. Instead, use this function with the same name to dynamically compute the correct quoting style on the current terminal in the nil case described above.

Function: string-search needle haystack &optional start-pos

Return the position of the first instance of needle in haystack, both of which are strings. If start-pos is non-nil, start searching from that position in needle. Return nil if no match was found. This function only considers the characters in the strings when doing the comparison; text properties are ignored. Matching is always case-sensitive.

Function: length= sequence length

Return non-nil if the length of sequence is equal to length.

Function: length< sequence length

Return non-nil if sequence is shorter than length. This may be more efficient than computing the length of sequence if sequence is a long list.

Function: length> sequence length

Return non-nil if sequence is longer than length.

Function: file-name-concat directory &rest components

Concatenate components to directory, inserting a slash before the components if directory or the preceding component didn’t end with a slash.

(file-name-concat "/tmp" "foo") ⇒ "/tmp/foo"

A directory or components that are nil or the empty string are ignored—they are filtered out first and do not affect the results in any way.

This is almost the same as using concat, but dirname (and the non-final components) may or may not end with slash characters, and this function will not double those characters.

Function: garbage-collect-maybe factor

Suggest to run garbage collection, if enough data has been allocated. This is determined by the positive numerical argument factor, that would proportionally increase the likelihood of garbage collection taking place.

This compatibility function does nothing and ignores any suggestion.

Function: string-replace from-string to-string in-string

This function replaces all occurrences of from-string with to-string in in-string and returns the result. It may return one of its arguments unchanged, a constant string or a new string. Case is significant, and text properties are ignored.

Function: always &rest arguments

This function ignores any arguments and returns t.

See (elisp)Calling Functions.

Function: make-separator-line &optional length

Make a string appropriate for usage as a visual separator line. If length is nil, use the window width.

Function: insert-into-buffer to-buffer &optional start end

This is like insert-buffer-substring, but works in the opposite direction: The text is copied from the current buffer into to-buffer. The block of text is copied to the current point in to-buffer, and point (in that buffer) is advanced to after the end of the copied text. Is start/end is nil, the entire text in the current buffer is copied over.

See (elisp)Insertion.

Function: replace-string-in-region regexp replacement &optional start end

This function replaces all the occurrences of regexp with replacement in the region of buffer text between start and end; start defaults to position of point, and end defaults to the last accessible position of the buffer. The search for regexp is case-sensitive, and replacement is inserted without changing its letter-case. The replacement string can use the same special elements starting with ‘\’ as replace-match does. The function returns the number of replaced occurrences, or nil if regexp is not found. The function preserves the position of point.

(replace-regexp-in-region "foo[ \t]+bar" "foobar")

See (elisp)Search and Replace.

Function: replace-regexp-in-string string replacement &optional start end

This function works similarly to replace-regexp-in-region, but searches for, and replaces, literal strings instead of regular expressions.

See (elisp)Search and Replace.

Function: buffer-local-boundp variable buffer

This returns non-nil if there’s either a buffer-local binding of variable (a symbol) in buffer buffer, or variable has a global binding.

See (elisp)Creating Buffer-Local.

Macro: with-existing-directory body…

This macro ensures that default-directory is bound to an existing directory before executing body. If default-directory already exists, that’s preferred, and otherwise some other directory is used. This macro can be useful, for instance, when calling an external command that requires that it’s running in a directory that exists. The chosen directory is not guaranteed to be writable.

See (elisp)Testing Accessibility.

Macro: dlet (bindings…) forms…

This special form is like let, but it binds all variables dynamically. This is rarely useful—you usually want to bind normal variables lexically, and special variables (i.e., variables that are defined with defvar) dynamically, and this is what let does.

dlet can be useful when interfacing with old code that assumes that certain variables are dynamically bound (see (elisp)Dynamic Binding), but it’s impractical to defvar these variables. dlet will temporarily make the bound variables special, execute the forms, and then make the variables non-special again.

See (elisp)Local Variables.

Function: ensure-list object

This function returns object as a list. If object is already a list, the function returns it; otherwise, the function returns a one-element list containing object.

This is usually useful if you have a variable that may or may not be a list, and you can then say, for instance:

(dolist (elem (ensure-list foo))
  (princ elem))

See (elisp)Building Lists.

Function: string-clean-whitespace string

Clean up the whitespace in string by collapsing stretches of whitespace to a single space character, as well as removing all whitespace from the start and the end of string.

See (elisp)Creating Strings.

Function: string-fill string length

Attempt to Word-wrap string so that no lines are longer than length. Filling is done on whitespace boundaries only. If there are individual words that are longer than length, these will not be shortened.

See (elisp)Creating Strings.

Function: string-lines string &optional omit-nulls

Split string into a list of strings on newline boundaries. If the optional argument omit-nulls is non-nil, remove empty lines from the results. Note that this function returns trailing newlines on Emacs 28, use compat-call string-lines instead if you want consistent behavior.

Function: string-pad string length &optional padding start

Pad string to be of the given length using padding as the padding character. padding defaults to the space character. If string is longer than length, no padding is done. If start is nil or omitted, the padding is appended to the characters of string, and if it’s non-nil, the padding is prepended to string’s characters.

See (elisp)Creating Strings.

Function: string-chop-newline string

Remove the final newline, if any, from string.

See (elisp)Creating Strings.

Macro: named-let name bindings &rest body

This special form is a looping construct inspired from the Scheme language. It is similar to let: It binds the variables in bindings, and then evaluates body. However, named-let also binds name to a local function whose formal arguments are the variables in bindings and whose body is body. This allows body to call itself recursively by calling name, where the arguments passed to name are used as the new values of the bound variables in the recursive invocation.

Recursive calls to name that occur in tail positions in body are guaranteed to be optimized as tail calls, which means that they will not consume any additional stack space no matter how deeply the recursion runs. Such recursive calls will effectively jump to the top of the loop with new values for the variables.

See (elisp)Local Variables.

Function: file-name-with-extension filename extension

This function returns filename with its extension set to extension. A single leading dot in the extension will be stripped if there is one. For example:

(file-name-with-extension "file" "el")
     ⇒ "file.el"
(file-name-with-extension "file" ".el")
     ⇒ "file.el"
(file-name-with-extension "file.c" "el")
     ⇒ "file.el"

Note that this function will error if filename or extension are empty, or if the filename is shaped like a directory (i.e., if directory-name-p returns non-nil).

See (elisp)File Name Components.

Function: directory-empty-p directory

This utility function returns t if given directory is an accessible directory and it does not contain any files, i.e., is an empty directory. It will ignore ‘.’ and ‘..’ on systems that return them as files in a directory.

Symbolic links to directories count as directories. See file-symlink-p to distinguish symlinks.

See (elisp)Contents of Directories.

Function: format-prompt prompt default &rest format-args

Format prompt with default value default according to the minibuffer-default-prompt-format variable.

minibuffer-default-prompt-format is a format string (defaulting to ‘" (default %s)"’ that says how the “default” bit in prompts like ‘"Local filename (default somefile): "’ are to be formatted.

To allow the users to customize how this is displayed, code that prompts the user for a value (and has a default) should look something along the lines of this code snippet:

(read-file-name
 (format-prompt "Local filename" file)
 nil file)

If format-args is nil, prompt is used as a literal string. If format-args is non-nil, prompt is used as a format control string, and prompt and format-args are passed to format (see (elisp)Formatting Strings).

minibuffer-default-prompt-format can be ‘""’, in which case no default values are displayed.

If default is nil, there is no default value, and therefore no “default value” string is included in the result value. If default is a non-nil list, the first element of the list is used in the prompt.

See (elisp)Text from Minibuffer.

Function: thing-at-mouse event thing &optional no-properties

Mouse-event equivalent of thing-at-point. thing can be symbol, list, sexp, filename, url, … among other things.

When no-properties has a non-nil value, any text properties that might have been present in the buffer are stripped away.

Function: bounds-of-thing-at-mouse event thing

Determine start and end locations for thing at mouse click given by event. Like bounds-of-thing-at-point, but tries to use the position in event where the mouse button is clicked to find the thing nearby.

Function: mark-thing-at-mouse click thing

Activate the region around thing found near the mouse click.

Function: macroexp-file-name

Return the name of the file in which the code is currently being evaluated, or nil if it cannot be determined.

Function: macroexp-warn-and-return msg form &optional category compile-only arg

Return code equivalent to form labeled with warning msg.

Macro: with-environment-variables variables body…

This macro sets the environment variables according to variables temporarily when executing body. The previous values are restored when the form finishes. The argument variables should be a list of pairs of strings of the form (var value), where var is the name of the environment variable and value is that variable’s value.

(with-environment-variables (("LANG" "C")
                             ("LANGUAGE" "en_US:en"))
  (call-process "ls" nil t))

See (elisp)System Environment.

Function: color-dark-p rgb

Whether rgb is more readable against white than black. rgb is a 3-element list (R G B), each component in the range [0,1]. This predicate can be used both for determining a suitable (black or white) contrast color with rgb as background and as foreground.

Function: color-values-from-color-spec spec

Convert the textual color specification spec to a color triple (red green blue). Each of red, green and blue is a integer value between 0 and 65535.

The specification spec can be one of the following

  • #RGB, where R, G and B are hex numbers of equal length, 1-4 digits each.
  • rgb:R/G/B, where R, G, and B are hex numbers, 1-4 digits each.
  • rgbi:R/G/B, where R, G and B are floating-point numbers in [0,1].
Function: file-modes-number-to-symbolic modes

This function converts a numeric file mode specification in modes into the equivalent symbolic form.

See (elisp)Changing Files.

Function: file-backup-file-names filename

This function returns a list of all the backup file names for filename, or nil if there are none. The files are sorted by modification time, descending, so that the most recent files are first.

See (elisp)Backup Names.

Function: make-lock-file-name filename

Return a string containing a lock file name for filename, obeying lock-file-name-transforms.

Function: decoded-time-period time

Interpret time as a period and return its length in seconds. For computational purposes, years are 365 days long and months are 30 days long.

Function: subr-primitive-p object

Return t if object is a primitive, built-in function. On systems with native compilation subrp does not distinguish between built-in functions and functions that have been compiled. If native compilation is not available, this function behaves identically to subrp.

Function: native-comp-available-p

This function returns non-nil if the running Emacs process has the native-compilation support compiled into it. On systems that load libgccjit dynamically, it also makes sure that library is available and can be loaded. Lisp programs that need to know up front whether native-compilation is available should use this predicate.

Macro: with-window-non-dedicated window &rest body

Evaluate body with window temporarily made non-dedicated. If window is nil, use the selected window. Return the value of the last form in body.

2.4.2 Extended Definitions

These functions must be called explicitly via compat-call, since their calling convention or behavior was extended in Emacs 28.1:

Function: compat-call string-width string &optional from to

This function returns the width in columns of the string string, if it were displayed in the current buffer and the selected window. Optional arguments from and to specify the substring of string to consider, and are interpreted as in substring (see (elisp)Creating Strings).

The return value is an approximation: it only considers the values returned by char-width for the constituent characters, always takes a tab character as taking tab-width columns, ignores display properties and fonts, etc.

See (elisp)Size of Displayed Text.

This compatibility version handles the optional arguments from and to.

Function: compat-call count-windows

Return the number of live windows on the selected frame.

The optional argument minibuf specifies whether the minibuffer window is included in the count.

If all-frames is non-nil, count the windows in all frames instead just the selected frame.

This compatibility version handles the optional argument all-frames.

2.4.3 Missing Definitions

Compat does not provide support for the following Lisp features implemented in 28.1:

  • Support for interactive or declare to list applicable modes.
  • Support for :interactive argument to define-minor-mode and define-derived-mode.
  • Support for :predicate argument to define-globalized-minor-mode.
  • Support for the :success handler of condition-case.
  • The function benchmark-call.
  • Additional Edebug keywords.
  • The libjansson JSON APIs, e.g., json-parse-string.
  • The macro pcase-setq.
  • The function custom-add-choice.
  • The functions dom-print and dom-remove-attribute.
  • The function dns-query-asynchronous.
  • The function get-locale-names.
  • The functions mail-header-parse-addresses-lax and mail-header-parse-address-lax.
  • The function num-processors.
  • The function object-intervals.
  • The function require-theme.
  • The function syntax-class-to-char.
  • The function path-separator.
  • The function null-device.
  • The function macroexp-compiling-p.
  • The function split-string-shell-command.
  • The function string-limit.
  • The functions innermost-minibuffer-p and minibuffer-innermost-command-loop-p.
  • The function max-mini-window-lines.
  • The function lock-file and unlock-file.
  • The multisession library.

Next: , Previous: , Up: Support   [Contents][Index]

2.5 Emacs 29.1

2.5.1 Added Definitions

The following functions and macros are implemented in Emacs 29.1. These functions are made available by Compat on Emacs versions older than 29.1. Note that due to upstream changes, it might happen that there will be the need for changes, so use these functions with care.

The defcustom type key introduced in Emacs 29.1 is made available by Compat.

Variable: lisp-directory

This variable holds a string naming the directory which holds Emacs’s own *.el and *.elc files. This is usually the place where those files are located in the Emacs installation tree, unless Emacs is run from its build directory in which case it points to the lisp subdirectory in the source directory from which Emacs was built.

Function: count-sentences start end

Count sentences in current buffer from start to end.

Function: readablep object

This predicate says whether object has readable syntax, i.e., it can be written out and then read back by the Emacs Lisp reader. If it can’t, this function returns nil; if it can, this function returns a printed representation (via prin1).

Function: substitute-quotes string

This function works like substitute-command-keys, but only replaces quote characters.

Function: get-scratch-buffer-create

Return the *scratch* buffer, creating a new one if needed.

Function: use-region-noncontiguous-p

Return non-nil for a non-contiguous region if use-region-p.

Function: use-region-end

Return the end of the region if use-region-p.

Function: use-region-beginning

Return the start of the region if use-region-p.

Macro: buffer-local-set-state variable value...

Minor modes often set buffer-local variables that affect some features in Emacs. When a minor mode is switched off, the mode is expected to restore the previous state of these variables. This convenience macro helps with doing that: It works much like setq-local, but returns an object that can be used to restore these values back to their previous values/states (using the companion function buffer-local-restore-state).

Function: delete-line

Delete the current line.

Function: list-of-strings-p object

Return t if object is nil or a list of strings.

Function: plistp object

Non-nil if and only if object is a valid plist.

Macro: with-memoization place code

This macro provides a simple way to do memoization. code is evaluated and then stashed in place. If place’s value is non-nil, return that value instead of evaluating code.

Special Form: with-restriction start end [:label label] body

This special form saves the current bounds of the accessible portion of the buffer, sets the accessible portion to start at start and end at end, evaluates the body forms, and restores the saved bounds. In that case it is equivalent to

(save-restriction
  (narrow-to-region start end)
  body)

When the optional argument label, a symbol, is present, the narrowing is labeled. A labeled narrowing differs from a non-labeled one in several ways:

  • During the evaluation of the body form, narrow-to-region and widen can be used only within the start and end limits.
  • To lift the restriction introduced by with-restriction and gain access to other portions of the buffer, use without-restriction with the same label argument. (Another way to gain access to other portions of the buffer is to use an indirect buffer (see (elisp)Indirect Buffers).)
  • Labeled narrowings can be nested.
  • Labeled narrowings can only be used in Lisp programs: they are never visible on display, and never interfere with narrowings set by the user.

If you use with-restriction with the optional label argument, we recommend documenting the label in the doc strings of the functions which use it, so that other Lisp programs your code calls could lift the labeled narrowing if and when it needs.

Special Form: without-restriction [:label label] body

This special form saves the current bounds of the accessible portion of the buffer, widens the buffer, evaluates the body forms, and restores the saved bounds. In that case it is equivalent to

(save-restriction
  (widen)
  body)

When the optional argument label is present, the narrowing set by with-restriction with the same label argument is lifted.

Function: pos-bol &optional count

Like line-beginning-position, but ignores fields (and is more efficient).

Function: pos-eol &optional count

Like line-end-position, but ignores fields (and is more efficient).

Function: char-uppercase-p char

Return non-nil if char is an uppercase character according to Unicode.

Macro: with-delayed-message (timeout message) body…

Sometimes it’s unclear whether an operation will take a long time to execute or not, or it can be inconvenient to implement a progress reporter. This macro can be used in those situations.

(with-delayed-message (2 (format "Gathering data for %s" entry))
  (setq data (gather-data entry)))

In this example, if the body takes more than two seconds to execute, the message will be displayed. If it takes a shorter time than that, the message won’t be displayed. In either case, the body is evaluated as normally, and the return value of the final element in the body is the return value of the macro.

The message element is evaluated before body, and is always evaluated, whether the message is displayed or not.

Function: funcall-with-delayed-message timeout message function

Like funcall, but display message if function takes longer than timeout. timeout is a number of seconds, and can be an integer or a floating point number.

If function takes less time to execute than timeout seconds, message is not displayed.

Function: buttonize string callback &optional data help-echo

Sometimes it’s more convenient to make a string into a button without inserting it into a buffer immediately, for instance when creating data structures that may then, later, be inserted into a buffer. This function makes string into such a string, and callback will be called when the user clicks on the button. The optional data parameter will be used as the parameter when callback is called. If nil, the button is used as the parameter instead.

Function: buttonize-region start end callback &optional data help-echo

Make the region between start and end into a button. When clicked, callback will be called with the data as the function argument. If data isn’t present (or is nil), the button itself will be used instead as the function argument. If help-echo, use that as the help-echo property.

Function: get-display-property position prop &optional object properties

This convenience function can be used to get a specific display property, no matter whether the display property is a vector, a list or a simple property. This is like get-text-property (see (elisp)Examining Properties), but works on the display property only.

position is the position in the buffer or string to examine, and prop is the display property to return. The optional object argument should be either a string or a buffer, and defaults to the current buffer. If the optional properties argument is non-nil, it should be a display property, and in that case, position and object are ignored. (This can be useful if you’ve already gotten the display property with get-char-property, for instance (see (elisp)Examining Properties).

Function: add-display-text-property start end prop value &optional object

Add display property prop with value to the text from start to end. If any text in the region has a non-nil display property, those properties are retained.

If object is non-nil, it should be a string or a buffer. If nil, this defaults to the current buffer.

Function: take n list

This function returns the n first elements of list. Essentially, it returns the part of list that nthcdr skips.

take returns list if shorter than n elements; it returns nil if n is zero or negative.

(take 3 '(a b c d))
     ⇒ (a b c)
(take 10 '(a b c d))
     ⇒ (a b c d)
(take 0 '(a b c d))
     ⇒ nil
Function: ntake n list

This is a version of take that works by destructively modifying the list structure of the argument. That makes it faster, but the original value of list may be lost.

ntake returns list unmodified if shorter than n elements; it returns nil if n is zero or negative. Otherwise, it returns list truncated to its first n elements.

This means that it is usually a good idea to use the return value and not just rely on the truncation effect unless n is known to be positive.

Function: compiled-function-p object

This function returns t if object is a function object that is not in the form of ELisp source code but something like machine code or byte code instead. More specifically it returns t if the function is built-in, or byte-compiled, or natively-compiled, or a function loaded from a dynamic module.

Function: function-alias-p object &optional noerror

Checks whether object is a function alias. If it is, it returns a list of symbols representing the function alias chain, else nil. For instance, if a is an alias for b, and b is an alias for c:

(function-alias-p 'a)
    ⇒ (b c)

If there’s a loop in the definitions, an error will be signalled. If noerror is non-nil, the non-looping parts of the chain is returned instead.

Function: string-equal-ignore-case string1 string2

string-equal-ignore-case compares strings ignoring case differences, like char-equal when case-fold-search is t.

See (elisp)Text Comparison.

Function: string-split string &optional separators omit-nulls trim

string-split is an alias for the function split-string. The name follows the convention of other string functions.

See (elisp)Creating Strings.

Function: buffer-match-p condition buffer-or-name &optional arg

This function checks if a buffer designated by buffer-or-name satisfies a condition. Optional third argument arg is passed to the predicate function in condition. A condition can be one of the following:

  • A string, interpreted as a regular expression. The buffer satisfies the condition if the regular expression matches the buffer name.
  • A predicate function, which should return non-nil if the buffer matches. If the function expects one argument, it is called with buffer-or-name as the argument; if it expects 2 arguments, the first argument is buffer-or-name and the second is arg (or nil if arg is omitted).
  • A cons-cell (oper . expr) where oper is one of
    not

    Satisfied if expr doesn’t satisfy buffer-match-p with the same buffer and arg.

    or

    Satisfied if expr is a list and any condition in expr satisfies buffer-match-p, with the same buffer and arg.

    and

    Satisfied if expr is a list and all conditions in expr satisfy buffer-match-p, with the same buffer and arg.

    derived-mode

    Satisfied if the buffer’s major mode derives from expr.

    major-mode

    Satisfied if the buffer’s major mode is equal to expr. Prefer using derived-mode instead when both can work.

  • t Satisfied by any buffer. A convenient alternative to "" (empty string), (and) (empty conjunction) or always.

See (elisp)Buffer List.

Function: match-buffers condition &optional buffers arg

This function returns a list of all buffers that satisfy a condition, as defined for buffer-match-p. By default all buffers are considered, but this can be restricted via the second optional buffer-list argument. Optional third argument arg will be used by condition in the same way as buffer-match-p does.

See (elisp)Buffer List.

Function: string-glyph-split string

When character compositions are in effect, sequence of characters can be composed for display to form grapheme clusters, for example to display accented characters, or ligatures, or Emoji, or when complex text shaping requires that for some scripts. When that happens, characters no longer map in a simple way to display columns, and display layout decisions with such strings, such as truncating too wide strings, can be a complex job. This function helps in performing such jobs: it splits up its argument string into a list of substrings, where each substring produces a single grapheme cluster that should be displayed as a unit. Lisp programs can then use this list to construct visually-valid substrings of string which will look correctly on display, or compute the width of any substring of string by adding the width of its constituents in the returned list, etc.

For instance, if you want to display a string without the first glyph, you can say:

(apply #'insert (cdr (string-glyph-split string))))

See (elisp)Size of Displayed Text.

Macro: with-buffer-unmodified-if-unchanged &rest body…

Evaluate body like progn, but change buffer-modified status only if buffer text changes. If the buffer was unmodified before execution of body, and buffer text after execution of body is identical to what it was before, ensure that buffer is still marked unmodified afterwards.

Note that only changes in the raw byte sequence of the buffer text, as stored in the internal representation, are monitored for the purpose of detecting the lack of changes in buffer text. Any other changes that are normally perceived as "buffer modifications", such as changes in text properties, buffer-file-coding-system, buffer multibyteness, etc. – will not be noticed, and the buffer will still be marked unmodified, effectively ignoring those changes.

Function: file-attribute-file-identifier

Return the fields (inodenum device) as a list from attributes generated by file-attributes.

See (elisp)File Attributes.

Function: file-name-split filename

This function splits a file name into its components, and can be thought of as the inverse of string-join with the appropriate directory separator. For example,

(file-name-split "/tmp/foo.txt")
    ⇒ ("" "tmp" "foo.txt")
(string-join (file-name-split "/tmp/foo.txt") "/")
    ⇒ "/tmp/foo.txt"
Function: file-name-parent-directory filename

This function returns the directory name of the parent directory of filename. If filename is at the root directory of the filesystem, it returns nil. A relative filename is assumed to be relative to default-directory, and the return value will also be relative in that case. If the return value is non-nil, it ends in a slash.

See (elisp)Directory Names.

Function: file-has-changed-p file &optional tag

This function returns non-nil if the time stamp of filename has changed since the last call. When called for the first time for some filename, it records the last modification time and size of the file, and returns non-nil when filename exists. Thereafter, when called for the same filename, it compares the current time stamp and size with the recorded ones, and returns non-nil only if either the time stamp or the size (or both) are different. This is useful when a Lisp program wants to re-read a file whenever it changes. With an optional argument tag, which must be a symbol, the size and modification time comparisons are limited to calls with the same tag.

See (elisp)File Attributes.

Function: directory-abbrev-make-regexp directory

Create a regexp to match directory for directory-abbrev-alist.

Function: directory-abbrev-apply filename

Apply the abbreviations in directory-abbrev-alist to filename. Note that when calling this, you should set case-fold-search as appropriate for the filesystem used for filename.

Function: key-valid-p keys

Say whether keys is a valid key. A key is a string consisting of one or more key strokes. The key strokes are separated by single space characters.

Each key stroke is either a single character, or the name of an event, surrounded by angle brackets. In addition, any key stroke may be preceded by one or more modifier keys. Finally, a limited number of characters have a special shorthand syntax.

Here’s some example key sequences.

f

The key f.

S o m

A three key sequence of the keys S, o and m.

C-c o

A two key sequence of the keys c with the control modifier and then the key o.

H-<left>

The key named "left" with the hyper modifier.

M-RET

The "return" key with a meta modifier.

C-M-<space>

The "space" key with both the control and meta modifiers.

These are the characters that have shorthand syntax: NUL, RET, TAB, LFD, ESC, SPC, DEL.

Modifiers have to be specified in this order

Alt (A)-Control (C)-Hyper (H)-Meta (M)-Shift (s)-Super (s)
Function: key-parse keys

Convert keys to the internal Emacs key representation. See key-valid-p for a description of valid key sequences. Examples include f, C-c C-c, H-<left>, M-RET or C-M-<return>.

Function: keymap-set keymap key definition

This function sets the binding for key in keymap. (If key is more than one event long, the change is actually made in another keymap reached from keymap.) The argument binding can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see (elisp)Key Lookup.) The value returned by keymap-set is binding.

If key is <t>, this sets the default binding in keymap. When an event has no binding of its own, the Emacs command loop uses the keymap’s default binding, if there is one.

Every prefix of key must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of key is undefined, then keymap-set defines it as a prefix key so that the rest of key can be defined as specified.

If there was previously no binding for key in keymap, the new binding is added at the beginning of keymap. The order of bindings in a keymap makes no difference for keyboard input, but it does matter for menu keymaps (see (elisp)Menu Keymaps).

See (elisp)Changing Key Bindings.

Function: keymap-global-set key command

This function sets the binding of key in the current global map to binding.

(keymap-global-set key binding)
≡
(keymap-set (current-global-map) key binding)

See (elisp)Key Binding Commands.

Function: keymap-local-set key command

This function sets the binding of key in the current local keymap to binding.

(keymap-local-set key binding)
≡
(keymap-set (current-local-map) key binding)

See (elisp)Key Binding Commands.

Function: keymap-global-unset key &optional remove

This function removes the binding of key from the current global map.

One use of this function is in preparation for defining a longer key that uses key as a prefix—which would not be allowed if key has a non-prefix binding. For example:

(keymap-global-unset "C-l")
    ⇒ nil
(keymap-global-set "C-l C-l" 'redraw-display)
    ⇒ nil

See (elisp)Key Binding Commands.

Function: keymap-local-unset key &optional remove

This function removes the binding of key from the current local map.

See (elisp)Key Binding Commands.

Function: keymap-substitute keymap olddef newdef &optional oldmap prefix

Replace olddef with newdef for any keys in keymap now defined as olddef. In other words, olddef is replaced with newdef wherever it appears. Alternatively, if optional fourth argument oldmap is specified, we redefine in keymap as newdef those keys that are defined as olddef in oldmap.

Function: keymap-lookup keymap key &optional accept-default no-remap position

This function returns the definition of key in keymap. All the other functions described in this chapter that look up keys use keymap-lookup. Here are examples:

(keymap-lookup (current-global-map) "C-x C-f")
    ⇒ find-file
(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5")
    ⇒ 2

See (elisp)Functions for Key Lookup.

Function: keymap-local-lookup keys &optional accept-default

Like keymap-lookup, but restricting the search for commands bound to keys to the current local keymap.

Function: keymap-global-lookup keys &optional accept-default

Like keymap-lookup, but restricting the search for commands bound to keys to the current global keymap.

Function: define-keymap &rest definitions

You can create a keymap with the functions described above, and then use keymap-set (see (elisp)Changing Key Bindings) to specify key bindings in that map. When writing modes, however, you frequently have to bind a large number of keys at once, and using keymap-set on them all can be tedious and error-prone. Instead you can use define-keymap, which creates a keymap and binds a number of keys. Here’s a very basic example:

(define-keymap
  "n" #'forward-line
  "f" #'previous-line
  "C-c C-c" #'quit-window)

This function creates a new sparse keymap, defines the keystrokes in pairs, and returns the new keymap.

pairs is a list of alternating key bindings and key definitions, as accepted by keymap-set. In addition, the key can be the special symbol :menu, in which case the definition should be a menu definition as accepted by easy-menu-define (see (elisp)Easy Menu). Here’s a brief example of this usage:

(define-keymap :full t
  "g" #'eww-reload
  :menu '("Eww"
          ["Exit" quit-window t]
          ["Reload" eww-reload t]))

A number of keywords can be used before the key/definition pairs to change features of the new keymap. If any of the feature keywords is missing from the define-keymap call, the default value for that feature is nil. Here’s a list of the available feature keywords:

:full

If non-nil, create a char-table keymap (as from make-keymap) instead of a sparse keymap (as from make-sparse-keymap (see (elisp)Creating Keymaps). A sparse keymap is the default.

:parent

If non-nil, the value should be a keymap to use as the parent (see (elisp)Inheritance and Keymaps).

:keymap

If non-nil, the value should be a keymap. Instead of creating a new keymap, the specified keymap is modified instead.

:suppress

If non-nil, the keymap will be suppressed with suppress-keymap (see (elisp)Changing Key Bindings). By default, digits and the minus sign are exempt from suppressing, but if the value is nodigits, this suppresses digits and minus-sign like it does with other characters.

:name

If non-nil, the value should be a string to use as the menu for the keymap if you use it as a menu with x-popup-menu (see (elisp)Pop-Up Menus).

:prefix

If non-nil, the value should be a symbol to be used as a prefix command (see (elisp)Prefix Keys). If this is the case, this symbol is returned by define-keymap instead of the map itself.

Function: defvar-keymap (variable-name &rest defs)

By far, the most common thing to do with a keymap is to bind it to a variable. This is what virtually all modes do—a mode called foo almost always has a variable called foo-mode-map.

This macro defines name as a variable, passes options and pairs to define-keymap, and uses the result as the default value for the variable.

options is like the keywords in define-keymap, but there’s an additional :doc keyword that provides the doc string for the defined variable.

Here’s an example:

(defvar-keymap eww-textarea-map
  :parent text-mode-map
  "RET" #'forward-line
  "TAB" #'shr-next-link)
Macro: while-let spec then-forms...

Like when-let, but repeat until a binding in spec is nil. The return value is always nil.

This is comparable to and-let*.

Function: window-configuration-equal-p config1 config2

This function says whether two window configurations have the same window layout, but ignores the values of point and the saved scrolling positions—it can return t even if those aspects differ.

Macro: ert-with-temp-file name &rest body

Bind name to the name of a new temporary file and evaluate body. Delete the temporary file after body exits normally or non-locally. name will be bound to the file name of the temporary file. See the docstring for supported keyword arguments.

Macro: ert-with-temp-directory name &rest body

Bind name to the name of a new temporary directory and evaluate body. Delete the temporary directory after body exits normally or non-locally.

name is bound to the directory name, not the directory file name. (In other words, it will end with the directory delimiter; on Unix-like systems, it will end with "/".)

The same keyword arguments are supported as in ert-with-temp-file (which see), except for :text.

Function: cl-constantly value

Return a function that takes any number of arguments, but returns value.

Macro: cl-with-gensyms names… body

This macro expands to code that executes body with each of the variables in names bound to a fresh uninterned symbol, or gensym, in Common Lisp parlance. For macros requiring more than one gensym, use of cl-with-gensyms shortens the code and renders one’s intentions clearer. Compare:

(defmacro my-macro (foo)
  (let ((bar (gensym "bar"))
        (baz (gensym "baz"))
        (quux (gensym "quux")))
    `(let ((,bar (+ …)))
       …)))

(defmacro my-macro (foo)
  (cl-with-gensyms (bar baz quux)
    `(let ((,bar (+ …)))
       …)))
Macro: cl-once-only ((variable form)…) body

This macro is primarily to help the macro programmer ensure that forms supplied by the user of the macro are evaluated just once by its expansion even though the result of evaluating the form is to occur more than once. Less often, this macro is used to ensure that forms supplied by the macro programmer are evaluated just once.

Each variable may be used to refer to the result of evaluating form in body. cl-once-only binds each variable to a fresh uninterned symbol during the evaluation of body. Then, cl-once-only wraps the final expansion in code to evaluate each form and bind the result to the corresponding uninterned symbol. Thus, when the macro writer substitutes the value for variable into the expansion they are effectively referring to the result of evaluating form, rather than form itself. Another way to put this is that each variable is bound to an expression for the (singular) result of evaluating form.

The most common case is where variable is one of the arguments to the macro being written, so (variable variable) may be abbreviated to just variable.

For example, consider this macro:

(defmacro my-list (x y &rest forms)
  (let ((x-result (gensym))
        (y-result (gensym)))
    `(let ((,x-result ,x)
           (,y-result ,y))
       (list ,x-result ,y-result ,x-result ,y-result
             (progn ,@forms))))

In a call like (my-list (pop foo) …) the intermediate binding to x-result ensures that the pop is not done twice. But as a result the code is rather complex: the reader must keep track of how x-result really just means the first parameter of the call to the macro, and the required use of multiple gensyms to avoid variable capture by (progn ,@forms) obscures things further. cl-once-only takes care of these details:

(defmacro my-list (x y &rest forms)
  (cl-once-only (x y)
    `(list ,x ,y ,x ,y
           (progn ,@forms))))

2.5.2 Extended Definitions

These functions must be called explicitly via compat-call, since their calling convention or behavior was extended in Emacs 29.1:

Function: compat-call set-transient-map keymap &optional keep-pred on-exit message timeout

This function adds keymap as a transient keymap, which takes precedence over other keymaps for one (or more) subsequent keys.

Normally, keymap is used just once, to look up the very next key. If the optional argument keep-pred is t, the map stays active as long as the user types keys defined in keymap; when the user types a key that is not in keymap, the transient keymap is deactivated and normal key lookup continues for that key.

The keep-pred argument can also be a function. In that case, the function is called with no arguments, prior to running each command, while keymap is active; it should return non-nil if keymap should stay active.

The optional argument on-exit, if non-nil, specifies a function that is called, with no arguments, after keymap is deactivated.

The optional argument message specifies the message to display after activating the transient map. If message is a string, it is the format string for the message, and any ‘%k’ specifier in that string is replaced with the list of keys from the transient map. Any other non-nil value of message stands for the default message format ‘Repeat with %k’.

If the optional argument timeout is non-nil, it should be a number that specifies how many seconds of idle time to wait before deactivating keymap. The value of the variable set-transient-map-timeout, if non-nil, overrides the value of this argument.

This function works by adding and removing keymap from the variable overriding-terminal-local-map, which takes precedence over all other active keymaps (see (Searching Keymaps)elisp).

Function: compat-call string-lines string &optional omit-nulls keep-newlines

Split string into a list of strings on newline boundaries. If the optional argument omit-nulls is non-nil, remove empty lines from the results. If the optional argument keep-newlines is non-nil, don’t remove the trailing newlines from the result strings.

See (elisp)Creating Strings.

Function: compat-call define-key

This function is like keymap-set (see (elisp)Changing Key Bindings, but understands only the legacy key syntaxes.

In addition, this function also has a remove argument. If it is non-nil, the definition will be removed. This is almost the same as setting the definition to nil, but makes a difference if the keymap has a parent, and key is shadowing the same binding in the parent. With remove, subsequent lookups will return the binding in the parent, whereas with a nil definition the lookups will return nil.

See (elisp)Low-Level Key Binding.

This compatibility version handles the optional argument remove.

Function: compat-call plist-get plist prop &optional predicate

This returns the value of the property property stored in the property list plist. Comparisons are done with predicate, and defaults to eq. It accepts a malformed plist argument. If property is not found in the plist, it returns nil.

See (elisp)Plist Access.

This compatibility version handles the optional argument predicate. This is a generalized variable (see (elisp)Generalized Variables) that can be used to change a value with setf.

Function: compat-call plist-put plist prop val &optional predicate

This stores value as the value of the property property in the property list plist. Comparisons are done with predicate, and defaults to eq. It may modify plist destructively, or it may construct a new list structure without altering the old. The function returns the modified property list, so you can store that back in the place where you got plist.

See (elisp)Plist Access.

This compatibility version handles the optional argument predicate.

Function: compat-call plist-member plist prop &optional predicate

This returns non-nil if plist contains the given property. Comparisons are done with predicate, and defaults to eq. Unlike plist-get, this allows you to distinguish between a missing property and a property with the value nil. The value is actually the tail of plist whose car is property.

See (elisp)Plist Access.

This compatibility version handles the optional argument predicate.

2.5.3 Missing Definitions

Compat does not provide support for the following Lisp features implemented in 29.1:

  • The function imagep.
  • The function image-at-point-p.
  • The function function-documentation.
  • The macro with-undo-amalgamate.
  • The function string-glyph-split.
  • The function string-limit.
  • The function string-pixel-width and buffer-text-pixel-size.
  • The function minibuffer-lazy-highlight-setup.
  • The function pp-emacs-lisp-code.
  • The function bidi-string-strip-control-characters.
  • The native function current-cpu-time.
  • The functions xdg-state-home, xdg-current-desktop and xdg-session-type.
  • The macro setopt.
  • The oclosure library.
  • The textsec library.
  • The range library.
  • The string-edit library.
  • The vtable library.
  • The pixel-fill library.
  • Support for symbols with position information.

Previous: , Up: Support   [Contents][Index]

2.6 Emacs 30.1

2.6.1 Added Definitions

The following functions and macros are implemented in Emacs 30.1. These functions are made available by Compat on Emacs versions older than 30.1. Note that due to upstream changes, it might happen that there will be the need for changes, so use these functions with care.

Function: char-to-name char

This function returns the Unicode name of char. It returns nil if char is not a character or has no Unicode name.

Function: obarray-clear obarray

This function removes all symbols from obarray.

Function: closurep object

This function returns t if object is a closure, which is a particular kind of function object. Currently closures are used for all byte-code functions and all interpreted functions.

Function: interpreted-function-p object

This function returns t if object is an interpreted function.

Function: primitive-function-p object

Return t if object is a built-in primitive function. This excludes special forms, since they are not functions.

Function: value< a b

This function returns non-nil if a comes before b in the standard sorting order; this means that it returns nil when b comes before a, or if they are equal or unordered.

The arguments a and b must have the same type. Specifically:

  • Numbers are compared using <.
  • Strings are compared using string< and symbols are compared by comparing their names as strings.
  • Conses, lists, vectors and records are compared lexicographically. This means that the two sequences are compared element-wise from left to right until they differ, and the result is then that of value< on the first pair of differing elements. If one sequence runs out of elements before the other, the shorter sequence comes before the longer.
  • Markers are compared first by buffer, then by position.
  • Buffers and processes are compared by comparing their names as strings. Dead buffers (whose name is nil) will compare before any live buffer.
  • Other types are considered unordered and the return value will be nil.

Examples:

(value< -4 3.5) ⇒ t
(value< "dog" "cat") ⇒ nil
(value< 'yip 'yip) ⇒ nil
(value< '(3 2) '(3 2 0)) ⇒ t
(value< [3 2 "a"] [3 2 "b"]) ⇒ t

Note that nil is treated as either a symbol or an empty list, depending on what it is compared against:

(value< nil '(0)) ⇒ t
(value< 'nib nil) ⇒ t

There is no limit to the length of sequences (lists, vectors and so on) that can be compared, but value< may fail with an error if used to compare circular or deeply nested data structures.

Function: drop n list

This function is an alias for nthcdr. It returns the nth CDR of list. In other words, it skips past the first n links of list and returns what follows.

Function: get-truename-buffer filename

Return the buffer with file-truename equal to filename (a string). If there is no such live buffer, return nil. See also find-buffer-visiting.

Function: find-buffer variable value

Return the buffer with buffer-local variable equal to value. If there is no such live buffer, return nil.

Function: require-with-check feature &optional filename noerror

This function works like require, except if feature is already loaded (i.e. is already a member of the list in features, see below). If feature is already loaded, this function checks if feature was provided by a file different from filename, and if so, it by default signals an error. If the value of the optional argument noerror is reload, the function doesn’t signal an error, but instead forcibly reloads filename; if noerror is some other non-nil value, the function emits a warning about feature being already provided by another file.

Function: merge-ordered-lists lists &optional error-function

Merge lists in a consistent order. lists is a list of lists of elements. Merge them into a single list containing the same elements (removing duplicates), obeying their relative positions in each list. The order of the (sub)lists determines the final order in those cases where the order within the sublists does not impose a unique choice. Equality of elements is tested with eql.

If a consistent order does not exist, call error-function with a remaining list of lists that we do not know how to merge. It should return the candidate to use to continue the merge, which has to be the head of one of the lists. By default we choose the head of the first list.

Variable: completion-lazy-hilit

If non-nil, request lazy highlighting of completion candidates.

Lisp programs (a.k.a. "front ends") that present completion candidates may opt to bind this variable to a non-nil value when calling functions (such as completion-all-completions) which produce completion candidates. This tells the underlying completion styles that they do not need to fontify (i.e., propertize with the face property) completion candidates in a way that highlights the matching parts. Then it is the front end which presents the candidates that becomes responsible for this fontification. The front end does that by calling the function completion-lazy-hilit on each completion candidate that is to be displayed to the user.

Note that only some completion styles take advantage of this variable for optimization purposes. Other styles will ignore the hint and fontify eagerly as usual. It is still safe for a front end to call completion-lazy-hilit in these situations.

To author a completion style that takes advantage of this variable, see completion-lazy-hilit-fn and completion-pcm--hilit-commonality.

Variable: completion-lazy-hilit-fn

Fontification function set by lazy-highlighting completions styles. When a given style wants to enable support for completion-lazy-hilit (which see), that style should set this variable to a function of one argument. It will be called with each completion candidate, a string, to be displayed to the user, and should destructively propertize these strings with the face property.

Function: completion-lazy-hilit str

Return a copy of completion candidate str that is face-propertized. See documentation of the variable completion-lazy-hilit for more details.

Macro: static-if condition then-form else-forms...

Test condition at macro-expansion time. If its value is non-nil, expand the macro to then-form, otherwise expand it to else-forms enclosed in a progn. else-forms may be empty.

Here is an example of its use from CC Mode, which prevents a defadvice form being compiled in newer versions of Emacs:

(static-if (boundp 'comment-line-break-function)
    (progn)
  (defvar c-inside-line-break-advice nil)
  (defadvice indent-new-comment-line (around c-line-break-advice
                                             activate preactivate)
    "Call `c-indent-new-comment-line' if in CC Mode."
    (if (or c-inside-line-break-advice
            (not c-buffer-is-cc-mode))
        ad-do-it
      (let ((c-inside-line-break-advice t))
        (c-indent-new-comment-line (ad-get-arg 0))))))

2.6.2 Extended Definitions

These functions must be called explicitly via compat-call, since their calling convention or behavior was extended in Emacs 30.1:

Function: compat-call sort sequence &rest keyword-args

This function sorts sequence, which must be a list or vector, and returns a sorted sequence of the same type. The sort is stable, which means that elements with equal sort keys maintain their relative order. It takes the following optional keyword arguments:

:key keyfunc

Use keyfunc, a function that takes a single element from sequence and returns its key value, to generate the keys used in comparison. If this argument is absent or if keyfunc is nil then identity is assumed; that is, the elements themselves are used as sorting keys.

:lessp predicate

Use predicate to order the keys. predicate is a function that takes two sort keys as arguments and returns non-nil if the first should come before the second. If this argument is absent or predicate is nil, then value< is used, which is applicable to many different Lisp types and generally sorts in ascending order.

For consistency, any predicate must obey the following rules:

  • It must be antisymmetric: it cannot both order a before b and b before a.
  • It must be transitive: if it orders a before b and b before c, then it must also order a before c.
:reverse flag

If flag is non-nil, the sorting order is reversed. With the default :lessp predicate this means sorting in descending order.

:in-place flag

If flag is non-nil, then sequence is sorted in-place (destructively) and returned. If nil, or if this argument is not given, a sorted copy of the input is returned and sequence itself remains unmodified. In-place sorting is slightly faster, but the original sequence is lost.

If the default behaviour is not suitable for your needs, it is usually easier and faster to supply a new :key function than a different :lessp predicate. For example, consider sorting these strings:

(setq numbers '("one" "two" "three" "four" "five" "six"))
(sort numbers)
     ⇒ ("five" "four" "one" "six" "three" "two")

You can sort the strings by length instead by supplying a different key function:

(sort numbers :key #'length)
     ⇒ ("one" "two" "six" "four" "five" "three")

Note how strings of the same length keep their original order, thanks to the sorting stability. Now suppose you want to sort by length, but use the string contents to break ties. The easiest way is to specify a key function that transforms an element to a value that is sorted this way. Since value< orders compound objects (conses, lists, vectors and records) lexicographically, you could do:

(sort numbers :key (lambda (x) (cons (length x) x)))
     ⇒ ("one" "six" "two" "five" "four" "three")

because (3 . "six") is ordered before (3 . "two") and so on.

For compatibility with previous versions of Emacs, the sort function can also be called using the fixed two-argument form:

(sort sequence predicate)

where predicate is the :lessp argument. When using this form, sorting is always done in-place.

Function: compat-call completion-metadata-get metadata prop

Get property prop from completion metadata. If the metadata specifies a completion category, the variables completion-category-overrides and completion-category-defaults take precedence for category-specific overrides. If the completion metadata does not specify the property, the completion-extra-properties plist is consulted. Note that the keys of the completion-extra-properties plist are keyword symbols, not plain symbols.

Function: compat-call copy-tree tree &optional vectors-and-records

This function returns a copy of the tree tree. If tree is a cons cell, this makes a new cons cell with the same CAR and CDR, then recursively copies the CAR and CDR in the same way.

Normally, when tree is anything other than a cons cell, copy-tree simply returns tree. However, if vectors-and-records is non-nil, it copies vectors and records too (and operates recursively on their elements). The tree argument must not contain cycles.

2.6.3 Missing Definitions

Compat does not provide support for the following Lisp features implemented in 30.1:


Next: , Previous: , Up: "Compat" Manual   [Contents][Index]

3 Development

Compat is developed on GitHub.

Bug reports, patches and comments are best sent to the issue tracker. These may include issues in the compatibility code, missing definitions or performance issues. We also provide a development mailing list (~pkal/compat-devel@lists.sr.ht).

Please note that as a GNU ELPA package, Compat requires contributors to have signed the FSF copyright assignment, before any non-trivial contribution (roughly 15 lines of code) can be applied.

It is important that you provide tests when you contribute new functionality. Compat has 100% test coverage by the test suite. We use continuous integration to check if patches preserve existing functionality.

Development for the currently stable Emacs version happens in the main branch of the Compat Git repository. ELPA-devel nightly builds are created from this branch. New features, which are not yet ready to be merged directly into the main branch, are developed in feature branches. Furthermore the Git repository has a branch emacs-<version> where the development for the upcoming Emacs release takes place. This branch is separate from the main branch since the new functionality should not be made available (neither via ELPA nor ELPA-devel) before the new Emacs version has been reasonably stabilized, e.g., around the time when the Emacs version branch is created in the Emacs repository on Savannah.


Appendix A Function Index

Jump to:   A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   R   S   T   U   V   W   X  
Index Entry  Section

A
add-display-text-property: Emacs 29.1
alist-get: Emacs 25.1
always: Emacs 28.1
and-let*: Emacs 26.1
assoc-delete-all: Emacs 26.1

B
bignump: Emacs 27.1
bool-vector: Emacs 25.1
bounds-of-thing-at-mouse: Emacs 28.1
buffer-hash: Emacs 26.1
buffer-local-boundp: Emacs 28.1
buffer-local-restore-state: Emacs 29.1
buffer-local-set-state: Emacs 29.1
buffer-match-p: Emacs 29.1
buttonize: Emacs 29.1
buttonize-region: Emacs 29.1

C
char-to-name: Emacs 30.1
char-uppercase-p: Emacs 29.1
cl-constantly: Emacs 29.1
cl-once-only: Emacs 29.1
cl-with-gensyms: Emacs 29.1
closurep: Emacs 30.1
color-dark-p: Emacs 28.1
color-values-from-color-spec: Emacs 28.1
compat-call: Usage
compat-call alist-get: Emacs 26.1
compat-call assoc: Emacs 26.1
compat-call assoc-delete-all: Emacs 27.1
compat-call completion-metadata-get: Emacs 30.1
compat-call copy-tree: Emacs 30.1
compat-call count-windows: Emacs 28.1
compat-call define-key: Emacs 29.1
compat-call executable-find: Emacs 27.1
compat-call file-size-human-readable: Emacs 27.1
compat-call line-number-at-pos: Emacs 26.1
compat-call lookup-key: Emacs 27.1
compat-call make-temp-file: Emacs 26.1
compat-call plist-get: Emacs 29.1
compat-call plist-member: Emacs 29.1
compat-call plist-put: Emacs 29.1
compat-call recenter: Emacs 27.1
compat-call regexp-opt: Emacs 27.1
compat-call set-transient-map: Emacs 29.1
compat-call setq-local: Emacs 27.1
compat-call sort: Emacs 30.1
compat-call string-lines: Emacs 29.1
compat-call string-trim: Emacs 26.1
compat-call string-trim-left: Emacs 26.1
compat-call string-trim-right: Emacs 26.1
compat-call string-width: Emacs 28.1
compat-function: Usage
compiled-function-p: Emacs 29.1
completion-lazy-hilit: Emacs 30.1
count-sentences: Emacs 29.1
cXXXr: Emacs 26.1
cXXXXr: Emacs 26.1

D
date-days-in-month: Emacs 27.1
date-ordinal-to-time: Emacs 27.1
decoded-time-day: Emacs 27.1
decoded-time-dst: Emacs 27.1
decoded-time-hour: Emacs 27.1
decoded-time-minute: Emacs 27.1
decoded-time-month: Emacs 27.1
decoded-time-period: Emacs 28.1
decoded-time-second: Emacs 27.1
decoded-time-weekday: Emacs 27.1
decoded-time-year: Emacs 27.1
decoded-time-zone: Emacs 27.1
define-keymap: Emacs 29.1
defvar-keymap: Emacs 29.1
delete-line: Emacs 29.1
directory-abbrev-apply: Emacs 29.1
directory-abbrev-make-regexp: Emacs 29.1
directory-empty-p: Emacs 28.1
directory-name-p: Emacs 25.1
dlet: Emacs 28.1
dolist-with-progress-reporter: Emacs 27.1
drop: Emacs 30.1

E
ensure-list: Emacs 28.1
ert-with-temp-directory: Emacs 29.1
ert-with-temp-file: Emacs 29.1

F
file-attribute-access-time: Emacs 26.1
file-attribute-collect: Emacs 26.1
file-attribute-device-number: Emacs 26.1
file-attribute-file-identifier: Emacs 29.1
file-attribute-group-id: Emacs 26.1
file-attribute-inode-number: Emacs 26.1
file-attribute-link-number: Emacs 26.1
file-attribute-modes: Emacs 26.1
file-attribute-modification-time: Emacs 26.1
file-attribute-size: Emacs 26.1
file-attribute-status-change-time: Emacs 26.1
file-attribute-type: Emacs 26.1
file-attribute-user-id: Emacs 26.1
file-backup-file-names: Emacs 28.1
file-has-changed-p: Emacs 29.1
file-local-name: Emacs 26.1
file-modes-number-to-symbolic: Emacs 28.1
file-name-concat: Emacs 28.1
file-name-parent-directory: Emacs 29.1
file-name-quote: Emacs 26.1
file-name-quoted-p: Emacs 26.1
file-name-split: Emacs 29.1
file-name-unquote: Emacs 26.1
file-name-with-extension: Emacs 28.1
file-size-human-readable-iec: Emacs 27.1
find-buffer: Emacs 30.1
fixnump: Emacs 27.1
flatten-tree: Emacs 27.1
format-message: Emacs 25.1
format-prompt: Emacs 28.1
funcall-with-delayed-message: Emacs 29.1
function-alias-p: Emacs 29.1

G
garbage-collect-maybe: Emacs 28.1
gensym: Emacs 26.1
get-display-property: Emacs 29.1
get-scratch-buffer-create: Emacs 29.1
get-truename-buffer: Emacs 30.1

H
hash-table-empty: Emacs 25.1

I
if-let: Emacs 25.1
if-let*: Emacs 26.1
ignore-errors: Emacs 27.1
image-property: Emacs 26.1
insert-into-buffer: Emacs 28.1
interpreted-function-p: Emacs 30.1

K
key-parse: Emacs 29.1
key-valid-p: Emacs 29.1
keymap-global-lookup: Emacs 29.1
keymap-global-set: Emacs 29.1
keymap-global-unset: Emacs 29.1
keymap-local-lookup: Emacs 29.1
keymap-local-set: Emacs 29.1
keymap-local-unset: Emacs 29.1
keymap-lookup: Emacs 29.1
keymap-set: Emacs 29.1
keymap-substitute: Emacs 29.1

L
length<: Emacs 28.1
length=: Emacs 28.1
length>: Emacs 28.1
list-of-strings-p: Emacs 29.1

M
macroexp-file-name: Emacs 28.1
macroexp-parse: Emacs 25.1
macroexp-quote: Emacs 25.1
macroexp-warn-and-return: Emacs 28.1
macroexpand-1: Emacs 25.1
major-mode-restore: Emacs 27.1
major-mode-suspend: Emacs 27.1
make-empty-file: Emacs 27.1
make-lock-file-name: Emacs 28.1
make-nearby-temp-file: Emacs 26.1
make-separator-line: Emacs 28.1
mapcan: Emacs 26.1
mark-thing-at-mouse: Emacs 28.1
match-buffers: Emacs 29.1
merge-ordered-lists: Emacs 30.1
minibuffer-history-value: Emacs 27.1

N
named-let: Emacs 28.1
native-comp-available-p: Emacs 28.1
ntake: Emacs 29.1

O
obarray-clear: Emacs 30.1

P
package-get-version: Emacs 27.1
plistp: Emacs 29.1
pos-bol: Emacs 29.1
pos-eol: Emacs 29.1
primitive-function-p: Emacs 30.1
process-lines-handling-status: Emacs 28.1
process-lines-ignore-status: Emacs 28.1
proper-list-p: Emacs 27.1
provided-mode-derived-p: Emacs 27.1

R
read-answer: Emacs 26.1
read-char-from-minibuffer: Emacs 27.1
read-multiple-choice: Emacs 26.1
readablep: Emacs 29.1
region-bounds: Emacs 25.1
region-noncontiguous-p: Emacs 25.1
replace-regexp-in-string: Emacs 28.1
replace-string-in-region: Emacs 28.1
require-with-check: Emacs 30.1
ring-resize: Emacs 27.1

S
save-mark-and-excursion: Emacs 25.1
static-if: Emacs 30.1
string-chop-newline: Emacs 28.1
string-clean-whitespace: Emacs 28.1
string-distance: Emacs 27.1
string-equal-ignore-case: Emacs 29.1
string-fill: Emacs 28.1
string-glyph-split: Emacs 29.1
string-greaterp: Emacs 25.1
string-lines: Emacs 28.1
string-pad: Emacs 28.1
string-replace: Emacs 28.1
string-search: Emacs 28.1
string-split: Emacs 29.1
subr-primitive-p: Emacs 28.1
substitute-quotes: Emacs 29.1

T
take: Emacs 29.1
temporary-file-directory: Emacs 26.1
text-property-search-backward: Emacs 27.1
text-property-search-forward: Emacs 27.1
text-quoting-style: Emacs 28.1
thing-at-mouse: Emacs 28.1
thread-first: Emacs 25.1
thread-last: Emacs 25.1
time-equal-p: Emacs 27.1

U
use-region-beginning: Emacs 29.1
use-region-end: Emacs 29.1
use-region-noncontiguous-p: Emacs 29.1

V
value<: Emacs 30.1

W
when-let: Emacs 25.1
when-let*: Emacs 26.1
while-let: Emacs 29.1
window-configuration-equal-p: Emacs 29.1
with-buffer-unmodified-if-unchanged: Emacs 29.1
with-delayed-message: Emacs 29.1
with-environment-variables: Emacs 28.1
with-existing-directory: Emacs 28.1
with-file-modes: Emacs 25.1
with-memoization: Emacs 29.1
with-minibuffer-selected-window: Emacs 27.1
with-restriction: Emacs 29.1
with-suppressed-warnings: Emacs 27.1
with-window-non-dedicated: Emacs 28.1
without-restriction: Emacs 29.1

X
xor: Emacs 27.1

Jump to:   A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   R   S   T   U   V   W   X  

Appendix B Variable Index

Jump to:   C   E   G   L   M   R   S   T  
Index Entry  Section

C
completion-lazy-hilit: Emacs 30.1
completion-lazy-hilit-fn: Emacs 30.1

E
exec-path: Emacs 27.1

G
gensym-counter: Emacs 26.1

L
lisp-directory: Emacs 29.1

M
mounted-file-systems: Emacs 26.1

R
regexp-unmatchable: Emacs 27.1

S
set-transient-map-timeout: Emacs 29.1

T
text-quoting-style: Emacs 25.1

Jump to:   C   E   G   L   M   R   S   T