(BTW - Even a purely functional definition of `push' would return the new stack/list value. And users would of course make use of that return value.)

___

 

Besides the Hyperspec, Common Lisp the Language says this (and it's the case also for the first, 1984 edition, not just CLTL2):

[Macro]
push item place

The form place should be the name of a generalized variable containing a list; item may refer to any Lisp object. The item is consed onto the front of the list, and the augmented list is stored back into place and returned. The form place may be any form acceptable as a generalized variable to setf. If the list held in place is viewed as a push-down stack, then push pushes an element onto the top of the stack. For example:

(setq x '(a (b c) d)) 

(push 5 (cadr x)) => (5 b c)  and now x => (a (5 b c) d)

The effect of (push item place) is roughly equivalent to

(setf place (cons item place))

except that the latter would evaluate any subforms of place twice, while push takes care to evaluate them only once. Moreover, for certain place forms push may be significantly more efficient than the setf version.

 

On Sat, Dec 7, 2019 at 5:48 AM Richard Stallman <HYPERLINK "mailto:rms@gnu.org"rms@gnu.org> wrote:

> What does Common Lisp say about the return value of 'push'?

From the Common Lisp Hyperspec:

 

Macro PUSH

Syntax:

push item place => new-place-value

Arguments and Values:

item---an object.

place---a place, the value of which may be any object.

new-place-value---a list (the new value of place).

Description:

HYPERLINK \l "push prepends item to the list that is stored in place, stores the resulting list in place, and returns the list.

> If Common Lisp describes a certain return value for 'push',
> people will tend to use it that way,

Yes, though as I said, it is very rarely used, at least on our sources. 34 uses out of ~4,100.

There are also a lot like
(and test-1 test-2 ... (push item place))

but don't really depend on the return value of `push', they're just using `and' as a conditional.

 

> and I think it would be a waste of time changing all code that ever depends on that return value.

 

At least for our sources, that time's already been wasted, whether we apply my patch or not.

 

Emacs Lisp is not just for "our sources". It's for Emacs users. What we show as the doc of a function matters for users, not just for Emacs internal developers.

 

> It would be easier to document that return value.

 

Not just easier. Better, including for users.

I tend to agree, because I don't like gratuitously discarding CL compatibility.