bug#40671: [DOC] modify literal objects

[Paul Eggert]

On 4/19/20 4:45 PM, Michael Heerdegen wrote:

> I have just the feeling sure if you simplify too much.  Lisp has
> reading, compiling, evaluation....

Yes, it can be complicated under the hood. The current section attempts to 
document this conservatively, saying "If your program does this it'll be safe." 
It does not attempt to document much of what happens if you step outside the 
"safe" boundaries (i.e., if you attempt to modify "constants" - to use the 
current terminology).

One can indeed imagine more-detailed documentation about what happens if you 
modify constants. However, I didn't have the time or inclination to document the 
details there, and on the whole I think this was the right decision. It's not a 
win to greatly complicate the Elisp documentation to cover iffy edge-cases that 
code shouldn't be exploring anyway. On the contrary, we should leave things 
unspecified in this dangerous area, to give future implementers more freedom to 
improve Emacs.


> (let ((l (list 1 2 3)))
>    `',l)
>
> ==> '(1 2 3)
>
> If you evaluate this (the return value is a valid expression), `quote'
> returns a list, but it's not a list literal.

Sure, but one shouldn't be modifying that list. Once you hand a Lisp object to 
'eval', modifying that object later ought to be a no-no even if the interpreter 
happens to do something non-crashy now. Otherwise we're placing too many 
constraints on the Lisp implementation (which can crash even now if you play 
this sort of game).

> > > |  Vectors written with square brackets are constants and should not be
> > > |  modified via @code{aset} or other destructive operations.
> > > (let ((l (list 1 2 3)))
> > >     (let ((my-vector `[,@l]))
> > >       my-vector))
> > > What does this sentence tell me about the vector I constructed?
> >
> > Nothing, just as the documentation for splicing also says nothing
> > about that vector.
>
> One could read your sentence as suggesting that `my-vector' would be
> constant because square brackets are used to construct it.  This was an
> example to demonstrate where your wording is too vague in my opinion.

OK, how about if we append the following sentence to that section:

  As an exception to the above rules, a vector within a backquote construct
is not considered to be a constant if it contains a substitution or splice.


That is, the backquote causes the vector to (a) not be considered a constant, 
(b) be newly created each time the backquote is evaluated, and (c) mutable. The 
(a) and (b) parts fix problems that were already there in the longstanding 
documentation; the (c) part is new.