bug#75170: add-to-alist: new function

[Roland Winkler <winkler@gnu.org>]

On Mon, 12 Feb 2001, Stephen Gildea wrote:
> Here's a handy function I'd like to see added to Emacs 21: add-to-alist.
> It is like add-to-list, but it looks only at the cars of the element to
> be added and the existing list elements when considering a match.  An
> additional optional argument to add-to-alist says what to do if the car
> matches but the cdr does not.
> 
> I use this function in my .emacs to update values in alists such as
> default-frame-alist and auto-mode-alist; I'm sure it has other uses.
> My goal in proposing this function is to allow .emacs files to be
> shorter and easier to write.  The functions add-to-list and add-hook
> were important steps in that direction; here is another such step.
> 
> 
> (defun add-to-alist (alist-var elt-cons &optional no-replace)
>   "Add to the value of ALIST-VAR an element ELT-CONS if it isn't there yet.
> If an element with the same car as the car of ELT-CONS is already present,
> replace it with ELT-CONS unless NO-REPLACE is non-nil; if a matching
> element is not already present, add ELT-CONS to the front of the alist.
> The test for presence of the car of ELT-CONS is done with `equal'."
>   (let ((existing-element (assoc (car elt-cons) (symbol-value alist-var))))
>     (if existing-element
>         (or no-replace
>             (rplacd existing-element (cdr elt-cons)))
>       (set alist-var (cons elt-cons (symbol-value alist-var))))))
> 
> 
> The no-replace argument is useful for setting auto-mode-alist when you
> don't know whether Emacs supports a particular programming language.
> For example, the following suppresses using text-mode for m4 files in
> Emacs 19 but doesn't override using m4-mode in Emacs 20.
> 
> (setq default-major-mode 'text-mode)
> (add-to-alist 'auto-mode-alist '("\\.m4\\'" . fundamental-mode) t)

While I thought about a function add-to-alist I found the above thread
from 24 years ago.  Stephen's message describes nicely when such a
function can be useful.  I suggest to add such a function to subr.el.

The code below follows the conventions of add-to-list.

(defun add-to-alist (alist-var elt-cons &optional no-replace append compare-fn)
  "Add ELT-CONS to the value of ALIST-VAR if it isn't there yet.
If an element with the same car as the car of ELT-CONS is already present
in ALIST-VAR, replace it with ELT-CONS unless NO-REPLACE is non-nil.
If a matching element is not yet present, add ELT-CONS at the beginning
of ALIST-VAR.  If APPEND is non-nil, add ELT-CONS at the end of ALIST-VAR.
The test for presence of ELT-CONS is done with `equal', or with COMPARE-FN
if that's non-nil.
ALIST-VAR should not refer to a lexical variable.

The return value is the new value of ALIST-VAR."
  (let ((elt (cond ((or (null compare-fn) (eq compare-fn #'equal))
	            (assoc (car elt-cons) (symbol-value alist-var)))
                   ((eq compare-fn #'eq)
	            (assq (car elt-cons) (symbol-value alist-var)))
                   (t
	            (let ((alist (symbol-value alist-var))
                          (key (car elt-cons)))
	              (while (and alist
                                  (not (funcall compare-fn key (caar alist))))
	                (setq alist (cdr alist)))
                      (car alist))))))
    (if elt
        (progn
          (unless no-replace
            (setcdr elt (cdr elt-cons)))
          (symbol-value alist-var))
      (set alist-var
	   (if append
	       (append (symbol-value alist-var) (list elt-cons))
	     (cons elt-cons (symbol-value alist-var)))))))