From d07f177382b24945e1f579744702908b33605c3e Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= Date: Sat, 1 Feb 2020 20:11:11 +0100 Subject: [PATCH] Clarify add-to-list documentation (bug#39373) While add-to-list often works with lexical variables, this is a hack that isn't always effective; better tell the user not to try. * doc/lispref/lists.texi (List Variables): Add a note about lexical variables to the add-to-list description. Fix the equivalent code. * lisp/subr.el (add-to-list): Amend doc string. --- doc/lispref/lists.texi | 8 ++++++-- lisp/subr.el | 1 + 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 5ef21d06710..ce0d9a3c922 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -777,6 +777,9 @@ non-@code{nil}, it is added at the end. The argument @var{symbol} is not implicitly quoted; @code{add-to-list} is an ordinary function, like @code{set} and unlike @code{setq}. Quote the argument yourself if that is what you want. + +Do not use this function when @var{symbol} refers to a lexical +variable. @end defun Here's a scenario showing how to use @code{add-to-list}: @@ -799,8 +802,9 @@ foo ;; @r{@code{foo} was changed.} @var{value})} is this: @example -(or (member @var{value} @var{var}) - (setq @var{var} (cons @var{value} @var{var}))) +(if (member @var{value} @var{var}) + @var{var} + (setq @var{var} (cons @var{value} @var{var}))) @end example @defun add-to-ordered-list symbol element &optional order diff --git a/lisp/subr.el b/lisp/subr.el index a4fdc6bdfef..05fb82321e5 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -1845,6 +1845,7 @@ COMPARE-FN if that's non-nil. If ELEMENT is added, it is added at the beginning of the list, unless the optional argument APPEND is non-nil, in which case ELEMENT is added at the end. +LIST-VAR should not refer to a lexical variable. The return value is the new value of LIST-VAR. -- 2.39.5