Re: add-to-list vs cl-pushnew

[Robin Tarsiger <rtt@dasyatidae.com>]

Stefan Monnier wrote:
>> (Aside: why not replace add-to-list with cl-pushnew always?
> 
> Good question.
> 
> 
>         Stefan "who really doesn't like `add-to-list`"

In case it was interpreted differently, my original question was
rhetorical. There's several reasons I can think of to keep using
add-to-list's current behavior as-is for its primary use case,
as opposed to recommending that new code avoid it entirely:

  - The unquoted variable name argument leaving available the
    make-local-variable idiom and similar.

  - The presence of the APPEND arg. This being a toggle lets it
    be plumbed through wrapper functions easily, so that you can
    write (defun foo-add-bar (bar &optional at-end) ...) and call
    (add-to-list 'foo-bar-list rectified-bar at-end) from it.

  - The use of equal, not eql, as the default comparison function.
    This becomes important if any of the list variables contain
    almost anything other than symbols, and I could see eql as a
    default in this case leading to subtle bugs since duplicates
    wouldn't be common, nor necessarily punished in practice.
    (eql "foo" "foo") is allowed to be nil.

  - The docstring mentioning the potential need for eval-after-load
    to handle package ordering issues, which is an easy source of
    bugs in add-to-list's main use case but irrelevant in most
    list processing. If you just use the general list processing
    functions, there isn't as good a place to warn about that.

  - I recall a while ago that pulling in the cl library for one
    or two symbols was considered bad style because it was quite
    heavy, but I don't know if that's still true.

However, I would not be averse to finding it a better primary name
and demoting the add-to-list name to being a compatibility alias,
especially if new elisp programmers are likely to stumble into it
and skip over the the "please do not abuse for general list
manipulation" part of the doc, since the name itself both doesn't
imply that right now and is paradoxically easier to find than the
push family by some (albeit not-so-good) routes. If you do this,
you'd want to hit add-to-ordered-list too.

I also think upon looking at the "List Variables" section again
that it could usefully be split up, since putting push and
add-to-list right next to each other when the latter is so much
more specialized could be structurally misleading. (The "please
do not abuse" text is also nowhere there, instead obscured behind
"Do not use this function when SYMBOL refers to a lexical
variable.", which could lead off into the weeds of e.g. "ah,
so if I want to use this function on locals then I have to not
use lexical-binding" to someone not already receiving usage
cues from other places.)

-RTT