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:

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

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

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

emacs-lisp
(substitute-in-file-name (compat-call file-name-quote "bar/~/foo")) ⇒
     "/:bar/~/foo"
emacs-lisp
(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.

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

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

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

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