Re: emacs-27 eebfb72 1/2: Document constant vs mutable objects better

["Štěpán Němec" <stepnem@gmail.com>]

On Sun, 19 Apr 2020 13:37:54 -0700
Paul Eggert wrote:

> Unless otherwise specified, the patch simply adopts your other
> suggestions.

Thank you, and sorry for aggravating your pain.

Regarding comparing two equal floats, strings or lists by `eq', you warn
about its undefinedness ("might not return nil") repeatedly, but can you
give an actual example where (eq 1.2 1.2) or (eq "string" "string")
returns non-nil in Elisp?

Otherwise, isn't it too hypothetical/theoretical to talk about in the
manual? I guess it is imaginable that a compiler might do that, but so
are other things that Elisp could do but doesn't.

>> IOW, "mutable" and "safely
>> mutable"/"mutating it is a good idea" should be distinguished.
>
> The attached patch makes that distinction in a new section "Constants
> and mutability" that I hope clarifies some of the issues here. While
> writing this, I noticed that for Elisp we needn't separate the three
> notions (not-mutable-and-this-is-checked, not-safe-to-mutate,
> safely-mutable) everywhere; all we need to do is describe those
> notions in one spot, and everywhere else we can just use the term
> "mutable" for safely-mutable and the term "constant" for everything
> else.

I think there is no disagreement about the issues involved, but about
the terms used to describe them. I still think that formulations like
"the other arguments (all but the last) should be mutable lists" are
unfortunate, because all Elisp lists are mutable. IOW, "mutable" and
"immutable" seem better suited for data structure classification than
Elisp best practices recommendations. All lists/strings/vectors are
mutable in Elisp. The manual had better describe under what
circumstances one should not mutate them, and I don't think calling the
same data structure once "mutable" and once not will help rather than
confuse or mystify.

> diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
> index 46cfab164b..deb288943a 100644
> --- a/doc/lispref/eval.texi
> +++ b/doc/lispref/eval.texi
> @@ -158,6 +158,12 @@ contents unchanged.
>  @end group
>  @end example
>  
> +  A self-evaluating form yields a constant, and you should not attempt
> +to modify the constant's contents via @code{setcar}, @code{aset} or
> +similar primitives.  The Lisp interpreter might unify the constants
           ^^^^^^^^^^
In the Elisp manual, "primitive" is defined as "A function which is
callable from Lisp but is actually written in C", but I think we want to
say that one shouldn't try to modify constants, period; no matter the
particular means used.

> +yielded by your program's self-evaluating forms, so that these
> +constants might share structure.  @xref{Constants and Mutability}.
> +
> @@ -1306,10 +1306,10 @@ same way in Lisp input.
>  
>    A vector, like a string or a number, is considered a constant for
>  evaluation: the result of evaluating it is the same vector.  This does
> -not evaluate or even examine the elements of the vector.  Vectors
> -written with square brackets are constants and should not be modified
> -via @code{aset} or other destructive operations.
> -@xref{Self-Evaluating Forms}.
> +not evaluate or even examine the elements of the vector.
> +@xref{Self-Evaluating Forms}.  Vectors written with square brackets
> +are constants and should not be modified via @code{aset} or other
> +destructive operations.  @xref{Constants and Mutability}.

This is a good formulation IMO: no "(im)mutable" needed. Such and such
are (considered) constant/literal, and should not be modified/modifying
them leads to undefined consequences.

  Thanks,

  Štěpán