[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110881: cl.texi flet clarification

[Glenn Morris]

------------------------------------------------------------
revno: 110881
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Thu 2012-11-15 23:43:24 -0800
message:
  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.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi
  etc/NEWS

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-11-13 08:16:58 +0000
+++ b/doc/misc/ChangeLog        2012-11-16 07:43:24 +0000
@@ -1,3 +1,8 @@
+2012-11-16  Glenn Morris  <address@hidden>
+
+       * cl.texi (Function Bindings): Clarify that cl-flet is lexical.
+       (Obsolete Macros): Move example here from Function Bindings.
+
 2012-11-13  Glenn Morris  <address@hidden>
 
        * erc.texi: Use @code{nil} rather than just "nil".

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-11-07 22:23:34 +0000
+++ b/doc/misc/cl.texi  2012-11-16 07:43:24 +0000
@@ -1292,28 +1292,14 @@
 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
address@hidden  For example,
-
address@hidden
-(cl-flet ((message (&rest args) (push args saved-msgs)))
-    (do-something))
address@hidden 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
address@hidden 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 @@
 @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 (address@hidden) address@hidden
@@ -4863,6 +4850,25 @@
 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
address@hidden  For example,
+
address@hidden
+(flet ((message (&rest args) (push args saved-msgs)))
+  (do-something))
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-15 07:30:46 +0000
+++ b/etc/NEWS  2012-11-16 07:43:24 +0000
@@ -320,6 +320,8 @@
 +++
 *** `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'.