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:

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

emacs-lisp
(proper-list-p '(a b c)) ⇒ 3
emacs-lisp
(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:

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

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

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

Function: decoded-time-minute time ​

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

Function: decoded-time-hour time ​

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

Function: decoded-time-day time ​

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

Function: decoded-time-month time ​

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

Function: decoded-time-year time ​

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

Function: decoded-time-weekday time ​

Return the weekday field of a decoded-time record time. It can also be used as a 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 Generalized Variables.

Function: decoded-time-zone time ​

Return the zone field of a decoded-time record time. It can also be used as a 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 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:

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

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

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

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

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