From 400ff5cd195e81204edd9c69fa1b8bc3cb66b42d Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Wed, 22 Apr 2020 10:42:09 -0700 Subject: [PATCH] Improve wording about constants MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks to Štěpán Němec and Drew Adams for reviews of recent changes. * doc/lispref/eval.texi (Quoting): Give an example. * doc/lispref/lists.texi (Association Lists): Simplify example code. * doc/lispref/objects.texi (Lisp Data Types) (Constants and Mutability): Clarify wording. --- doc/lispref/eval.texi | 6 ++++++ doc/lispref/lists.texi | 7 +++---- doc/lispref/objects.texi | 21 ++++++++++++++------- 3 files changed, 23 insertions(+), 11 deletions(-) diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 021604c514..baddce4d9c 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -606,6 +606,12 @@ Here are some examples of expressions that use @code{quote}: @end group @end example + Although the expressions @code{(list '+ 1 2)} and @code{'(+ 1 2)} +both yield lists equal to @code{(+ 1 2)}, the former yields a +freshly-minted mutable list whereas the latter yields a constant list +built from conses that may be shared with other constants. +@xref{Constants and Mutability}. + Other quoting constructs include @code{function} (@pxref{Anonymous Functions}), which causes an anonymous lambda expression written in Lisp to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 1125af7bec..ea44e01f48 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1625,10 +1625,9 @@ keys may not be symbols: '(("simple leaves" . oak) ("compound leaves" . horsechestnut))) -;; @r{The @code{copy-sequence} means the keys are not @code{eq}.} -(assq (copy-sequence "simple leaves") leaves) - @result{} nil -(assoc (copy-sequence "simple leaves") leaves) +(assq "simple leaves" leaves) + @result{} @r{Unspecified; might be @code{nil} or non-@code{nil}.} +(assoc "simple leaves" leaves) @result{} ("simple leaves" . oak) @end smallexample @end defun diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index abd258eb53..1eda94ab63 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -46,7 +46,7 @@ you store in it, type and all. (Actually, a small number of Emacs Lisp variables can only take on values of a certain type. @xref{Variables with Restricted Values}.) - Some Lisp objects are @dfn{constant}: their values never change. + Some Lisp objects are @dfn{constant}: their values should never change. Others are @dfn{mutable}: their values can be changed via destructive operations that involve side effects. @@ -2384,22 +2384,28 @@ that for two strings to be equal, they have the same text properties. @cindex constants @cindex mutable objects - Some Lisp objects are constant: their values never change. + Some Lisp objects are constant: their values should never change +during a single execution of Emacs running well-behaved Lisp code. For example, you can create a new integer by calculating one, but you cannot modify the value of an existing integer. - Other Lisp objects are mutable: their values can be changed + Other Lisp objects are mutable: it is safe to change their values via destructive operations involving side effects. For example, an existing marker can be changed by moving the marker to point to somewhere else. - Although numbers are always constants and markers are always + Although all numbers are constants and all markers are mutable, some types contain both constant and mutable members. These types include conses, vectors, strings, and symbols. For example, the string literal @code{"aaa"} yields a constant string, whereas the function call @code{(make-string 3 ?a)} yields a mutable string that can be changed via later calls to @code{aset}. + A mutable object can become constant if it is passed to the +@code{eval} function, because a program should not modify an object +that is being evaluated. The reverse does not occur: constant objects +should stay constant. + Trying to modify a constant variable signals an error (@pxref{Constant Variables}). A program should not attempt to modify other types of constants because the @@ -2407,9 +2413,10 @@ resulting behavior is undefined: the Lisp interpreter might or might not detect the error, and if it does not detect the error the interpreter can behave unpredictably thereafter. Another way to put this is that although mutable objects are safe to change and constant -symbols reliably reject attempts to change them, other constants are -not safely mutable: if you try to change one your program might -behave as you expect but it might crash or worse. This problem occurs +variables reliably prevent attempts to change them, other constants +are not safely mutable: if a misbehaving program tries to change such a +constant then the constant's value might actually change, or the +program might crash or worse. This problem occurs with types that have both constant and mutable members, and that have mutators like @code{setcar} and @code{aset} that are valid on mutable objects but hazardous on constants. -- 2.17.1