bug#40671: [DOC] modify literal objects

[Dmitry Gutov]

On 02.05.2020 00:40, Paul Eggert wrote:

> > As Drew pointed out (and if I understood this correctly), the above
> > specification leads to implementations that do raise an error when someone tried
> > to modify such a value.
>
> Although those implementations conform to the Common Lisp spec, that's because
> the spec explicitly says such behavior is undefined - which means
> implementations can signal an error, dump core, or do whatever else they want.
> See <https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node11.html>, which uses
> "should" in the same sense the emacs-27 elisp manual uses "should".

I suppose so.

> When this book specifies that it "is an error" for some situation to occur, this
> means that:
>
> * No valid Common Lisp program should cause this situation to occur.
>
> * If this situation occurs, the effects and results are completely undefined as
> far as adherence to the Common Lisp specification is concerned.
>
> * No Common Lisp implementation is required to detect such an error. Of course,
> implementors are encouraged to provide for detection of such errors wherever
> reasonable.
>
> This is not to say that some particular implementation might not define the
> effects and results for such a situation; the point is that no program
> conforming to the Common Lisp specification may correctly depend on such effects
> or results.

Indeed.

I took a longer look around the CLtL, to see how the term "constant" is 
used there, though. Some phrases:

---

  ...it is an error to destructively modify any object that appears as 
a constant in executable code, whether as a self-evaluating form or 
within a quote special form

  ...to specify what objects can be in compiled constants...

  quoted constants in it are similar in this sense to quoted constants 
in the corresponding source code

  An object may be used as a quoted constant...

  Some types of objects, such as streams, are not supported in 
constants processed by the file compiler. Such objects may not portably 
appear as constants in code processed with compile-file.

  The following terms are used throughout this section. The term 
constant refers to a quoted or self-evaluating constant, not a named 
constant defined by defconstant.

  Two objects are similar as a constant if and only if they are both of 
one of the types listed below and satisfy...

  Two conses are similar as constants if the values of their respective 
car and cdr attributes are similar as constants.

  (Then comes the description of "similar as constants" values being 
coalesced in compiled code).

---

CL's terminology seems fairly old by today's standards, but it looks 
like they were grasping for words, just as we are now.

They very rarely use the phrase "constant objects", however. Instead, 
it's almost always "objects that appears as a constant [in code]", 
"object ... used as a quoted constant", "object may not ... appear as 
constants in code", "objects are similar as a constant".

IOW, it's the difference between constant values and constant pointers 
to [mutable] values. And the users are advised not to change the objects 
that "appear as constants"/[play the role of constants]/[are the values 
of constants] in executable code.

And there is no juxtaposition of "mutable objects" vs "constant objects" 
anywhere in there, with "constant" defined like that, which is the part 
of our new documentation that really got me into this discussion. So the 
section "Constants and Mutability", even though it has valuable 
information, could use a full rewrite. And could probably move to end of 
the "Self-Evaluating Forms" section.

I'm also not sure it's a good idea to add too much explanations to the 
introduction featuring phrases like "a list that is part of the program 
and bad things could happen if we tried to change part of the program 
while running it", so I'd keep the changes in the examples (the ones I 
looked at look sensible), but remove most of the explanations. Moreso 
that they are using the phrases "mutable values" and "constant values". 
Some short explanation could say that it's a bad idea to modify a quoted 
form (and then reference "Self-Evaluating Forms").

I can try to make a patch, but at this point is would consist mostly of 
deletions.