Subject: bug#66756: 30.0.50; [PATCH] Improve discussion of 'let' in Elisp Introduction manual

From: Jim Porter <[email-masked]>
Date: Fri, 24 Nov 2023 13:46:55 -0800

On 11/24/2023 3:41 AM, Eli Zaretskii wrote:
> "During the execution" is probably a good idea, but "within the body
> of the expression" Does not seem to contrast with that, since it also
> holds for dynamic binding.

For "within the body of the expression", I wanted a phrase I could use 
near the beginning of this discussion, before we get into the 
differences of lexical vs dynamic binding. That way, I can refer back to 
it in the lexical/dynamic binding section and contrast it with the 
dynamic binding definition.

I've added some more explanation to it though, so hopefully that helps 
clarify things. I also reworked the description of dynamic binding to 
talk about how each variable has a stack of bindings. Hopefully this is 
clear enough; I think it's more straightforward than the previous one, 
since it uses a stack of papers on one's desk as a visual analogy to 
help drive the point home.

From 9800c1458ffa33780c2763dbd3013efad1b2dbd8 Mon Sep 17 00:00:00 2001
From: Jim Porter <[email-masked]>
Date: Wed, 25 Oct 2023 20:43:57 -0700
Subject: [PATCH] Introduce 'let' using lexical binding in the Lisp
 Introduction

* 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 (bug#66756).
---
 doc/lispintro/emacs-lisp-intro.texi | 157 +++++++++++++++++++++++-----
 1 file changed, 133 insertions(+), 24 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index c5b33ac5eaa..edcb41ed796 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
@@ -3602,24 +3603,22 @@ Prevent confusion
 @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.
-@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.)
+name outside the @code{let} expression (in computer science jargon, we
+call this @dfn{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}.)
+
+Another way to think about @code{let} is that it defines a special
+region in your code: within the body of the @code{let} expression, the
+variables you've named have their own local meaning.  Outside of the
+@code{let} body, they have other meanings (or they may not be defined
+at all).  In practice, 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.
+However, 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 +3778,114 @@ 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 @dfn{scope}).  For historical reasons, Emacs Lisp uses a form
+of variable binding called @dfn{dynamic binding} by default.  However,
+in this manual we discuss the preferred form of binding, called
+@dfn{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, when you create local variables with
+@code{let} under lexical binding, those variables are valid only
+within the body of the @code{let} expression.  In other parts of your
+code, they have other meanings, so if you call a function in the
+@code{let} body, that function would be unable to ``see'' the local
+variables you've created.
+
+Under dynamic binding, the rules are different: instead, when you use
+@code{let}, the local variables you've created are valid during
+execution of the let expression.  This means that, if your @code{let}
+expression calls a function, that function can see (and modify) these
+local variables.
+
+Another way to think about @code{let} when using dynamic binding is
+that every variable name has a ``stack'' of bindings, and whenever you
+use that variable's name, it refers to the binding on the top of the
+stack.  (You can imagine this like a stack of papers on your desk with
+the values written on them.)  When you bind a variable with
+@code{let}, it puts the new binding you've specified on the top of the
+stack, and then executes the @code{let} body.  Once the @code{let}
+body finishes, it takes that binding off of the stack, revealing the
+one it had (if any) before 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, see what happens in this code under lexical binding:
+
+@example
+;;; -*- lexical-binding: t -*-
+
+(setq x 0)
+
+(defun getx ()
+  x)
+
+(setq x 1)
+
+(let ((x 2))
+  (getx))
+     @result{} 1
+@end example
+
+@noindent
+Here, the result of @code{(getx)} is @code{1}.  Under lexical binding,
+@code{getx} doesn't see the value from our @code{let} expression.
+That's because the body of @code{getx} is outside of the body of our
+@code{let} expression.  Instead, @code{getx} looks for @code{x}
+elsewhere, and finds it at the global scope of our code.  When
+executing @code{getx}, the current global value of @code{x} is
+@code{1}, so that's what @code{getx} returns.
+
+If we use dynamic binding instead, the behavior is different:
+
+@example
+;;; -*- lexical-binding: nil -*-
+
+(setq x 0)
+
+(defun getx ()
+  x)
+
+(setq x 1)
+
+(let ((x 2))
+  (getx))
+     @result{} 2
+@end example
+
+@noident
+Now, the result of @code{(getx)} is @code{2}!  That's because under
+dynamic binding, when executing @code{getx}, the current binding for
+@code{x} is the one from our @code{let} binding.  This time,
+@code{getx} doesn't see the global value for @code{x}, since its
+binding is below the one from our @code{let} expression in the stack
+of bindings.
+
+(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 +9237,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 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}).  Second, 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.  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