From 9db675656ea76a401a792a711231766b3d7a87d2 Mon Sep 17 00:00:00 2001 From: Jim Porter Date: Wed, 25 Oct 2023 20:43:57 -0700 Subject: [PATCH] Introduce 'let' using lexical binding in the Lisp Introduction Bug#66756. * doc/lispintro/emacs-lisp-intro.texi (Prevent confusion): Rework the explanation to discuss how things work under lexical binding. (How let Binds Variables): Describe the differences between lexical and dynamic binding (including how to configure it). (defvar): Mention that 'defvar' declares variables as always dynamically-bound. --- doc/lispintro/emacs-lisp-intro.texi | 133 +++++++++++++++++++++++----- 1 file changed, 110 insertions(+), 23 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index c5b33ac5eaa..9a8b93fbd3e 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -3591,6 +3591,7 @@ let * Parts of let Expression:: * Sample let Expression:: * Uninitialized let Variables:: +* How let Binds Variables:: @end menu @ifnottex @@ -3601,25 +3602,22 @@ Prevent confusion @cindex @samp{local variable} defined @cindex @samp{variable, local}, defined The @code{let} special form prevents confusion. @code{let} creates a -name for a @dfn{local variable} that overshadows any use of the same -name outside the @code{let} expression. This is like understanding -that whenever your host refers to ``the house'', he means his house, not -yours. (Symbols used in argument lists work the same way. +name for a @dfn{local variable} that overrides any use of the same +name outside the @code{let} expression (in computer science jargon, we +call this ``binding'' the variable). This is like understanding that +in your host's home, whenever he refers to ``the house'', he means his +house, not yours. (Symbols used in argument lists work the same way. @xref{defun, , The @code{defun} Macro}.) -Local variables created by a @code{let} expression retain their value -@emph{only} within the @code{let} expression itself (and within -expressions called within the @code{let} expression); the local -variables have no effect outside the @code{let} expression. - -Another way to think about @code{let} is that it is like a @code{setq} -that is temporary and local. The values set by @code{let} are -automatically undone when the @code{let} is finished. The setting -only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say the binding of -a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, the default scoping is dynamic, not lexical. (The -non-default lexical binding is not discussed in this manual.) +Another way to think about @code{let} is that it defines a place in +your code where the variables you named have their own local meaning. +Outside of the @code{let} body, they have another meaning (or they may +not be defined at all). This means that inside the @code{let} body, +calling @code{setq} for a variable named by the @code{let} expression +will set the value of the @emph{local} variable of that name. This +also means that outside of the @code{let} body, calling @code{setq} +for a variable named by the @code{let} expression will @emph{not} +affect that local variable. @code{let} can create more than one variable at once. Also, @code{let} gives each variable it creates an initial value, either a @@ -3779,6 +3777,93 @@ Uninitialized let Variables @samp{%s}.) The four variables as a group are put into a list to delimit them from the body of the @code{let}. +@node How let Binds Variables +@subsection How @code{let} Binds Variables +@cindex Lexical binding +@cindex Binding, lexical +@cindex Dynamic binding +@cindex Binding, dynamic + +Emacs Lisp supports two different ways of binding variable names to +their values. These ways affect the parts of your program where a +particular binding is valid (in computer science jargon, we call these +parts a ``scope''). For historical reasons, Emacs Lisp uses a form of +variable binding called ``dynamic binding'' by default. However, in +this manual we discuss the preferred form of binding, called ``lexical +binding'', unless otherwise noted (in the future, the Emacs +maintainers plan to change the default to lexical binding). If you +have programmed in other languages before, you're likely already +familiar with how lexical binding behaves. + +In order to use lexical binding in a program, you should add this to +the first line of your Emacs Lisp file: + +@example +;;; -*- lexical-binding: t -*- +@end example + +For more information about this, @pxref{Selecting Lisp Dialect, , , +elisp, The Emacs Lisp Reference Manual}. + +As we discussed before, under lexical binding, @code{let} defines a +@emph{place} in your code where the variables have their own local +meaning. Under dynamic binding, the rules are different: instead, you +are defining a @emph{time} in your code when the variables have their +own local meaning. + +Another way to think about @code{let} when using dynamic binding is +that it is like a @code{setq} that is temporary and local. The values +set by @code{let} are automatically undone when the @code{let} is +finished. The setting only affects expressions that are inside the +bounds of the @code{let} expression. + +In some cases, both lexical and dynamic binding behave identically. +However, in other cases, they can change the meaning of your program. +For example, under lexical binding, if you call a function inside of a +@code{let} body, that function's body would be unable to ``see'' (or +modify) the value of a local variable from the @code{let} expression: + +@example +;;; -*- lexical-binding: t -*- + +(setq x 1) + +(defun getx () + x) + +(let ((x 2)) + (getx)) + @result{} 1 +@end example + +@noindent +If we use dynamic binding instead, the behavior is different: + +@example +;;; -*- lexical-binding: nil -*- + +(setq x 1) + +(defun getx () + x) + +(let ((x 2)) + (getx)) + @result{} 2 +@end example + +Now, the result of @samp{(getx)} is @samp{2}! That's because under +dynamic binding, when @code{getx} looks for the value of @code{x}, it +sees the value we set in our @code{let} expression. In other words, +the call to @code{getx} happens during the @emph{time} when our +@code{let} expression is active. Under lexical binding, @code{getx} +doesn't see the value from our @code{let} expression. That's because +it happens in a different @emph{place} than the @code{let} body. + +(Some variables are also ``special'', and they are always dynamically +bound even when @code{lexical-binding} is @code{t}. @xref{defvar, , +Initializing a Variable with @code{defvar}}.) + @node if @section The @code{if} Special Form @findex if @@ -9130,12 +9215,14 @@ defvar given an initial value by using the @code{defvar} special form. The name comes from ``define variable''. -The @code{defvar} special form is similar to @code{setq} in that it sets -the value of a variable. It is unlike @code{setq} in two ways: first, -it only sets the value of the variable if the variable does not already -have a value. If the variable already has a value, @code{defvar} does -not override the existing value. Second, @code{defvar} has a -documentation string. +The @code{defvar} special form is similar to @code{setq} in that it +sets the value of a variable. It is unlike @code{setq} in three ways: +first, it only sets the value of the variable if the variable does not +already have a value. If the variable already has a value, +@code{defvar} does not override the existing value. Second, it marks +the variable as ``special'' so that it is always dynamically bound, +even when @code{lexical-binding} is @code{t} (@pxref{How let Binds +Variables}). Third, @code{defvar} has a documentation string. (There is a related macro, @code{defcustom}, designed for variables that people customize. It has more features than @code{defvar}. -- 2.25.1