path: root/compat.texi

\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename compat.info
@settitle "Compat" Manual
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@copying
Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.

@quotation
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.”

@end quotation
@end copying

@dircategory Emacs
@direntry
* Compat: (compat).     Compatibility Library for Emacs Lisp.
@end direntry

@finalout
@titlepage
@title "Compat" Manual
@subtitle For version 29.1.3.0
@author Philip Kaludercic, Daniel Mendler
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top "Compat" Manual

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

@insertcopying
@end ifnottex

@menu
* Introduction::
* Support::
* Development::
* Function Index::
* Variable Index::

@detailmenu
--- The Detailed Node Listing ---

Introduction

* Overview::
* Usage::
* Intentions::

Support

* Emacs 25.1::                   Compatibility support for Emacs 25.1
* Emacs 26.1::                   Compatibility support for Emacs 26.1
* Emacs 27.1::                   Compatibility support for Emacs 27.1
* Emacs 28.1::                   Compatibility support for Emacs 28.1
* Emacs 29.1::                   Compatibility support for Emacs 29.1

@end detailmenu
@end menu

@node Introduction
@chapter Introduction

@menu
* Overview::
* Usage::
* Intentions::
@end menu

@node Overview
@section Overview

The objective of Compat is to provide "forwards compatibility" library
for Emacs Lisp.  That is to say 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.

Version 24.4 is chosen as the oldest version we can support, since
Elisp has seen significant changes at that version.  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.

@node Usage
@section Usage

The intended use-case for this library is for package developers to
add as a dependency in the header:

@example
;; Package-Requires: ((emacs "24.4") (compat "29.1.3.0"))
@end example

There is no need to depend on @code{emacs} 24.4 specifically.  One can
choose to 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

@example
(require 'compat)
@end example

should be added early on. In packages which are part of Emacs itself,
the noerror flag should be specified.

@example
(require 'compat nil 'noerror)
@end example

This will load all necessary Compat definitions.  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.

Note that Compat provides replacement functions with extended
functionality for functions that are already defined (@code{sort},
@code{assoc}, @dots{}).  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
@code{compat-function} or called explicitly with @code{compat-call}.
We call them ``Extended Definitions''.  In contrast, newly ``Added
Definitions'' can be called as usual.

@example
(compat-call assoc key alist testfn) ;; Call extended `assoc'
(mapcan fun seq)                     ;; Call newly added `mapcan'
@end example

@defmac compat-call fun &rest args
This macro calls the compatibility function @var{fun} with @var{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
@code{compat-call}.  This happens for example when the calling
convention of a function has changed.
@end defmac

@defmac compat-function fun
This macro returns the compatibility function symbol for @var{fun}.
See @code{compat-call} for a more convenient macro to directly call
compatibility functions.
@end defmac

This design has been chosen 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
@file{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
@uref{https://lists.sr.ht/~pkal/compat-announce, compat-announce}
mailing list to be notified when new versions are released or relevant
changes are made.  We also provide a
@uref{https://lists.sr.ht/~pkal/compat-devel, development mailing
list} (@email{~pkal/compat-devel@@lists.sr.ht,
~pkal/compat-devel@@lists.sr.ht}).

@node Intentions
@section Intentions

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

Complete backwards compatibility cannot be provided due to the scope
of Compat and for technical reasons.  These might include:

@itemize
@item
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.

@item
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 @code{compat-function}
and @code{compat-call} macros.

@item
New functionality was implemented in the C core, and depends on
external libraries that cannot be reasonably duplicated in the scope
of a compatibility library.

@item
New functionality depends on an entire new, non-trivial library.
Sometimes these are provided via ELPA (xref, project, @dots{}), but
other times it would be infeasible to duplicate an entire library
within Compat while also providing the necessary backwards
compatibility.

@item
The semantics of Elisp changed on a deep level. For example the
addition of Bigint support in Emacs 27.1 cannot be replicated on the
level of Compat.

@item
Backported functions would introduce performance bugs. Sometimes
functions provided by newer Emacs versions are implemented on the C
level, relying on internal data structures, which we cannot access. In
this case a backport may still be possible but would be significantly
slower than the newer functionality, such that downstream packages
would observe performance bugs. Examples are the
@code{string-pixel-width} function and the @code{json-parse-string}
function provided by libjansson.

@item
It just was not added without a good reason.  If you happen to find
such a function, @ref{Development, , reporting} it would be much
appreciated. Always begin by assuming that this might be the case,
unless proven otherwise.
@end itemize

@node Support
@chapter Support

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

@menu
* Emacs 25.1::                   Compatibility support for Emacs 25.1
* Emacs 26.1::                   Compatibility support for Emacs 26.1
* Emacs 27.1::                   Compatibility support for Emacs 27.1
* Emacs 28.1::                   Compatibility support for Emacs 28.1
* Emacs 29.1::                   Compatibility support for Emacs 29.1
@end menu

@node Emacs 25.1
@section Emacs 25.1

@subsection 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.

@c copied from lispref/help.texi
@defopt 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 @code{curve}, the style is
@t{‘like this’} with curved single quotes.  If the value is
@code{straight}, the style is @t{'like this'} with straight
apostrophes.  If the value is @code{grave}, quotes are not translated
and the style is @t{`like this'} with grave accent and apostrophe, the
standard style before Emacs version 25.  The default value @code{nil}
acts like @code{curve} if curved single quotes seem to be displayable,
and like @code{grave} otherwise.

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

@c based on lisp/simple.el
@defun region-bounds
Return the boundaries of the region.  Value is a list of one or more
cons cells of the form @code{(start . end)}.  It will have more than
one cons cell when the region is non-contiguous, see
@code{region-noncontiguous-p} and @code{extract-rectangle-bounds}.
@end defun

@c based on lisp/simple.el
@defun 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.
@end defun

@c copied from lispref/positions.texi
@defmac save-mark-and-excursion body@dots{}
This macro is like @code{save-excursion}, but also saves and restores
the mark location and @code{mark-active}.  This macro does what
@code{save-excursion} did before Emacs 25.1.
@end defmac

@c copied from lispref/strings.texi
@defun format-message string &rest objects
This function acts like @code{format}, except it also converts any grave
accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the value
of @code{text-quoting-style}.

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

@ref{Formatting Strings,,,elisp}.
@end defun

@c copied from lispref/files.texi
@defun directory-name-p filename
This function returns non-@code{nil} if @var{filename} ends with a
directory separator character.  This is the forward slash @samp{/} on
GNU and other POSIX-like systems; MS-Windows and MS-DOS recognize both
the forward slash and the backslash @samp{\} as directory separators.

@xref{Directory Names,,,elisp}.
@end defun

@c copied from lispref/strings.texi
@defun string-greaterp string1 string2
This function returns the result of comparing @var{string1} and
@var{string2} in the opposite order, i.e., it is equivalent to calling
@code{(string-lessp @var{string2} @var{string1})}.

@xref{Text Comparison,,,elisp}.
@end defun

@c copied from lispref/files.texi
@defmac with-file-modes mode body@dots{}
This macro evaluates the @var{body} forms with the default permissions
for new files temporarily set to @var{modes} (whose value is as for
@code{set-file-modes} above).  When finished, it restores the original
default file permissions, and returns the value of the last form in
@var{body}.

This is useful for creating private files, for example.

@xref{Changing Files,,,elisp}.
@end defmac

@c copied from lispref/lists.texi
@defun alist-get key alist &optional default remove
This function is similar to @code{assq}.  It finds the first association
@w{@code{(@var{key} . @var{value})}} by comparing @var{key} with
@var{alist} elements, and, if found, returns the @var{value} of that
association.  If no association is found, the function returns
@var{default}.

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

@ref{Association Lists,,,elisp}.
@end defun

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

A binding may also optionally drop the @var{symbol}, and simplify to
@code{(@var{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:

@example
@group
(if-let* (@var{symbol} (test)) foo bar)
@equiv{}
(if-let* ((@var{symbol} (test))) foo bar)
@end group
@end example
@end defmac

@defmac when-let (bindings@dots{}) &rest body
As with @code{when}, if one is only interested in the case where all
@var{bindings} are non-nil.  Otherwise @var{bindings} are interpreted
just as they are by @code{if-let*}.
@end defmac

@c based on lisp/subr-x.el
@defun hash-table-empty hash-table
Check whether @var{hash-table} is empty (has 0 elements).
@end defun

@c based on lisp/subr-x.el
@defmac thread-first &rest forms
Combine @var{forms} into a single expression by ``threading'' each
element as the @emph{first} argument of their successor.  Elements of
@var{forms} can either be an list of an atom.

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

@example
(thread-first
  5
  (+ 20)
  (/ 25)
  -
  (+ 40))
@equiv{}
(+ (- (/ (+ 5 20) 25)) 40)
@end example

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

@defmac thread-last &rest forms
Combine @var{forms} into a single expression by ``threading'' each
element as the @emph{last} argument of their successor.  Elements of
@var{forms} can either be an list of an atom.

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

@example
(thread-first
  5
  (+ 20)
  (/ 25)
  -
  (+ 40))
@equiv{}
(+ 40 (- (/ 25 (+ 20 5))))
@end example

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

@c copied from lispref/macros.texi
@defun macroexpand-1 form &optional environment
This function expands macros like @code{macroexpand}, but it only
performs one step of the expansion: if the result is another macro call,
@code{macroexpand-1} will not expand it.

@xref{Expansion,Expansion,,elisp}.
@end defun

@c based on lisp/emacs-lisp/macroexp.el
@defun macroexp-quote e
Return an expression @var{e} such that @code{(eval e)} is @var{v}.
@end defun

@c based on lisp/emacs-lisp/macroexp.el
@defun macroexp-parse body
Parse a function @var{body} into @code{(declarations . exps)}.
@end defun

@defun bool-vector &rest objects
This function creates and returns a bool-vector whose elements are the
arguments, @var{objects}.

@xref{Bool-Vectors,,,elisp}.
@end defun

@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
since their calling convention or behavior was extended in Emacs 25.1:

@defun compat-call@ sort sequence predicate
This function sorts @var{sequence} stably.  Note that this function
doesn't work for all sequences; it may be used only for lists and
vectors.  If @var{sequence} is a list, it is modified destructively.
This functions returns the sorted @var{sequence} and compares elements
using @var{predicate}.  A stable sort is one in which elements with
equal sort keys maintain their relative order before and after the sort.
Stability is important when successive sorts are used to order elements
according to different criteria.

@xref{Sequence Functions,,,elisp}.

The compatibility version adds support for vectors to be sorted, not
just lists.
@end defun

@subsection Missing Definitions
Compat does not provide support for the following Lisp features
implemented in 25.1:

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

@node Emacs 26.1
@section Emacs 26.1

@subsection 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.

@c based on lispref/lists.texi
@defun assoc-delete-all key alist
This function is like @code{assq-delete-all} except that it uses
@code{equal} to compare elements.
@end defun

@c copied from lispref/minibuf.texi
@defun read-answer question answers
This function prompts the user with text in @var{question}, which
should end in the @samp{SPC} character.  The function includes in the
prompt the possible responses in @var{answers} by appending them to
the end of @var{question}.  The possible responses are provided in
@var{answers} as an alist whose elements are of the following form:

@lisp
(@var{long-answer} @var{short-answer} @var{help-message})
@end lisp

@noindent
where @var{long-answer} is the complete text of the user response, a
string; @var{short-answer} is a short form of the same response, a
single character or a function key; and @var{help-message} is the text
that describes the meaning of the answer.  If the variable
@code{read-answer-short} is non-@code{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 @key{RET}.  If @code{use-dialog-box} is non-@code{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 @var{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:

@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"))))
@end lisp
@end defun

@c copied from lispref/functions.texi
@defun mapcan function sequence
This function applies @var{function} to each element of @var{sequence},
like @code{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 @code{nconc};
@pxref{Rearrangement,,,elisp}).  Like with @code{mapcar}, @var{sequence}
can be of any type except a char-table.

@example
@group
;; @r{Contrast this:} (mapcar #'list '(a b c d)) @result{} ((a) (b) (c)
(d)) ;; @r{with this:} (mapcan #'list '(a b c d)) @result{} (a b c d)
@end group
@end example

@xref{Mapping Functions,,,elisp}.
@end defun

@defun cXXXr
@end defun
@defun cXXXXr
@xref{List Elements,,,elisp}.
@end defun

@c copied from lispref/symbols.texi
@defun gensym &optional prefix
This function returns a symbol using @code{make-symbol}, whose name is
made by appending @code{gensym-counter} to @var{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
@code{"g"}.
@end defun

@defvar gensym-counter
See @code{gensym}.
@end defvar

@c copied from lispref/text.texi
@defun buffer-hash &optional buffer-or-name
Return a hash of @var{buffer-or-name}.  If @code{nil}, this defaults
to the current buffer.  As opposed to @code{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
@code{secure-hash} is, and should not allocate more memory.
@c Note that we do not document what hashing function we're using, or
@c even whether it's a cryptographic hash, since that may change
@c according to what we find useful.
@end defun

@c copied from lispref/files.texi
@defmac file-name-unquote name
This macro removes the quotation prefix @samp{/:} from the file
@var{name}, if any. If @var{name} is a remote file name, the local
part of @var{name} is unquoted.
@end defmac

@c copied from lispref/files.texi
@defun file-name-quoted-p name
This macro returns non-@code{nil}, when @var{name} is quoted with the
prefix @samp{/:}.  If @var{name} is a remote file name, the local part
of @var{name} is checked.

@xref{File Name Expansion,,,elisp}.
@end defun

@c copied from lispref/files.texi
@defun file-name-quote name
This macro adds the quotation prefix @samp{/:} to the file @var{name}.
For a local file @var{name}, it prefixes @var{name} with @samp{/:}.  If
@var{name} is a remote file name, the local part of @var{name}
(@pxref{Magic File Names,,,elisp}) is quoted.  If @var{name} is already
a quoted file name, @var{name} is returned unchanged.

@example
@group
(substitute-in-file-name (compat-call file-name-quote "bar/~/foo")) @result{}
     "/:bar/~/foo"
@end group

@group
(substitute-in-file-name (compat-call file-name-quote "/ssh:host:bar/~/foo"))
     @result{} "/ssh:host:/:bar/~/foo"
@end group
@end example

The macro cannot be used to suppress file name handlers from magic file
names (@pxref{Magic File Names,,,elisp}).

@xref{File Name Expansion,,,elisp}.
@end defun

@c copied from lispref/files.texi
@defun make-nearby-temp-file prefix &optional dir-flag suffix
This function is similar to @code{make-temp-file}, but it creates a
temporary file as close as possible to @code{default-directory}.  If
@var{prefix} is a relative file name, and @code{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
@code{temporary-file-directory}.  Otherwise, the function
@code{make-temp-file} is used.  @var{prefix}, @var{dir-flag} and
@var{suffix} have the same meaning as in @code{make-temp-file}.

@example
@group
(let ((default-directory "/ssh:remotehost:")) (make-nearby-temp-file
  "foo")) @result{} "/ssh:remotehost:/tmp/foo232J6v"
@end group
@end example
@end defun

@c based on lisp/files.el
@defvar mounted-file-systems
A regular expression matching files names that are probably on a mounted
file system.
@end defvar

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

@xref{Unique File Names,,,elisp}.
@end defun

@defmac if-let* (bindings@dots{}) then &rest else
@code{if-let*} is mostly equivalent to @code{if-let}, with the
exception that the legacy @code{(if (@var{var} (test)) foo bar)}
syntax is not permitted.
@end defmac

@defmac when-let* (bindings@dots{}) then &rest else
@code{when-let*} is mostly equivalent to @code{when-let}, with the
exception that the legacy @code{(when-let (@var{var} (test)) foo bar)}
syntax is not permitted.
@end defmac

@defmac and-let* (bindings@dots{}) &rest body
A combination of @var{let*} and @var{and}, analogous to
@code{when-let*}.  If all @var{bindings} are non-@code{nil} and
@var{body} is @code{nil}, then the result of the @code{and-let*} form
will be the last value bound in @var{bindings}.

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

@c copied from lispref/files.texi
@defun file-local-name filename
This function returns the @emph{local part} of @var{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:

@smallexample
(file-local-name "/ssh:@var{user}@@@var{host}:/foo/bar") @result{}
     "/foo/bar"
@end smallexample

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

@xref{Magic File Names,,,elisp}.
@end defun

@defun read-multiple-choice prompt choices
Ask user a multiple choice question.  @var{prompt} should be a string
that will be displayed as the prompt.

@var{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 @ref{Reading One Event,Reading One Event,,elisp,}.
@end defun

@defun image-property
Defined in @code{image.el}.

This function can also be used as a generalised variable.
@end defun

@defun file-attribute-type
Return the field @emph{type} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-link-number
Return the field @emph{link-number} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-user-id
Return the field @emph{user-id} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-group-id
Return the field @emph{group-id} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-access-time
Return the field @emph{access-time} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-modification-time
Return the field @emph{modification-time} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-status-change-time
Return the field @emph{modification-time} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-size
Return the field @emph{size} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-modes
Return the field @emph{modes} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-inode-number
Return the field @emph{inode-number} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@defun file-attribute-device-number
Return the field @emph{device-number} as generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@c based on lisp/files.el
@defun file-attribute-collect attributes &rest attr-names
Filter the file attributes @var{attributes}, as generated by
@code{file-attributes}, according to @var{attr-names}.

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

@example
@group
(file-attributes ".") @result{} (t 1 1000 1000 (25329 18215 325481 96000) (25325 15364 530263 840000) (25325 15364 530263 840000) 788 "drwxr-xr-x" t 137819 40)
@end group
@group
(file-attribute-collect (file-attributes ".") 'type 'modes
'inode-number) @result{} (t "drwxr-xr-x" 137819)
@end group
@end example
@end defun

@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
since their calling convention or behavior was extended in Emacs 26.1:

@c copied from lispref/files.texi
@defun 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 @var{prefix} some
random characters that are different in each Emacs job.  The result is
guaranteed to be a newly created file, containing @var{text} if that's
given as a string and empty otherwise. On MS-DOS, this function can
truncate @var{prefix} to fit into the 8+3 file-name limits.  If
@var{prefix} is a relative file name, it is expanded against
@code{temporary-file-directory}.

The compatibility version adds support for handling the optional
argument @var{TEXT}.

@example
@group
(make-temp-file "foo")
     @result{} "/tmp/foo232J6v"
@end group
@end example

When @code{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 @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
empty directory instead of an empty file.  It returns the file name,
not the directory name, of that directory.  @xref{Directory Names,,,elisp}.

If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
the end of the file name.

If @var{text} is a string, @code{make-temp-file} inserts it in the file.

To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses @code{make-temp-file} should have its
own @var{prefix}.  The number added to the end of @var{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.
@end defun

@defun compat-call@ assoc key alist &optional testfn
This function returns the first association for @var{key} in
@var{alist}, comparing @var{key} against the alist elements using
@var{testfn} if it is a function, and @code{equal} otherwise
(@pxref{Equality Predicates,,,elisp}).  If @var{testfn} is a function,
it is called with two arguments: the @sc{car} of an element from
@var{alist} and @var{key}.  The function returns @code{nil} if no
association in @var{alist} has a @sc{car} equal to @var{key}, as tested
by @var{testfn}.

@xref{Association Lists,,,elisp}.

The compatibility version adds support for handling the optional
argument @var{testfn}.
@end defun

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

@xref{Text Lines,,,elisp}.

The compatibility version adds support for handling the optional
argument @var{absolute}.
@end defun

@defun compat-call@ alist-get key alist &optional default remove testfn
@xref{Association Lists,,,elisp}.  This function is similar to
@code{assq}.  It finds the first association @w{@code{(@var{key}
. @var{value})}} by comparing @var{key} with @var{alist} elements, and,
if found, returns the @var{value} of that association.  If no
association is found, the function returns @var{default}.  Comparison of
@var{key} against @var{alist} elements uses the function specified by
@var{testfn}, defaulting to @code{eq}.

@xref{Association Lists,,,elisp,}.

The compatibility version handles the optional argument @var{testfn}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun compat-call@ string-trim-left string &optional regexp
Remove the leading text that matches @var{regexp} from @var{string}.
@var{regexp} defaults to @samp{[ \t\n\r]+}.

@xref{Creating Strings,,,elisp}.

The compatibility version handles the optional argument @var{regexp}.
@end defun

@defun compat-call@ string-trim-right string &optional regexp
Remove the trailing text that matches @var{regexp} from @var{string}.
@var{regexp} defaults to @samp{[ \t\n\r]+}.

@xref{Creating Strings,,,elisp}.

The compatibility version handles the optional argument @var{regexp}.
@end defun

@defun compat-call@ string-trim string &optional trim-left trim-right
Remove the leading text that matches @var{trim-left} and trailing text
that matches @var{trim-right} from @var{string}.  Both regexps default
to @samp{[ \t\n\r]+}.

@xref{Creating Strings,,,elisp}.

The compatibility version handles the optional arguments @var{trim-left}
and @var{trim-right}.
@end defun

@subsection Missing Definitions
Compat does not provide support for the following Lisp features
implemented in 26.1:

@itemize
@item
The function @code{func-arity}.
@item
The function @code{secure-hash-algorithms}.
@item
The function @code{gnutls-available-p}.
@item
Support for records and record functions.
@item
The function @code{mapbacktrace}.
@item
The function @code{file-name-case-insensitive-p}.
@item
The additional elements of @code{parse-partial-sexp}.
@item
The function @code{add-variable-watcher}.
@item
The function @code{undo-amalgamate-change-group}.
@item
The function @code{char-from-name}
@item
Signalling errors when @code{length} or @code{member} deal with list
cycles.
@item
The function @code{frame-list-z-order}.
@item
The function @code{frame-restack}.
@item
All changes related to @code{display-buffer}.
@item
The function @code{window-swap-states}.
@item
The function @code{string-version-lessp}.
@end itemize

@node Emacs 27.1
@section Emacs 27.1

@subsection 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.

@c copied from lispref/modes.texi
@defun major-mode-suspend
This function works like @code{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
@code{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.
@end defun

@c copied from lispref/modes.texi
@defun major-mode-restore &optional avoided-modes
This function restores the major mode recorded by
@code{major-mode-suspend}.  If no major mode was recorded, this
function calls @code{normal-mode}, but tries to force it not to choose
any modes in @var{avoided-modes}, if that argument is non-@code{nil}.
@end defun

@c copied from lispref/sequences.texi
@defun ring-resize ring size
Set the size of @var{ring} to @var{size}.  If the new size is smaller,
then the oldest items in the ring are discarded.
@end defun

@c based on lisp/simple.el
@defun minibuffer-history-value
Return the value of the minibuffer input history list.  If
@var{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."
@end defun

@c based on lisp/minibuffer.el
@defmac with-minibuffer-selected-window &rest body
Execute the forms in @var{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.
@end defmac

@c copied from lispref/minbuf.texi
@defun 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
@var{chars}, a list of accepted characters.  The @var{history}
argument specifies the history list symbol to use; if it is omitted or
@code{nil}, this function doesn't use the history.

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

@c copied from lispref/numbers.texi
@defun bignump object
This predicate tests whether its argument is a large integer, and
returns @code{t} if so, @code{nil} otherwise.  Unlike small integers,
large integers can be @code{=} or @code{eql} even if they are not @code{eq}.
@end defun

@c copied from lispref/numbers.texi
@defun fixnump object
This predicate tests whether its argument is a small integer, and
returns @code{t} if so, @code{nil} otherwise.  Small integers can be
compared with @code{eq}.
@end defun

@c copied from lispref/lists.texi
@defun proper-list-p object
This function returns the length of @var{object} if it is a proper list,
@code{nil} otherwise (@pxref{Cons Cells,,,elisp}).  In addition to
satisfying @code{listp}, a proper list is neither circular nor dotted.

@example
@group
(proper-list-p '(a b c)) @result{} 3
@end group
@group
(proper-list-p '(a b . c)) @result{} nil
@end group
@end example

@xref{List-related Predicates,,,elisp}.
@end defun

@c copied from lispref/strings.texi
@defun string-distance string1 string2 &optional bytecompare
This function returns the @emph{Levenshtein distance} between the source
string @var{string1} and the target string @var{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 @emph{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
@var{bytecompare} is non-@code{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 (@pxref{Text Representations,,,elisp}); make the strings unibyte
by encoding them (@pxref{Explicit Encoding,,,elisp}) if you need
accurate results with raw bytes.

@xref{Text Comparison,,,elisp}.
@end defun

@c copied from lispref/control.texi
@defmac ignore-errors body@dots{}
This construct executes @var{body}, ignoring any errors that occur
during its execution.  If the execution is without error,
@code{ignore-errors} returns the value of the last form in @var{body};
otherwise, it returns @code{nil}.

Here's the example at the beginning of this subsection rewritten using
@code{ignore-errors}:

@example
@group
  (ignore-errors (delete-file filename))
@end group
@end example

@xref{Handling Errors,,,elisp}.
@end defmac

@c copied from lispref/display.texi
@defmac dolist-with-progress-reporter (var count [result]) reporter-or-message body@dots{}
This is another convenience macro that works the same way as
@code{dolist} does, but also reports loop progress using the functions
described above.  As in @code{dotimes-with-progress-reporter},
@code{reporter-or-message} can be a progress reporter or a string.  You
can rewrite the previous example with this macro as follows:

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

@xref{Progress,,,elisp}.
@end defmac

@c copied from lispref/lists.texi
@defun flatten-tree tree
This function returns a ``flattened'' copy of @var{tree}, that is, a
list containing all the non-@code{nil} terminal nodes, or leaves, of the
tree of cons cells rooted at @var{tree}.  Leaves in the returned list
are in the same order as in @var{tree}.

@example
(flatten-tree '(1 (2 . 3) nil (4 5 (6)) 7)) @result{}(1 2 3 4 5 6 7)
@end example

@xref{Building Lists,,,elisp}.
@end defun

@c copied from lispref/control.texi
@defun xor condition1 condition2
This function returns the boolean exclusive-or of @var{condition1} and
@var{condition2}.  That is, @code{xor} returns @code{nil} if either both
arguments are @code{nil}, or both are non-@code{nil}.  Otherwise, it
returns the value of that argument which is non-@code{nil}.

Note that in contrast to @code{or}, both arguments are always evaluated.

@xref{Combining Conditions,,,elisp}.
@end defun

@defvar 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.

@xref{Regexp Functions,,,elisp}
@end defvar

@defun decoded-time-second time
Return the @var{seconds} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun decoded-time-minute time
Return the @var{minute} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun decoded-time-hour time
Return the @var{hour} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun decoded-time-day time
Return the @var{day} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun decoded-time-month time
Return the @var{month} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun decoded-time-year time
Return the @var{year} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun decoded-time-weekday time
Return the @var{weekday} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@defun decoded-time-dst time
Return the @var{dst} (daylight saving time indicator) field of a
@code{decoded-time} record @var{time}. It can also be used as a
@ref{generalised variable,Generalized Variables,,elisp}.
@end defun

@defun decoded-time-zone time
Return the @var{zone} field of a @code{decoded-time} record @var{time}.
It can also be used as a @ref{generalised variable,Generalized
Variables,,elisp}.
@end defun

@c copied from lisp/emacs-lisp/package.el
@defun package-get-version
Return the version number of the package in which this is used.
@end defun

@c copied from lispref/os.texi
@defun time-equal-p t1 t2
This returns @code{t} if the two time values @var{t1} and @var{t2} are
equal.

@xref{Time Calculations,,,elisp}.
@end defun

@defun date-days-in-month year month
Return the number of days in @var{month} in @var{year}.  For instance,
February 2020 has 29 days.

@xref{Time Calculations,,,elisp}.  This function requires the
@code{time-date} feature to be loaded.
@end defun

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

@xref{Time Calculations,,,elisp}.  This function requires the
@code{time-date} feature to be loaded.
@end defun

@defopt 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 @code{nil}, which stands for the default
directory (which is the value of @code{default-directory}).
@xref{Locating Files, executable-find,,elisp}, for the details of this
search.
@cindex program directories

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

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

@xref{Subprocess Creation,,,elisp}.
@end defopt

@c based on lisp/modes.el
@defun provided-mode-derived-p mode &rest modes
This function returns non-@code{nil} if @var{mode} is derived from any
of the major modes given by the symbols @var{modes}.
@end defun

@c based on lisp/files.texi
@defun file-size-human-readable-iec size
Human-readable string for @var{size} bytes, using IEC prefixes.
@end defun

@c based on lispref/files.texi
@defun make-empty-file filename &optional parents
This function creates an empty file named @var{filename}.  As
@code{make-directory}, this function creates parent directories if
@var{parents} is non-@code{nil}.  If @var{filename} already exists, this
function signals an error.
@end defun

@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
since their calling convention or behavior was extended in Emacs 27.1:

@c based on lispref/windows.texi
@defun 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.

@xref{Textual Scrolling,,,elisp}.

This compatibility version adds support for the optional argument
@var{redisplay}.
@end defun

@c based on lispref/keymaps.texi
@defun compat-call@ lookup-key keymap key &optional accept-defaults
This function returns the definition of @var{key} in @var{keymap}.  If
the string or vector @var{key} is not a valid key sequence according
to the prefix keys specified in @var{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 @var{key} that compose a complete key.

@xref{Low-Level Key Binding,,,elisp}.

This compatibility version allows for @var{keymap} to be a list of
keymaps, instead of just a singular keymap.
@end defun

@c based on lispref/variables.texi
@defmac compat-call@ setq-local &rest pairs
@var{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 @code{make-local-variable} followed by @code{setq} for each of
the variables.  The variables should be unquoted symbols.

@lisp
(setq-local var1 "value1"
            var2 "value2")
@end lisp

@xref{Creating Buffer-Local,,,elisp}.

This compatibility version allows for more than one variable to be set
at once, as can be done with @code{setq}.
@end defmac

@c based on lispref/searching.texi
@defun compat-call@ regexp-opt strings &optional paren
This function returns an efficient regular expression that will match
any of the strings in the list @var{strings}.  This is useful when you
need to make matching or searching as fast as possible---for example,
for Font Lock mode.

@xref{Regexp Functions,,,elisp}.

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

@c based on lisp/files.texi
@defun compat-call@ file-size-human-readable file-size &optional flavor space unit
Return a string with a human readable representation of @var{file-size}.

The optional second argument @var{flavor} controls the units and the
display format.  If @var{flavor} is@dots{}

@itemize
@item
@code{si}, each kilobyte is 1000 bytes and the produced suffixes are
@code{k}, @code{M}, @code{G}, @code{T}, etc.
@item
@code{iec}, each kilobyte is 1024 bytes and the produced suffixes are
@code{KiB}, @code{MiB}, @code{GiB}, @code{TiB}, etc.
@item
@code{nil} or omitted, each kilobyte is 1024 bytes and the produced
suffixes are @code{k}, @code{M}, @code{G}, @code{T}, etc.
@end itemize

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

@c copied from lispref/lists.texi
@defun compat-call@ assoc-delete-all key alist &optional test
This function is like @code{assq-delete-all} except that it accepts
an optional argument @var{test}, a predicate function to compare the
keys in @var{alist}.  If omitted or @code{nil}, @var{test} defaults to
@code{equal}.  As @code{assq-delete-all}, this function often modifies
the original list structure of @var{alist}.

@xref{Association Lists,,,elisp}.

This compatibility version handles the optional third (@var{testfn})
argument.
@end defun

@c copied from lispref/files.texi
@defun compat-call@ executable-find program &optional remote
This function searches for the executable file of the named
@var{program} and returns the absolute file name of the executable,
including its file-name extensions, if any.  It returns @code{nil} if
the file is not found.  The function searches in all the directories in
@code{exec-path}, and tries all the file-name extensions in
@code{exec-suffixes} (@pxref{Subprocess Creation,,,elisp}).

If @var{remote} is non-@code{nil}, and @code{default-directory} is a
remote directory, @var{program} is searched on the respective remote host.

@xref{Locating Files,,,elisp}.

This compatibility version adds support to handle the optional second
(@var{remote}) argument.
@end defun

@defun compat-call@ dired-get-marked-files &optional localp arg filter distinguish-one-marked error
Return a list of file names that are @emph{marked} in a Dired buffer.

This compatibility version handles the optional fifth (@var{error})
argument, which signals an error if the list of found files is empty.
@code{error} can be a string with the error message.
@end defun

@defun text-property-search-forward prop &optional value predicate not-current
Search for the next region that has text property @var{prop} set to
@var{value} according to @var{predicate}.

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

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

@var{predicate} can either be @code{t} (which is a synonym for
@code{equal}), @code{nil} (which means ``not equal''), or a predicate
that will be called with two parameters: The first is @var{value}, and
the second is the value of the text property we're inspecting.

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

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

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

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

That is, the ``bold'' words are the @code{bold} face, and the
``italic'' word is in the @code{italic} face.

With point at the start:

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

This will pick out all the words that use the @code{bold} face.

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

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

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

This will pick out all the regions where @code{face} is set to
something, but this is split up into where the properties change, so
the result here will be @samp{("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 @code{shr-url}.

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

This will give you a list of all those URLs.

@xref{elisp,,,Property Search}.
@end defun

@defun text-property-search-backward prop &optional value predicate not-current
This is just like @code{text-property-search-forward}, but searches
backward instead.  Point is placed at the beginning of the matched
region instead of the end, though.

@xref{elisp,,,Property Search}.
@end defun

@subsection Missing Definitions
Compat does not provide support for the following Lisp features
implemented in 27.1:

@itemize
@item
The functions @code{base64url-encode-*}.
@item
The function @code{decoded-time-add}.
@item
The function @code{decoded-time-set-defaults}.
@item
The function @code{time-convert}.
@item
All @code{iso8601-*} functions.
@item
The macro @code{benchmark-progn}.
@item
The macro @code{with-suppressed-warnings}.
@item
Support for @code{condition-case} to handle t.
@item
The function @code{file-system-info}.
@item
The function @code{group-name}.
@item
Additional @code{format-spec} modifiers.
@item
Support for additional body forms for
@code{define-globalized-minor-mode}.
@item
The macro @code{with-connection-local-variables} and related
functionality.
@end itemize

@node Emacs 28.1
@section Emacs 28.1

@subsection 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.

@c copied from lispref/help.texi
@defun text-quoting-style
You should not read the value of the variable
@code{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 @code{nil} case described above.
@end defun

@c copied from lispref/strings.texi
@defun string-search needle haystack &optional start-pos
Return the position of the first instance of @var{needle} in
@var{haystack}, both of which are strings.  If @var{start-pos} is
non-@code{nil}, start searching from that position in @var{needle}.
Return @code{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.
@end defun

@c copied from lispref/sequences.texi
@defun length= sequence length
Return non-@code{nil} if the length of @var{sequence} is equal to
@var{length}.
@end defun

@c copied from lispref/sequences.texi
@defun length< sequence length
Return non-@code{nil} if @var{sequence} is shorter than @var{length}.
This may be more efficient than computing the length of @var{sequence}
if @var{sequence} is a long list.
@end defun

@c copied from lispref/sequences.texi
@defun length> sequence length
Return non-@code{nil} if @var{sequence} is longer than @var{length}.
@end defun

@c copied from lispref/files.texi
@defun file-name-concat directory &rest components
Concatenate @var{components} to @var{directory}, inserting a slash
before the components if @var{directory} or the preceding component
didn't end with a slash.

@example
@group
(file-name-concat "/tmp" "foo") @result{} "/tmp/foo"
@end group
@end example

A @var{directory} or components that are @code{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 @code{concat}, but @var{dirname} (and
the non-final components) may or may not end with slash characters, and
this function will not double those characters.
@end defun

@c based on src/alloc.c
@defun garbage-collect-maybe factor
Suggest to run garbage collection, if @emph{enough} data has been
allocated.  This is determined by the positive numerical argument
@var{factor}, that would proportionally increase the likelihood of
garbage collection taking place.

This compatibility function does nothing and ignores any suggestion.
@end defun

@c copied from lispref/searching.texi
@defun string-replace from-string to-string in-string
This function replaces all occurrences of @var{from-string} with
@var{to-string} in @var{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.
@end defun

@c copied from lispef/functions.texi
@defun always &rest arguments
This function ignores any @var{arguments} and returns @code{t}.

@xref{Calling Functions,,,elisp}.
@end defun

@defun make-separator-line &optional length
Make a string appropriate for usage as a visual separator line.
If @var{length} is nil, use the window width.
@end defun

@c copied from lispref/text.texi
@defun insert-into-buffer to-buffer &optional start end
This is like @code{insert-buffer-substring}, but works in the opposite
direction: The text is copied from the current buffer into
@var{to-buffer}.  The block of text is copied to the current point in
@var{to-buffer}, and point (in that buffer) is advanced to after the
end of the copied text.  Is @code{start}/@code{end} is @code{nil}, the
entire text in the current buffer is copied over.

@xref{Insertion,,,elisp}.
@end defun

@c copied from lispref/searching.texi
@defun replace-string-in-region regexp replacement &optional start end
This function replaces all the occurrences of @var{regexp} with
@var{replacement} in the region of buffer text between @var{start} and
@var{end}; @var{start} defaults to position of point, and @var{end}
defaults to the last accessible position of the buffer.  The search
for @var{regexp} is case-sensitive, and @var{replacement} is inserted
without changing its letter-case.  The @var{replacement} string can
use the same special elements starting with @samp{\} as
@code{replace-match} does.  The function returns the number of
replaced occurrences, or @code{nil} if @var{regexp} is not found.  The
function preserves the position of point.

@example
(replace-regexp-in-region "foo[ \t]+bar" "foobar")
@end example
@xref{Search and Replace,,,elisp}.
@end defun

@c copied from lispref/searching.texi
@defun replace-regexp-in-string string replacement &optional start end
  This function works similarly to @code{replace-regexp-in-region},
but searches for, and replaces, literal @var{string}s instead of
regular expressions.

@xref{Search and Replace,,,elisp}.
@end defun

@c copied from lispref/variables
@defun buffer-local-boundp variable buffer
This returns non-@code{nil} if there's either a buffer-local binding
of @var{variable} (a symbol) in buffer @var{buffer}, or @var{variable}
has a global binding.

@xref{Creating Buffer-Local,,,elisp}.
@end defun

@c copied from lispref/files.texi
@defmac with-existing-directory body@dots{}
This macro ensures that @code{default-directory} is bound to an
existing directory before executing @var{body}.  If
@code{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.

@xref{Testing Accessibility,,,elisp}.
@end defmac

@c copied from lispref/variables.texi
@defmac dlet (bindings@dots{}) forms@dots{}
This special form is like @code{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 @code{defvar}) dynamically, and this is what @code{let}
does.

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

@xref{Local Variables,,,elisp}.
@end defmac

@c copied from lispref/lists.texi
@defun ensure-list object
This function returns @var{object} as a list.  If @var{object} is
already a list, the function returns it; otherwise, the function
returns a one-element list containing @var{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:

@lisp
(dolist (elem (ensure-list foo))
  (princ elem))
@end lisp

@xref{Building Lists,,,elisp}.
@end defun

@c copied from lispref/strings.texi
@defun string-clean-whitespace string
Clean up the whitespace in @var{string} by collapsing stretches of
whitespace to a single space character, as well as removing all
whitespace from the start and the end of @var{string}.

@xref{Creating Strings,,,elisp}.
@end defun

@c copied from lispref/strings.texi
@defun string-fill string length
Attempt to Word-wrap @var{string} so that no lines are longer than
@var{length}.  Filling is done on whitespace boundaries only.  If
there are individual words that are longer than @var{length}, these
will not be shortened.

@xref{Creating Strings,,,elisp}.
@end defun

@c copied from lispref/strings.texi
@defun string-lines string &optional omit-nulls
Split @var{string} into a list of strings on newline boundaries.  If
the optional argument @var{omit-nulls} is non-@code{nil}, remove empty
lines from the results.  Note that this function returns trailing
newlines on Emacs 28, use @code{compat-call string-lines} instead if
you want consistent behavior.
@end defun

@c copied from lispref/strings.texi
@defun string-pad string length &optional padding start
Pad @var{string} to be of the given @var{length} using @var{padding}
as the padding character.  @var{padding} defaults to the space
character.  If @var{string} is longer than @var{length}, no padding is
done.  If @var{start} is @code{nil} or omitted, the padding is
appended to the characters of @var{string}, and if it's
non-@code{nil}, the padding is prepended to @var{string}'s characters.

@xref{Creating Strings,,,elisp}.
@end defun

@c copied from lispref/strings.texi
@defun string-chop-newline string
Remove the final newline, if any, from @var{string}.

@xref{Creating Strings,,,elisp}.
@end defun

@c based on lispref/variables.texi
@defmac named-let name bindings &rest body
This special form is a looping construct inspired from the
Scheme language.  It is similar to @code{let}: It binds the variables in
@var{bindings}, and then evaluates @var{body}.  However,
@code{named-let} also binds @var{name} to a
local function whose formal arguments are the variables in @var{bindings}
and whose body is @var{body}.  This allows @var{body} to call itself
recursively by calling
@var{name}, where the arguments passed to @var{name} are used as the
new values of the bound variables in the recursive invocation.

Recursive calls to @var{name} that occur in @emph{tail positions} in
@var{body} are guaranteed to be optimized as @emph{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.

@xref{Local Variables,,,elisp}.
@end defmac

@c copied from lispref/files.texi
@defun file-name-with-extension filename extension
This function returns @var{filename} with its extension set to
@var{extension}.  A single leading dot in the @var{extension} will be
stripped if there is one.  For example:

@example
(file-name-with-extension "file" "el")
     @result{} "file.el"
(file-name-with-extension "file" ".el")
     @result{} "file.el"
(file-name-with-extension "file.c" "el")
     @result{} "file.el"
@end example

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

@xref{File Name Components,File Name Components,,elisp}.
@end defun

@c copied from lispref/files.texi
@defun directory-empty-p directory
This utility function returns @code{t} if given @var{directory} is an
accessible directory and it does not contain any files, i.e., is an
empty directory.  It will ignore @samp{.} and @samp{..} on systems
that return them as files in a directory.

Symbolic links to directories count as directories.
See @var{file-symlink-p} to distinguish symlinks.

@xref{Contents of Directories,,,elisp}.
@end defun

@c copied from lispref/minibuf.texi
@defun format-prompt prompt default &rest format-args
Format @var{prompt} with default value @var{default} according to the
@code{minibuffer-default-prompt-format} variable.

@code{minibuffer-default-prompt-format} is a format string (defaulting
to @samp{" (default %s)"} that says how the ``default'' bit in prompts
like @samp{"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:

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

If @var{format-args} is @code{nil}, @var{prompt} is used as a literal
string.  If @var{format-args} is non-@code{nil}, @var{prompt} is used
as a format control string, and @var{prompt} and @var{format-args} are
passed to @code{format} (@pxref{Formatting Strings,,,elisp}).

@code{minibuffer-default-prompt-format} can be @samp{""}, in which
case no default values are displayed.

If @var{default} is @code{nil}, there is no default value, and
therefore no ``default value'' string is included in the result value.
If @var{default} is a non-@code{nil} list, the first element of the
list is used in the prompt.

@xref{Text from Minibuffer,,,elisp}.
@end defun

@c based on lisp/thingatpt.el
@defun thing-at-mouse event thing &optional no-properties
Mouse-@var{event} equivalent of @code{thing-at-point}.  @var{thing} can
be @code{symbol}, @code{list}, @code{sexp}, @code{filename}, @code{url},
@dots{} among other things.

When @var{no-properties} has a non-@code{nil} value, any text properties
that might have been present in the buffer are stripped away.
@end defun

@c based on lisp/thingatpt.el
@defun bounds-of-thing-at-mouse event thing
Determine start and end locations for @var{thing} at mouse click given
by @var{event}.  Like @code{bounds-of-thing-at-point}, but tries to use
the position in @var{event} where the mouse button is clicked to find
the thing nearby.
@end defun

@c based on lisp/mouse.el
@defun mark-thing-at-mouse click thing
Activate the region around @var{thing} found near the mouse @var{click}.
@end defun

@c based on lisp/emacs-lisp/macroexp.el
@defun macroexp-file-name
Return the name of the file in which the code is currently being
evaluated, or @code{nil} if it cannot be determined.
@end defun

@c based on lisp/emacs-lisp/macroexp.el
@defun macroexp-warn-and-return msg form &optional category compile-only arg
Return code equivalent to @code{form} labeled with warning @code{msg}.
@end defun

@c copied from on lispref/os.texi
@defmac with-environment-variables variables body@dots{}
This macro sets the environment variables according to @var{variables}
temporarily when executing @var{body}.  The previous values are
restored when the form finishes.  The argument @var{variables} should
be a list of pairs of strings of the form
@w{@code{(@var{var} @var{value})}}, where @var{var} is the name of the
environment variable and @var{value} is that variable's value.

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

@xref{System Environment,System Environment,,elisp}.
@end defmac

@c based on lisp/faces.el
@defun color-dark-p rgb
Whether @var{rgb} is more readable against white than black. @var{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 @var{rgb} as background and as foreground.
@end defun

@c based on src/xfaces.c
@defun color-values-from-color-spec spec
Convert the textual color specification @var{spec} to a color triple
@code{(@var{red} @var{green} @code{blue})}.  Each of @var{red},
@var{green} and @code{blue} is a integer value between 0 and 65535.

The specification @var{spec} can be one of the following
@itemize
@item
@code{#RGB}, where R, G and B are hex numbers of equal length, 1-4 digits each.
@item
@code{rgb:R/G/B}, where R, G, and B are hex numbers, 1-4 digits each.
@item
@code{rgbi:R/G/B}, where R, G and B are floating-point numbers in [0,1].
@end itemize
@end defun

@c copied from lispref/files.texi
@defun file-modes-number-to-symbolic modes
This function converts a numeric file mode specification in
@var{modes} into the equivalent symbolic form.

@xref{Changing Files,Changing Files,,elisp}.
@end defun

@c copied from lispref/backups.texi
@defun file-backup-file-names filename
This function returns a list of all the backup file names for
@var{filename}, or @code{nil} if there are none.  The files are sorted
by modification time, descending, so that the most recent files are
first.

@xref{Backup Names,,,elisp}.
@end defun

@c based on lisp/files.el
@defun make-lock-file-name filename
Return a string containing a lock file name for @var{filename}, obeying
@code{lock-file-name-transforms}.
@end defun

@c copied from lisp/calendar/time-date.el
@defun decoded-time-period time
Interpret @var{time} as a period and return its length in seconds.  For
computational purposes, years are 365 days long and months are 30 days
long.
@end defun

@c based on lisp/subr.el
@defun subr-primitive-p object
Return @code{t} if @var{object} is a primitive, built-in function.  On
systems with native compilation @code{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 @code{subrp}.
@end defun

@c based on lisp/subr.el
@defun subr-native-elisp-p object
Return @code{t} if @var{object} if the object is native compiled lisp.
If native compilation is not available, this function always returns
@code{nil}.
@end defun

@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
since their calling convention or behavior was extended in Emacs 28.1:

@defun compat-call@ string-width string &optional from to
This function returns the width in columns of the string @var{string},
if it were displayed in the current buffer and the selected window.
Optional arguments @var{from} and @var{to} specify the substring of
@var{string} to consider, and are interpreted as in @code{substring}
(@pxref{Creating Strings,,,elisp}).

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

@xref{Size of Displayed Text,,,elisp}.

This compatibility version handles the optional arguments @var{from} and
@var{to}.
@end defun

@c copied from on lisp/window.el
@defun compat-call@ count-windows
Return the number of live windows on the selected frame.

The optional argument @var{minibuf} specifies whether the minibuffer
window is included in the count.

If @var{all-frames} is non-@code{nil}, count the windows in all frames
instead just the selected frame.

This compatibility version handles the optional argument
@var{all-frames}.
@end defun

@c copied from on lisp/window.el
@defmac with-window-non-dedicated window &rest body
Evaluate @var{body} with @var{window} temporarily made non-dedicated.
If @var{window} is nil, use the selected window.  Return the value of
the last form in @var{body}.
@end defmac

@subsection Missing Definitions
Compat does not provide support for the following Lisp features
implemented in 28.1:

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

@node Emacs 29.1
@section Emacs 29.1

@subsection 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.

@c based on lisp/textmodes/paragraphs.el
@defun count-sentences start end
Count sentences in current buffer from @var{start} to @var{end}.
@end defun

@c copied from lispref/streams.texi
@defun readablep object
This predicate says whether @var{object} has @dfn{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 @code{nil}; if it can,
this function returns a printed representation (via @code{prin1}).
@end defun

@c copied from lispref/help.texi
@defun substitute-quotes string
This function works like @code{substitute-command-keys}, but only
replaces quote characters.
@end defun

@c based on lisp/simple.el
@defun get-scratch-buffer-create
Return the *scratch* buffer, creating a new one if needed.
@end defun

@c based on lisp/simple.el
@defun use-region-noncontiguous-p
Return non-nil for a non-contiguous region if @code{use-region-p}.
@end defun

@c based on lisp/simple.el
@defun use-region-end
Return the end of the region if @code{use-region-p}.
@end defun

@c based on lisp/simple.el
@defun use-region-beginning
Return the start of the region if @code{use-region-p}.
@end defun

@c copied from lispref/modes.texi
@findex buffer-local-restore-state
@defmac 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 @code{setq-local}, but
returns an object that can be used to restore these values back to
their previous values/states (using the companion function
@code{buffer-local-restore-state}).
@end defmac

@c based on lisp/subr.el
@defun delete-line
Delete the current line.
@end defun

@c based on lisp/subr.el
@defun list-of-strings-p object
Return @code{t} if @var{object} is @code{nil} or a list of strings.
@end defun

@c based on lisp/subr.el
@defun plistp object
Non-nil if and only if @var{object} is a valid plist.
@end defun

@c copied from lispref/cl.texi
@defmac with-memoization @var{place} @var{code}@dots{}
This macro provides a simple way to do memoization.  @var{code} is
evaluated and then stashed in @var{place}.  If @var{place}'s value is
non-@code{nil}, return that value instead of evaluating @var{code}.
@end defmac

@c based on lisp/subr.el
@defmac with-narrowing start end [:locked tag] &rest body
Execute @var{body} with restrictions set to @var{start} and @var{end}.
The current restrictions, if any, are restored upon return.  With the
optional :locked @var{tag} argument, inside @var{tag},
@code{narrow-to-region} and @code{widen} can be used only within the
@var{start} and @var{end} limits, unless the restrictions are unlocked
by calling @code{narrowing-unlock} with @var{tag}.  See
@code{narrowing-lock} for a more detailed description.
@end defmac

@c copied from lispref/positions.texi
@defun pos-bol &optional count
Like @code{line-beginning-position}, but ignores fields (and is more
efficient).
@end defun

@c copied from lispref/positions.texi
@defun pos-eol &optional count
Like @code{line-end-position}, but ignores fields (and is more
efficient).
@end defun

@c copied from lispref/display.texi
@defmac with-delayed-message (timeout message) body@dots{}
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.

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

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 @var{message} element is evaluated before @var{body}, and is
always evaluated, whether the message is displayed or not.
@end defmac

@c based on src/eval.c
@defun funcall-with-delayed-message timeout message function
Like @code{funcall}, but display @var{message} if @var{function} takes
longer than @var{timeout}.  @var{timeout} is a number of seconds, and
can be an integer or a floating point number.

If @var{function} takes less time to execute than @var{timeout}
seconds, @var{message} is not displayed.
@end defun

@c copied from lispref/display.texi
@defun 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 @var{string} into such a string, and @var{callback}
will be called when the user clicks on the button.  The optional
@var{data} parameter will be used as the parameter when @var{callback}
is called.  If @code{nil}, the button is used as the parameter instead.
@end defun

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

@c copied from lispref/display.texi
@defun get-display-property position prop &optional object properties
This convenience function can be used to get a specific display
property, no matter whether the @code{display} property is a vector, a
list or a simple property.  This is like @code{get-text-property}
(@pxref{Examining Properties,Examining Properties,,elisp,}), but works
on the @code{display} property only.

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

@c copied from lisp/subr-x.el
@defun add-display-text-property start end prop value &optional object
Add display property @var{prop} with @var{value} to the text from
@var{start} to @var{end}.  If any text in the region has a non-nil
@code{display} property, those properties are retained.

If @var{object} is non-@code{nil}, it should be a string or a buffer.
If @code{nil}, this defaults to the current buffer.
@end defun

@c copied from lispref/lists.texi
@defun take n list
This function returns the @var{n} first elements of @var{list}.  Essentially,
it returns the part of @var{list} that @code{nthcdr} skips.

@code{take} returns @var{list} if shorter than @var{n} elements;
it returns @code{nil} if @var{n} is zero or negative.

@example
@group
(take 3 '(a b c d))
     @result{} (a b c)
@end group
@group
(take 10 '(a b c d))
     @result{} (a b c d)
@end group
@group
(take 0 '(a b c d))
     @result{} nil
@end group
@end example
@end defun

@c copied from lispref/lists.texi
@defun ntake n list
This is a version of @code{take} that works by destructively modifying
the list structure of the argument.  That makes it faster, but the
original value of @var{list} may be lost.

@code{ntake} returns @var{list} unmodified if shorter than @var{n}
elements; it returns @code{nil} if @var{n} is zero or negative.
Otherwise, it returns @var{list} truncated to its first @var{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 @var{n} is known to be
positive.
@end defun

@c copied from lispref/functions.texi
@defun compiled-function-p object
This function returns @code{t} if @var{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
@code{t} if the function is built-in, or byte-compiled, or
natively-compiled, or a function loaded from a dynamic module.
@end defun

@c copied from lispref/functions.texi
@defun function-alias-p object &optional noerror
Checks whether @var{object} is a function alias.  If it is, it returns
a list of symbols representing the function alias chain, else
@code{nil}.  For instance, if @code{a} is an alias for @code{b}, and
@code{b} is an alias for @code{c}:

@example
(function-alias-p 'a)
    @result{} (b c)
@end example

If there's a loop in the definitions, an error will be signalled.  If
@var{noerror} is non-@code{nil}, the non-looping parts of the chain is
returned instead.
@end defun

@c copied from lispref/strings.texi
@defun string-equal-ignore-case string1 string2
@code{string-equal-ignore-case} compares strings ignoring case
differences, like @code{char-equal} when @code{case-fold-search} is
@code{t}.

@xref{Text Comparison,,,elisp}.
@end defun

@defun string-split string &optional separators omit-nulls trim
@code{string-split} is an alias for the function @code{split-string}.
The name follows the convention of other string functions.

@xref{Creating Strings,,,elisp}.
@end defun

@c copied from lispref/buffers.texi
@defun buffer-match-p condition buffer-or-name &optional arg
This function checks if a buffer designated by @code{buffer-or-name}
satisfies a @code{condition}.  Optional third argument @var{arg} is
passed to the predicate function in @var{condition}.  A condition can
be one of the following:
@itemize @bullet{}
@item
A string, interpreted as a regular expression.  The buffer
satisfies the condition if the regular expression matches the buffer
name.
@item
A predicate function, which should return non-@code{nil} if the buffer
matches.  If the function expects one argument, it is called with
@var{buffer-or-name} as the argument; if it expects 2 arguments, the
first argument is @var{buffer-or-name} and the second is @var{arg}
(or @code{nil} if @var{arg} is omitted).
@item
A cons-cell @code{(@var{oper} . @var{expr})} where @var{oper} is one
of
@table @code
@item not
Satisfied if @var{expr} doesn't satisfy @code{buffer-match-p} with
the same buffer and @code{arg}.
@item or
Satisfied if @var{expr} is a list and @emph{any} condition in
@var{expr} satisfies @code{buffer-match-p}, with the same buffer and
@code{arg}.
@item and
Satisfied if @var{expr} is a list and @emph{all} conditions in
@var{expr} satisfy @code{buffer-match-p}, with the same buffer and
@code{arg}.
@item derived-mode
Satisfied if the buffer's major mode derives from @var{expr}.
@item major-mode
Satisfied if the buffer's major mode is equal to @var{expr}.  Prefer
using @code{derived-mode} instead when both can work.
@end table
@item t
Satisfied by any buffer.  A convenient alternative to @code{""} (empty
string), @code{(and)} (empty conjunction) or @code{always}.
@end itemize

@xref{Buffer List,,,elisp}.
@end defun

@c copied from lispref/buffers.texi
@defun match-buffers condition &optional buffers arg
This function returns a list of all buffers that satisfy a
@code{condition}, as defined for @code{buffer-match-p}.  By default
all buffers are considered, but this can be restricted via the second
optional @code{buffer-list} argument.  Optional third argument
@var{arg} will be used by @var{condition} in the same way as
@code{buffer-match-p} does.

@xref{Buffer List,,,elisp}.
@end defun

@c copied from lispref/display.texi
@defun string-glyph-split string
When character compositions are in effect, sequence of characters can
be composed for display to form @emph{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
suvh jobs: it splits up its argument @var{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 @var{string} which will
look correctly on display, or compute the width of any substring of
@var{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:

@example
(apply #'insert (cdr (string-glyph-split string))))
@end example

@xref{Size of Displayed Text,,,elisp}.
@end defun

@c based on lisp/subr-x.el
@defmac with-buffer-unmodified-if-unchanged &rest body@dots{}
Evaluate @var{body} like @code{progn}, but change buffer-modified
status only if buffer text changes.  If the buffer was unmodified
before execution of @var{body}, and buffer text after execution of
@var{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, @code{buffer-file-coding-system}, buffer multibyteness,
etc. -- will not be noticed, and the buffer will still be marked
unmodified, effectively ignoring those changes.
@end defmac

@defun file-attribute-file-identifier
Return the fields @code{(inodenum device)} as a list from attributes
generated by @code{file-attributes}.

@xref{File Attributes,,,elisp}.
@end defun

@c copied from lispref/files.texi
@defun file-name-split filename
This function splits a file name into its components, and can be
thought of as the inverse of @code{string-join} with the appropriate
directory separator.  For example,

@example
(file-name-split "/tmp/foo.txt")
    @result{} ("" "tmp" "foo.txt")
(string-join (file-name-split "/tmp/foo.txt") "/")
    @result{} "/tmp/foo.txt"
@end example
@end defun

@c copied from lispref/files.texi
@defun file-name-parent-directory filename
This function returns the directory name of the parent directory of
@var{filename}.  If @var{filename} is at the root directory of the
filesystem, it returns @code{nil}.  A relative @var{filename} is
assumed to be relative to @code{default-directory}, and the return
value will also be relative in that case.  If the return value is
non-@code{nil}, it ends in a slash.

@xref{Directory Names,,,elisp}.
@end defun

@c copied from lispref/files.texi
@defun file-has-changed-p file &optional tag
This function returns non-@code{nil} if the time stamp of
@var{filename} has changed since the last call.  When called for the
first time for some @var{filename}, it records the last modification
time and size of the file, and returns non-@code{nil} when
@var{filename} exists.  Thereafter, when called for the same
@var{filename}, it compares the current time stamp and size with the
recorded ones, and returns non-@code{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 @var{tag}, which must be a symbol, the size and modification
time comparisons are limited to calls with the same tag.

@xref{File Attributes,,,elisp}.
@end defun

@c based on lisp/keymap.el
@defun key-valid-p keys
Say whether @var{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.

@table @kbd
@item f
The key @kbd{f}.
@item S o m
A three key sequence of the keys @kbd{S}, @kbd{o} and @kbd{m}.
@item C-c o
A two key sequence of the keys @kbd{c} with the control modifier and
then the key @kbd{o}.
@item H-<left>
The key named "left" with the hyper modifier.
@item M-RET
The "return" key with a meta modifier.
@item C-M-<space>
The "space" key with both the control and meta modifiers.
@end table

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

Modifiers have to be specified in this order
@verbatim
Alt (A)-Control (C)-Hyper (H)-Meta (M)-Shift (s)-Super (s)
@end verbatim
@end defun

@c based on lisp/keymap.el and lisp/subr.el
@defun key-parse keys
Convert @var{keys} to the internal Emacs key representation.  See
@code{key-valid-p} for a description of valid key sequences.  Examples
include @kbd{f}, @kbd{C-c C-c}, @kbd{H-<left>}, @kbd{M-RET} or
@kbd{C-M-<return>}.

@end defun

@c copied from lispref/keymaps.texi
@defun keymap-set keymap key definition
This function sets the binding for @var{key} in @var{keymap}.  (If
@var{key} is more than one event long, the change is actually made in
another keymap reached from @var{keymap}.)  The argument @var{binding}
can be any Lisp object, but only certain types are meaningful.  (For a
list of meaningful types, see @ref{Key Lookup,,,elisp}.)  The value
returned by @code{keymap-set} is @var{binding}.

If @var{key} is @kbd{<t>}, this sets the default binding in
@var{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 @var{key} must be a prefix key (i.e., bound to a keymap)
or undefined; otherwise an error is signaled.  If some prefix of
@var{key} is undefined, then @code{keymap-set} defines it as a prefix
key so that the rest of @var{key} can be defined as specified.

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

@xref{Changing Key Bindings,,,elisp}.
@end defun

@c copied from lispref/keymaps.texi
@defun keymap-global-set key command
This function sets the binding of @var{key} in the current global map
to @var{binding}.

@smallexample
@group
(keymap-global-set @var{key} @var{binding})
@equiv{}
(keymap-set (current-global-map) @var{key} @var{binding})
@end group
@end smallexample

@xref{Key Binding Commands,,,elisp}.
@end defun

@c copied from lispref/keymaps.texi
@defun keymap-local-set key command
This function sets the binding of @var{key} in the current local
keymap to @var{binding}.

@smallexample
@group
(keymap-local-set @var{key} @var{binding})
@equiv{}
(keymap-set (current-local-map) @var{key} @var{binding})
@end group
@end smallexample

@xref{Key Binding Commands,,,elisp}.
@end defun

@c copied from lispref/keymaps.texi
@defun keymap-global-unset key &optional remove
This function removes the binding of @var{key} from the current
global map.

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

@smallexample
@group
(keymap-global-unset "C-l")
    @result{} nil
@end group
@group
(keymap-global-set "C-l C-l" 'redraw-display)
    @result{} nil
@end group
@end smallexample

@xref{Key Binding Commands,,,elisp}.
@end defun

@c copied from lispref/keymaps.texi
@defun keymap-local-unset key &optional remove
This function removes the binding of @var{key} from the current
local map.

@xref{Key Binding Commands,,,elisp}.
@end defun

@c based on from lisp/keymap.el
@defun keymap-substitute keymap olddef newdef &optional oldmap prefix
Replace @var{olddef} with @var{newdef} for any keys in @var{keymap} now
defined as @var{olddef}.  In other words, @var{olddef} is replaced with
@var{newdef} wherever it appears.  Alternatively, if optional fourth
argument @var{oldmap} is specified, we redefine in @var{keymap} as
@var{newdef} those keys that are defined as @var{olddef} in
@var{oldmap}.
@end defun

@c copied from lispref/keymaps.texi
@defun keymap-lookup keymap key &optional accept-default no-remap position
This function returns the definition of @var{key} in @var{keymap}.  All
the other functions described in this chapter that look up keys use
@code{keymap-lookup}.  Here are examples:

@example
@group
(keymap-lookup (current-global-map) "C-x C-f")
    @result{} find-file
@end group
@group
(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5")
    @result{} 2
@end group
@end example

@xref{Functions for Key Lookup,,,elisp}.
@end defun

@c copied from lispref/keymaps.texi
@defun keymap-local-lookup keys &optional accept-default
Like @code{keymap-lookup}, but restricting the search for commands bound
to @var{keys} to the current local keymap.
@end defun

@c copied from lispref/keymaps.texi
@defun keymap-global-lookup keys &optional accept-default
Like @code{keymap-lookup}, but restricting the search for commands bound
to @var{keys} to the current global keymap.
@end defun

@c copied from lispref/keymaps.texi
@defun define-keymap &rest definitions
You can create a keymap with the functions described above, and then use
@code{keymap-set} (@pxref{Changing Key Bindings,,,elisp}) 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 @code{keymap-set} on
them all can be tedious and error-prone.  Instead you can use
@code{define-keymap}, which creates a keymap and binds a number of keys.
Here's a very basic example:

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

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

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

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

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 @code{define-keymap} call, the default value for that
feature is @code{nil}.  Here's a list of the available feature
keywords:

@table @code
@item :full
If non-@code{nil}, create a char-table keymap (as from
@code{make-keymap}) instead of a sparse keymap (as from
@code{make-sparse-keymap} (@pxref{Creating Keymaps,,,elisp}).  A sparse
keymap is the default.

@item :parent
If non-@code{nil}, the value should be a keymap to use as the parent
(@pxref{Inheritance and Keymaps,,,elisp}).

@item :keymap
If non-@code{nil}, the value should be a keymap.  Instead of creating
a new keymap, the specified keymap is modified instead.

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

@item :name
If non-@code{nil}, the value should be a string to use as the menu for
the keymap if you use it as a menu with @code{x-popup-menu}
(@pxref{Pop-Up Menus,,,elisp}).

@item :prefix
If non-@code{nil}, the value should be a symbol to be used as a prefix
command (@pxref{Prefix Keys,,,elisp}).  If this is the case, this symbol
is returned by @code{define-keymap} instead of the map itself.
@end table
@end defun

@c copied from lispref/keymaps.texi
@defun 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
@code{foo} almost always has a variable called @code{foo-mode-map}.

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

@var{options} is like the keywords in @code{define-keymap}, but
there's an additional @code{:doc} keyword that provides the doc
string for the defined variable.

Here's an example:

@lisp
(defvar-keymap eww-textarea-map
  :parent text-mode-map
  "RET" #'forward-line
  "TAB" #'shr-next-link)
@end lisp
@end defun

@c copied from lispref/control.texi
@defmac while-let spec then-forms...
Like @code{when-let}, but repeat until a binding in @var{spec} is
@code{nil}.  The return value is always @code{nil}.

This is comparable to @code{and-let*}.
@end defmac

@c based on lisp/emacs-lisp/ert-x.el
@defmac ert-with-temp-file name &rest body
Bind @var{name} to the name of a new temporary file and evaluate
@var{body}.  Delete the temporary file after @var{body} exits normally
or non-locally.  @var{name} will be bound to the file name of the
temporary file. See the docstring for supported keyword arguments.
@end defmac

@c based on lisp/emacs-lisp/ert-x.el
@defmac ert-with-temp-directory name &rest body
Bind @var{name} to the name of a new temporary directory and evaluate
@var{body}.  Delete the temporary directory after @var{body} exits
normally or non-locally.

@var{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
@code{ert-with-temp-file} (which see), except for @code{:text}.
@end defmac

@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
since their calling convention or behavior was extended in Emacs 29.1:

@c copied from lispref/strings.texi
@defun compat-call@ string-lines string &optional omit-nulls keep-newlines
Split @var{string} into a list of strings on newline boundaries.  If
the optional argument @var{omit-nulls} is non-@code{nil}, remove empty
lines from the results.  If the optional argument @var{keep-newlines}
is non-@code{nil}, don't remove the trailing newlines from the result
strings.

@xref{Creating Strings,,,elisp}.
@end defun

@c copied from lispref/keymaps.texi
@defun compat-call@ define-key
This function is like @code{keymap-set} (@pxref{Changing Key
Bindings,,,elisp}, but understands only the legacy key syntaxes.

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

@xref{Low-Level Key Binding,,,elisp}.

This compatibility version handles the optional argument
@var{remove}.
@end defun

@c copied from lispref/lists.texi
@defun compat-call@ plist-get plist prop &optional predicate
This returns the value of the @var{property} property stored in the
property list @var{plist}.  Comparisons are done with @var{predicate},
and defaults to @code{eq}.  It accepts a malformed @var{plist}
argument.  If @var{property} is not found in the @var{plist}, it
returns @code{nil}.

@xref{Plist Access,,,elisp}.

This compatibility version handles the optional argument
@var{predicate}.  This is a generalized variable (@pxref{Generalized
Variables,,,elisp}) that can be used to change a value with
@code{setf}.
@end defun

@c copied from lispref/lists.texi
@defun compat-call@ plist-put plist prop val &optional predicate
This stores @var{value} as the value of the @var{property} property in
the property list @var{plist}.  Comparisons are done with @var{predicate},
and defaults to @code{eq}.  It may modify @var{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 @var{plist}.

@xref{Plist Access,,,elisp}.

This compatibility version handles the optional argument
@var{predicate}.
@end defun

@c copied from lispref/lists.texi
@defun compat-call@ plist-member plist prop &optional predicate
This returns non-@code{nil} if @var{plist} contains the given
@var{property}.  Comparisons are done with @var{predicate}, and
defaults to @code{eq}.  Unlike @code{plist-get}, this allows you to
distinguish between a missing property and a property with the value
@code{nil}.  The value is actually the tail of @var{plist} whose
@code{car} is @var{property}.

@xref{Plist Access,,,elisp}.

This compatibility version handles the optional argument
@var{predicate}.
@end defun

@subsection Missing Definitions
Compat does not provide support for the following Lisp features
implemented in 29.1:

@itemize
@item
The function @code{imagep}.
@item
The function @code{function-documentation}.
@item
The command @code{string-edit} and @code{read-string-from-buffer}.
@item
The macro @code{with-undo-amalgamate}.
@item
The function @code{string-glyph-split}.
@item
The function @code{string-limit}.
@item
The function @code{string-pixel-width}.
@item
The function @code{buffer-text-pixel-size}.
@item
The function @code{pixel-fill-region}.
@item
The function @code{textsec-suspicious-p}.
@item
The function @code{minibuffer-lazy-highlight-setup}.
@item
The function @code{pp-emacs-lisp-code}.
@end itemize

@node Development
@chapter Development

Compat is developed on GitHub.

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

Please note that as a GNU ELPA package, Compat requires contributors
to have signed the
@uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html,
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.


@node Function Index
@appendix Function Index

@printindex fn

@node Variable Index
@appendix Variable Index

@printindex vr

@bye