GNU bug report logs - #66554
[PATCH] Add the public API of Compat to the core

Previous Next

Full log

Message #193 received at 66554 <at> debbugs.gnu.org (full text, mbox):

From: Philip Kaludercic <philipk <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: mail <at> daniel-mendler.de, stefankangas <at> gmail.com, monnier <at> iro.umontreal.ca,
 66554 <at> debbugs.gnu.org
Subject: Re: bug#66554: [PATCH] Add the public API of Compat to the core
Date: Thu, 08 Feb 2024 07:40:23 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Philip Kaludercic <philipk <at> posteo.net>
>> Cc: mail <at> daniel-mendler.de,  66554 <at> debbugs.gnu.org,  stefankangas <at> gmail.com,
>>   monnier <at> iro.umontreal.ca
>> Date: Wed, 07 Feb 2024 17:15:45 +0000
>> 
>> >> Let me try to make my point more clear: I'd prefer that the reader
>> >> emerges from reading this description with a practical way of knowing
>> >> when to call the function directly and when to call it via
>> >> 'compat-call'.  If that's not easy to understand, perhaps we should
>> >> tell that 'compat-call' should always be used, to avoid some rare
>> >> corner cases where a direct call will not do, and be done?
>> >
>> > I don't think we should recommend always using `compat-call', that would
>> > make code unreadable.  What definitions have to be called via
>> > `compat-call' really depends on how they were defined in Compat.  I
>> > don't know of a better rule to describe it without copying the
>> > documentation from the Compat manual (that wouldn't be a good idea
>> > either, because it wouldn't stay up to date).
>> 
>> Daniel, do have any ideas how to improve the documentation here?  It
>> seems to me that the authoritative source of information on what
>> functions to compat-call is Compat itself, right?
>
> What does Compat manual say about this aspect?

--8<---------------cut here---------------start------------->8---
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
--8<---------------cut here---------------end--------------->8---

and then later on, for each version there is a section like this

--8<---------------cut here---------------start------------->8---
@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/keymaps.texi
@defun compat-call@ set-transient-map keymap &optional keep-pred on-exit message timeout
This function adds @var{keymap} as a @dfn{transient} keymap, which
takes precedence over other keymaps for one (or more) subsequent keys.
...
--8<---------------cut here---------------end--------------->8---

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.