From c04ac8a3191820d37e7858b7ca4e31cf04808cc3 Mon Sep 17 00:00:00 2001 From: Philipp Stephani Date: Fri, 23 Dec 2016 13:14:55 +0100 Subject: Document that variable binding order is unspecified * doc/lispref/variables.texi (Local Variables): * cl.texi (Modify Macros): Document that binding order in 'let' and 'cl-letf' is unspecified. --- doc/lispref/variables.texi | 12 ++++++++++++ doc/misc/cl.texi | 5 +++++ 2 files changed, 17 insertions(+) (limited to 'doc') diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index a2d64815d94..ba31f856369 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -221,6 +221,18 @@ Here is an example of this: @code{z} is bound to the old value of @result{} (1 2) @end group @end example + +On the other hand, the order of @emph{bindings} is unspecified: in the +following example, either 1 or 2 might be printed. + +@example +(let ((x 1) + (x 2)) + (print x)) +@end example + +Therefore, avoid binding a variable more than once in a single +@code{let} form. @end defspec @defspec let* (bindings@dots{}) forms@dots{} diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index c62fa727c10..75a83602fa3 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1179,6 +1179,11 @@ behavior. (@code{point} and @code{point-marker} are equivalent as @code{setf} places; each will accept either an integer or a marker as the stored value.) +Like in the case of @code{let}, the @var{value} forms are evaluated in +the order they appear, but the order of bindings is unspecified. +Therefore, avoid binding the same @var{place} more than once in a +single @code{cl-letf} form. + Since generalized variables look like lists, @code{let}'s shorthand of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would be ambiguous in @code{cl-letf} and is not allowed. -- cgit v1.2.1 From f69bd7954f113719bb0e46e143231744c80bef34 Mon Sep 17 00:00:00 2001 From: Philipp Stephani Date: Sun, 18 Dec 2016 22:18:01 +0100 Subject: Clarify usage of 'ediff-cleanup-hook' (Bug#24675) * doc/misc/ediff.texi (Hooks): Clarify usage of 'ediff-cleanup-hook' --- doc/misc/ediff.texi | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 376aaeea46e..896a6041e86 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1247,9 +1247,14 @@ merged (see @code{ediff-cleanup-hook}, below). @vindex ediff-cleanup-hook This hook is run just before @code{ediff-quit-hook}. This is a good place to do various cleanups, such as deleting the variant buffers. -Ediff provides a function, @code{ediff-janitor}, as one such possible -hook, which you can add to @code{ediff-cleanup-hook} with -@code{add-hook}. +Ediff provides a helper function, @code{ediff-janitor}, that you can +invoke from a private hook function. For example: + +@example +(defun my-ediff-janitor () + (ediff-janitor nil nil)) +(add-hook 'ediff-cleanup-hook #'my-ediff-janitor) +@end example @findex ediff-janitor This function kills buffers A, B, and, possibly, C, if these buffers aren't -- cgit v1.2.1 From d7973e808d54f1adf5224589c5cf770bb17453d2 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 26 Dec 2016 19:10:49 +0200 Subject: Document 'default-toplevel-value' and 'set-default-toplevel-value' * doc/lispref/variables.texi (Default Value): Document 'default-toplevel-value' and 'set-default-toplevel-value'. --- doc/lispref/variables.texi | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'doc') diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index ba31f856369..e231cbdfec1 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1580,6 +1580,44 @@ an ordinary evaluated argument. @end example @end defun + A variable can be let-bound (@pxref{Local Variables}) to a +non-default value; in that case, @code{default-value} will return the +value from that binding, not the global value, and @code{set-default} +will be prevented from setting the global value. The following two +functions allow to reference the global value even if it's masked by a +let-binding. + +@cindex top-level default value +@defun default-toplevel-value symbol +This function returns the @dfn{top-level} default value of +@var{symbol}, which is its value outside of any let-binding. +@end defun + +@example +@group +(defvar variable 'global-value) + @result{} variable +@end group +@group +(let ((variable 'let-binding)) + (default-value 'variable)) + @result{} let-binding +@end group +@group +(let ((variable 'let-binding)) + (default-toplevel-value 'variable)) + @result{} global-value +@end group +@end example + +@defun set-default-toplevel-value symbol value +This function sets the top-level default value of @var{symbol} to the +specified @var{value}. This comes in handy when you want to set the +global value of @var{symbol} regardless of whether your code runs in +the context of @var{symbol}'s let-binding. +@end defun + + @node File Local Variables @section File Local Variables @cindex file local variables -- cgit v1.2.1 From 697167b5432a89db009238cf5cbddc61e69ad339 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 27 Dec 2016 09:10:30 +0200 Subject: ; Improve wording of previous change in variables.texi * doc/lispref/variables.texi (Default Value): Improve wording of last change. --- doc/lispref/variables.texi | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index e231cbdfec1..887643196cc 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1580,12 +1580,13 @@ an ordinary evaluated argument. @end example @end defun - A variable can be let-bound (@pxref{Local Variables}) to a -non-default value; in that case, @code{default-value} will return the -value from that binding, not the global value, and @code{set-default} -will be prevented from setting the global value. The following two -functions allow to reference the global value even if it's masked by a -let-binding. + A variable can be let-bound (@pxref{Local Variables}) to a value. +This makes its global value shadowed by the binding; +@code{default-value} will then return the value from that binding, not +the global value, and @code{set-default} will be prevented from +setting the global value (it will change the let-bound value instead). +The following two functions allow to reference the global value even +if it's shadowed by a let-binding. @cindex top-level default value @defun default-toplevel-value symbol -- cgit v1.2.1