Commit d07f1773 authored by Mattias Engdegård's avatar Mattias Engdegård

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.
parent d3d2ea92
......@@ -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
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment