[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r110697: Start moving some cl.texi fe
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r110697: Start moving some cl.texi features to an Obsolete appendix |
Date: |
Sat, 27 Oct 2012 18:55:40 -0700 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110697
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2012-10-27 18:55:40 -0700
message:
Start moving some cl.texi features to an Obsolete appendix
* doc/misc/cl.texi (Lexical Bindings): Move to appendix of obsolete features.
(Porting Common Lisp): Emacs Lisp can do true lexical binding now.
(Obsolete Features): New appendix. Move Lexical Bindings here.
modified:
doc/misc/ChangeLog
doc/misc/cl.texi
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2012-10-27 22:54:53 +0000
+++ b/doc/misc/ChangeLog 2012-10-28 01:55:40 +0000
@@ -1,3 +1,9 @@
+2012-10-28 Glenn Morris <address@hidden>
+
+ * cl.texi (Lexical Bindings): Move to appendix of obsolete features.
+ (Porting Common Lisp): Emacs Lisp can do true lexical binding now.
+ (Obsolete Features): New appendix. Move Lexical Bindings here.
+
2012-10-27 Glenn Morris <address@hidden>
* cl.texi: Use defmac for macros rather than defspec.
=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi 2012-10-27 22:54:53 +0000
+++ b/doc/misc/cl.texi 2012-10-28 01:55:40 +0000
@@ -70,6 +70,7 @@
* Efficiency Concerns:: Hints and techniques.
* Common Lisp Compatibility:: All known differences with Steele.
* Porting Common Lisp:: Hints for porting Common Lisp code.
+* Obsolete Features:: Obsolete features.
* GNU Free Documentation License:: The license for this documentation.
* Function Index::
@@ -210,7 +211,6 @@
by @code{cl--}. Here is a complete list of functions prefixed by
@code{cl-} that were not taken from Common Lisp:
address@hidden FIXME lexical-let lexical-let*
@example
cl-callf cl-callf2 cl-defsubst
cl-floatp-safe cl-letf cl-letf*
@@ -806,12 +806,11 @@
constructs.
@c FIXME
address@hidden lexical-let is obsolete; flet is not cl-flet.
address@hidden values is not cl-values.
address@hidden flet is not cl-flet, values is not cl-values.
@menu
* Assignment:: The @code{cl-psetq} form.
* Generalized Variables:: Extensions to generalized variables.
-* Variable Bindings:: @code{cl-progv}, @code{lexical-let}, @code{flet},
@code{cl-macrolet}.
+* Variable Bindings:: @code{cl-progv}, @code{flet}, @code{cl-macrolet}.
* Conditionals:: @code{cl-case}, @code{cl-typecase}.
* Blocks and Exits:: @code{cl-block}, @code{cl-return},
@code{cl-return-from}.
* Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist},
@code{cl-do-symbols}.
@@ -1422,7 +1421,6 @@
@menu
* Dynamic Bindings:: The @code{cl-progv} form.
-* Lexical Bindings:: @code{lexical-let} and lexical closures.
* Function Bindings:: @code{flet} and @code{labels}.
* Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
@end menu
@@ -1447,120 +1445,6 @@
are ignored.
@end defmac
address@hidden Lexical Bindings
address@hidden Lexical Bindings
-
address@hidden
-The @code{CL} package defines the following macro which
-more closely follows the Common Lisp @code{let} form:
-
address@hidden lexical-let (address@hidden) address@hidden
-This form is exactly like @code{let} except that the bindings it
-establishes are purely lexical. Lexical bindings are similar to
-local variables in a language like C: Only the code physically
-within the body of the @code{lexical-let} (after macro expansion)
-may refer to the bound variables.
-
address@hidden
-(setq a 5)
-(defun foo (b) (+ a b))
-(let ((a 2)) (foo a))
- @result{} 4
-(lexical-let ((a 2)) (foo a))
- @result{} 7
address@hidden example
-
address@hidden
-In this example, a regular @code{let} binding of @code{a} actually
-makes a temporary change to the global variable @code{a}, so @code{foo}
-is able to see the binding of @code{a} to 2. But @code{lexical-let}
-actually creates a distinct local variable @code{a} for use within its
-body, without any effect on the global variable of the same name.
-
-The most important use of lexical bindings is to create @dfn{closures}.
-A closure is a function object that refers to an outside lexical
-variable. For example:
-
address@hidden
-(defun make-adder (n)
- (lexical-let ((n n))
- (function (lambda (m) (+ n m)))))
-(setq add17 (make-adder 17))
-(funcall add17 4)
- @result{} 21
address@hidden example
-
address@hidden
-The call @code{(make-adder 17)} returns a function object which adds
-17 to its argument. If @code{let} had been used instead of
address@hidden, the function object would have referred to the
-global @code{n}, which would have been bound to 17 only during the
-call to @code{make-adder} itself.
-
address@hidden
-(defun make-counter ()
- (lexical-let ((n 0))
- (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
-(setq count-1 (make-counter))
-(funcall count-1 3)
- @result{} 3
-(funcall count-1 14)
- @result{} 17
-(setq count-2 (make-counter))
-(funcall count-2 5)
- @result{} 5
-(funcall count-1 2)
- @result{} 19
-(funcall count-2)
- @result{} 6
address@hidden example
-
address@hidden
-Here we see that each call to @code{make-counter} creates a distinct
-local variable @code{n}, which serves as a private counter for the
-function object that is returned.
-
-Closed-over lexical variables persist until the last reference to
-them goes away, just like all other Lisp objects. For example,
address@hidden refers to a function object which refers to an
-instance of the variable @code{n}; this is the only reference
-to that variable, so after @code{(setq count-2 nil)} the garbage
-collector would be able to delete this instance of @code{n}.
-Of course, if a @code{lexical-let} does not actually create any
-closures, then the lexical variables are free as soon as the
address@hidden returns.
-
-Many closures are used only during the extent of the bindings they
-refer to; these are known as ``downward funargs'' in Lisp parlance.
-When a closure is used in this way, regular Emacs Lisp dynamic
-bindings suffice and will be more efficient than @code{lexical-let}
-closures:
-
address@hidden
-(defun add-to-list (x list)
- (mapcar (lambda (y) (+ x y))) list)
-(add-to-list 7 '(1 2 5))
- @result{} (8 9 12)
address@hidden example
-
address@hidden
-Since this lambda is only used while @code{x} is still bound,
-it is not necessary to make a true closure out of it.
-
-You can use @code{defun} or @code{flet} inside a @code{lexical-let}
-to create a named closure. If several closures are created in the
-body of a single @code{lexical-let}, they all close over the same
-instance of the lexical variable.
-
-The @code{lexical-let} form is an extension to Common Lisp. In
-true Common Lisp, all bindings are lexical unless declared otherwise.
address@hidden defmac
-
address@hidden lexical-let* (address@hidden) address@hidden
-This form is just like @code{lexical-let}, except that the bindings
-are made sequentially in the manner of @code{let*}.
address@hidden defmac
-
@node Function Bindings
@subsection Function Bindings
@@ -1650,6 +1534,10 @@
and macro-expander forms). The macro is defined accordingly for
use within the body of the @code{cl-macrolet}.
address@hidden FIXME this should be modified to say ``even when lexical-binding
address@hidden is code{nil}'', but is that true? The doc of cl-macrolet just
address@hidden refers us to cl-flet, which refers to cl-labels, which says that
it
address@hidden behaves differently according to whether l-b is true or not.
Because of the nature of macros, @code{cl-macrolet} is lexically
scoped even in Emacs Lisp: The @code{cl-macrolet} binding will
affect only calls that appear physically within the body
@@ -1678,8 +1566,10 @@
Likewise, a @code{let} or @code{let*} binding a symbol macro is
treated like a @code{letf} or @code{cl-letf*}. This differs from true
address@hidden FIXME does it work like this in Emacs with lexical-binding = t?
Common Lisp, where the rules of lexical scoping cause a @code{let}
binding to shadow a @code{cl-symbol-macrolet} binding. In this package,
address@hidden FIXME obsolete.
only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
macro.
@@ -4861,19 +4751,15 @@
@item
Lexical scoping. In Common Lisp, function arguments and @code{let}
-bindings apply only to references physically within their bodies
-(or within macro expansions in their bodies). Emacs Lisp, by
-contrast, uses @dfn{dynamic scoping} wherein a binding to a
-variable is visible even inside functions called from the body.
-
-Variables in Common Lisp can be made dynamically scoped by
-declaring them @code{special} or using @code{defvar}. In Emacs
-Lisp it is as if all variables were declared @code{special}.
-
-Often you can use code that was written for lexical scoping
-even in a dynamically scoped Lisp, but not always. Here is
-an example of a Common Lisp code fragment that would fail in
-Emacs Lisp:
+bindings apply only to references physically within their bodies (or
+within macro expansions in their bodies). Traditionally, Emacs Lisp
+uses @dfn{dynamic scoping} wherein a binding to a variable is visible
+even inside functions called from the body. Lexical binding is
+available since Emacs 24.1, so be sure to set @code{lexical-binding}
+to @code{t} if you need to emulate this aspect of Common Lisp.
+
+Here is an example of a Common Lisp code fragment that would fail in
+Emacs Lisp if @code{lexical-binding} were set to @code{nil}:
@example
(defun map-odd-elements (func list)
@@ -4886,20 +4772,16 @@
@end example
@noindent
-In Common Lisp, the two functions' usages of @code{x} are completely
-independent. In Emacs Lisp, the binding to @code{x} made by
address@hidden will have been hidden by the binding
-in @code{map-odd-elements} by the time the @code{(+ a x)} function
-is called.
-
-(This package avoids such problems in its own mapping functions
-by using names like @code{cl--x} instead of @code{x} internally;
-as long as you don't use this prefix for your own
-variables no collision can occur.)
-
address@hidden Bindings}, for a description of the @code{lexical-let}
-form which establishes a Common Lisp-style lexical binding, and some
-examples of how it differs from Emacs's regular @code{let}.
+With lexical binding, the two functions' usages of @code{x} are
+completely independent. With dynamic binding, the binding to @code{x}
+made by @code{add-odd-elements} will have been hidden by the binding
+in @code{map-odd-elements} by the time the @code{(+ a x)} function is
+called.
+
+Internally, this package uses lexical binding so that such problems do
+not occur. @xref{Lexical Bindings}, for a description of the obsolete
address@hidden form that emulates a Common Lisp-style lexical
+binding when dynamic binding is in use.
@item
Reader macros. Common Lisp includes a second type of macro that
@@ -5039,6 +4921,133 @@
recursion.
@end itemize
address@hidden Obsolete Features
address@hidden Obsolete Features
+
+This section describes some features of the package that are obsolete
+and should not be used in new code. They are only provided by the old
address@hidden entry point, not by the newer @file{cl-lib.el}.
+
address@hidden
+* Lexical Bindings:: An approximation of lexical binding.
address@hidden menu
+
address@hidden Lexical Bindings
address@hidden Lexical Bindings
+
+The following macros are extensions to Common Lisp, where all bindings
+are lexical unless declared otherwise. These features are likewise
+obsolete since the introduction of true lexical binding in Emacs 24.1.
+
address@hidden lexical-let (address@hidden) address@hidden
+This form is exactly like @code{let} except that the bindings it
+establishes are purely lexical.
address@hidden defmac
+
address@hidden FIXME remove this and refer to elisp manual.
address@hidden Maybe merge some stuff from here to there?
address@hidden
+Lexical bindings are similar to local variables in a language like C:
+Only the code physically within the body of the @code{lexical-let}
+(after macro expansion) may refer to the bound variables.
+
address@hidden
+(setq a 5)
+(defun foo (b) (+ a b))
+(let ((a 2)) (foo a))
+ @result{} 4
+(lexical-let ((a 2)) (foo a))
+ @result{} 7
address@hidden example
+
address@hidden
+In this example, a regular @code{let} binding of @code{a} actually
+makes a temporary change to the global variable @code{a}, so @code{foo}
+is able to see the binding of @code{a} to 2. But @code{lexical-let}
+actually creates a distinct local variable @code{a} for use within its
+body, without any effect on the global variable of the same name.
+
+The most important use of lexical bindings is to create @dfn{closures}.
+A closure is a function object that refers to an outside lexical
+variable. For example:
+
address@hidden
+(defun make-adder (n)
+ (lexical-let ((n n))
+ (function (lambda (m) (+ n m)))))
+(setq add17 (make-adder 17))
+(funcall add17 4)
+ @result{} 21
address@hidden example
+
address@hidden
+The call @code{(make-adder 17)} returns a function object which adds
+17 to its argument. If @code{let} had been used instead of
address@hidden, the function object would have referred to the
+global @code{n}, which would have been bound to 17 only during the
+call to @code{make-adder} itself.
+
address@hidden
+(defun make-counter ()
+ (lexical-let ((n 0))
+ (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
+(setq count-1 (make-counter))
+(funcall count-1 3)
+ @result{} 3
+(funcall count-1 14)
+ @result{} 17
+(setq count-2 (make-counter))
+(funcall count-2 5)
+ @result{} 5
+(funcall count-1 2)
+ @result{} 19
+(funcall count-2)
+ @result{} 6
address@hidden example
+
address@hidden
+Here we see that each call to @code{make-counter} creates a distinct
+local variable @code{n}, which serves as a private counter for the
+function object that is returned.
+
+Closed-over lexical variables persist until the last reference to
+them goes away, just like all other Lisp objects. For example,
address@hidden refers to a function object which refers to an
+instance of the variable @code{n}; this is the only reference
+to that variable, so after @code{(setq count-2 nil)} the garbage
+collector would be able to delete this instance of @code{n}.
+Of course, if a @code{lexical-let} does not actually create any
+closures, then the lexical variables are free as soon as the
address@hidden returns.
+
+Many closures are used only during the extent of the bindings they
+refer to; these are known as ``downward funargs'' in Lisp parlance.
+When a closure is used in this way, regular Emacs Lisp dynamic
+bindings suffice and will be more efficient than @code{lexical-let}
+closures:
+
address@hidden
+(defun add-to-list (x list)
+ (mapcar (lambda (y) (+ x y))) list)
+(add-to-list 7 '(1 2 5))
+ @result{} (8 9 12)
address@hidden example
+
address@hidden
+Since this lambda is only used while @code{x} is still bound,
+it is not necessary to make a true closure out of it.
+
+You can use @code{defun} or @code{flet} inside a @code{lexical-let}
+to create a named closure. If several closures are created in the
+body of a single @code{lexical-let}, they all close over the same
+instance of the lexical variable.
+
address@hidden lexical-let* (address@hidden) address@hidden
+This form is just like @code{lexical-let}, except that the bindings
+are made sequentially in the manner of @code{let*}.
address@hidden defmac
+
+
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r110697: Start moving some cl.texi features to an Obsolete appendix,
Glenn Morris <=