From e8693c969a822ad8192f2410fbf9a949a723ddce Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Thu, 15 Nov 2012 23:43:24 -0800 Subject: [PATCH] cl.texi flet clarification * doc/misc/cl.texi (Function Bindings): Clarify that cl-flet is lexical. (Obsolete Macros): Move example here from Function Bindings. * etc/NEWS: Related edit. --- doc/misc/ChangeLog | 5 +++++ doc/misc/cl.texi | 48 ++++++++++++++++++++++++++-------------------- etc/NEWS | 2 ++ 3 files changed, 34 insertions(+), 21 deletions(-) diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 07f38d15dd9..4a3c8778e88 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,8 @@ +2012-11-16 Glenn Morris + + * cl.texi (Function Bindings): Clarify that cl-flet is lexical. + (Obsolete Macros): Move example here from Function Bindings. + 2012-11-13 Glenn Morris * erc.texi: Use @code{nil} rather than just "nil". diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index a50be1027f3..beefa3e9c40 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1292,28 +1292,14 @@ it were a @code{cl-defun} form. The function @var{name} is defined accordingly for the duration of the body of the @code{cl-flet}; then the old function definition, or lack thereof, is restored. -You can use @code{cl-flet} to disable or modify the behavior of a -function in a temporary fashion. (Compare this with the idea -of advising functions. +You can use @code{cl-flet} to disable or modify the behavior of +functions (including Emacs primitives) in a temporary, localized fashion. +(Compare this with the idea of advising functions. @xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.) -This will even work on Emacs primitives, although note that some calls -to primitive functions internal to Emacs are made without going -through the symbol's function cell, and so will not be affected by -@code{cl-flet}. For example, - -@example -(cl-flet ((message (&rest args) (push args saved-msgs))) - (do-something)) -@end example -This code attempts to replace the built-in function @code{message} -with a function that simply saves the messages in a list rather -than displaying them. The original definition of @code{message} -will be restored after @code{do-something} exits. This code will -work fine on messages generated by other Lisp code, but messages -generated directly inside Emacs will not be caught since they make -direct C-language calls to the message routines rather than going -through the Lisp @code{message} function. +The bindings are lexical in scope. This means that all references to +the named functions must appear physically within the body of the +@code{cl-flet} form. Functions defined by @code{cl-flet} may use the full Common Lisp argument notation supported by @code{cl-defun}; also, the function @@ -1321,7 +1307,8 @@ body is enclosed in an implicit block as if by @code{cl-defun}. @xref{Program Structure}. Note that the @file{cl.el} version of this macro behaves slightly -differently. @xref{Obsolete Macros}. +differently. In particular, its binding is dynamic rather than +lexical. @xref{Obsolete Macros}. @end defmac @defmac cl-labels (bindings@dots{}) forms@dots{} @@ -4863,6 +4850,25 @@ time before Emacs had lexical binding). The result is that @code{flet} affects indirect calls to a function as well as calls directly inside the @code{flet} form itself. +This will even work on Emacs primitives, although note that some calls +to primitive functions internal to Emacs are made without going +through the symbol's function cell, and so will not be affected by +@code{flet}. For example, + +@example +(flet ((message (&rest args) (push args saved-msgs))) + (do-something)) +@end example + +This code attempts to replace the built-in function @code{message} +with a function that simply saves the messages in a list rather +than displaying them. The original definition of @code{message} +will be restored after @code{do-something} exits. This code will +work fine on messages generated by other Lisp code, but messages +generated directly inside Emacs will not be caught since they make +direct C-language calls to the message routines rather than going +through the Lisp @code{message} function. + @c Bug#411. Note that many primitives (e.g.@: @code{+}) have special byte-compile handling. Attempts to redefine such functions using @code{flet} will diff --git a/etc/NEWS b/etc/NEWS index b69240e081a..ba6dc68d72c 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -320,6 +320,8 @@ provide the old non-prefixed names. Some exceptions are listed below. +++ *** `cl-flet' is not like `flet' (which is deprecated). Instead it obeys the behavior of Common-Lisp's `flet'. +In particular, in cl-flet function definitions are lexically scoped, +whereas in flet the scoping is dynamic. +++ *** `cl-labels' is slightly different from `labels'. -- 2.39.2