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.

emacs-lisp
(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 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.

Function: replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start ​

This function copies string and searches it for matches for regexp, and replaces them with rep. It returns the modified copy. If start is non-nil, the search for matches starts at that index in string, and the returned value does not include the first start characters of string. To get the whole transformed string, concatenate the first start characters of string with the return value.

This function uses replace-match to do the replacement, and it passes the optional arguments fixedcase, literal and subexp along to replace-match.

Instead of a string, rep can be a function. In that case, replace-regexp-in-string calls rep for each match, passing the text of the match as its sole argument. It collects the value rep returns and passes that to replace-match as the replacement string. The match data at this point are the result of matching regexp against a substring of string.

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:

emacs-lisp
(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:

emacs-lisp
(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 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:

emacs-lisp
(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.

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

See 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 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: