Emacs 30.1

• Added Definitions
• Extended Definitions
• Missing Definitions

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.

Variable: trusted-content

List of files and directories whose content we trust. Be extra careful here since trusting means that Emacs might execute the code contained within those files and directories without an explicit request by the user. One important case when this might happen is when flymake-mode is enabled (for example, when it is added to a mode hook). Each element of the list should be a string: - If it ends in "/", it is considered as a directory name and means that Emacs should trust all the files whose name has this directory as a prefix. - else it is considered as a file name. Use abbreviated file names. For example, an entry "~/mycode" means that Emacs will trust all the files in your directory "mycode". This variable can also be set to :all, in which case Emacs will trust all files, which opens a gaping security hole.

Function: trusted-content-p

Return non-nil if we trust the contents of the current buffer. Here, "trust" means that we are willing to run code found inside of it. See also trusted-content.

Function: color-oklab-to-xyz l a b

Convert the OkLab color represented by l a b to CIE XYZ. Oklab is a perceptual color space created by Björn Ottosson <https://bottosson.github.io/posts/oklab/>. It has the property that changes in the hue and saturation of a color can be made while maintaining the same perceived lightness.

Function: color-xyz-to-oklab x y z

Convert the CIE XYZ color represented by x y z to Oklab.

Function: color-oklab-to-srgb l a b

Convert the Oklab color represented by l a b to sRGB.

Function: color-srgb-to-oklab r g b

Convert the sRGB color r g b to Oklab.

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: