From: Jim Porter <jporterbugs@gmail.com>
To: rms@gnu.org
Cc: eliz@gnu.org, 66756@debbugs.gnu.org
Subject: bug#66756: 30.0.50; [PATCH] Improve discussion of 'let' in Elisp Introduction manual
Date: Sat, 18 Nov 2023 21:25:42 -0800 [thread overview]
Message-ID: <381836df-c16f-b3e7-d0c4-473290e165de@gmail.com> (raw)
In-Reply-To: <E1r4YeF-0001fe-Ex@fencepost.gnu.org>
[-- Attachment #1: Type: text/plain, Size: 1544 bytes --]
On 11/18/2023 7:39 PM, Richard Stallman wrote:
> > +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'' (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}.
>
> Do we want to change the default some day to lexical binding:? If so,
> we should say so somewhere in this manual -- perhaps here, perhaps
> elsewhere,
I believe that's the goal, yes. I've added a note that the maintainers
eventually plan on making lexical binding the default.
> > +If we instead change @code{lexical-binding} to have a value of
> > +@code{nil}, we will get a different result here.
>
> "Get a different result" is vague -- it would be clearer if it said
> concretely what will happen.
>
> I suggest you show the dynamci situation in the same way you show the lexical
> situation. That will help people compare the two.
Done. I've also expanded the prose explanation at the end in order to
re-emphasize the differences between the two.
[-- Attachment #2: 0001-Introduce-let-using-lexical-binding-in-the-Lisp-Intr.patch --]
[-- Type: text/plain, Size: 6590 bytes --]
From f805ebf65dc218c7ae63251a357a4deaaf45d752 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
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).
---
doc/lispintro/emacs-lisp-intro.texi | 115 ++++++++++++++++++++++++----
1 file changed, 98 insertions(+), 17 deletions(-)
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index c5b33ac5eaa..554ba4a7560 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,89 @@ 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 primarily 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.
+
@node if
@section The @code{if} Special Form
@findex if
--
2.25.1
next prev parent reply other threads:[~2023-11-19 5:25 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-10-26 5:54 bug#66756: 30.0.50; [PATCH] Improve discussion of 'let' in Elisp Introduction manual Jim Porter
2023-10-26 18:30 ` Jim Porter
2023-10-29 16:38 ` Richard Stallman
2023-10-29 17:18 ` Drew Adams
2023-11-18 2:09 ` Jim Porter
2023-11-19 3:39 ` Richard Stallman
2023-11-19 5:25 ` Jim Porter [this message]
2023-11-19 5:30 ` Jim Porter
2023-11-19 8:38 ` Michael Albinus
2023-11-19 20:17 ` Jim Porter
2023-11-19 23:05 ` Jim Porter
2023-11-20 13:28 ` Michael Albinus
2023-11-23 2:57 ` Richard Stallman
2023-11-23 21:04 ` Jim Porter
2023-11-24 7:06 ` Eli Zaretskii
2023-11-24 9:01 ` Jim Porter
2023-11-24 11:41 ` Eli Zaretskii
2023-11-24 21:46 ` Jim Porter
2023-11-25 7:51 ` Eli Zaretskii
2023-11-30 21:03 ` Jim Porter
2023-12-01 8:29 ` Eli Zaretskii
2023-12-04 3:08 ` Richard Stallman
2023-12-04 3:08 ` Richard Stallman
2023-12-04 4:34 ` Jim Porter
2023-12-10 19:36 ` Jim Porter
2023-12-16 23:10 ` Stefan Kangas
2023-12-17 20:47 ` Jim Porter
2024-01-09 18:40 ` Jim Porter
2023-12-04 3:08 ` Richard Stallman
2023-11-04 8:27 ` Eli Zaretskii
2023-11-04 16:44 ` Jim Porter
2023-11-06 2:29 ` Richard Stallman
2023-11-06 2:29 ` Richard Stallman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=381836df-c16f-b3e7-d0c4-473290e165de@gmail.com \
--to=jporterbugs@gmail.com \
--cc=66756@debbugs.gnu.org \
--cc=eliz@gnu.org \
--cc=rms@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.