PATCH: Explicitly show how let works on global-variables

PATCH: Explicitly show how let works on global-variables

[Pedro Andres Aranda Gutierrez]

[-- Attachment #1.1: Type: text/plain, Size: 584 bytes --]

Hi

this is a small patch for the 'Introduction to Emacs LISP programming'
guide to show how let works on system-wide variables.
Understanding this would have made my life easier the past +20 years ;-)
and an example is sometimes worth 100 lines of explanation (more so if you
are in a hurry and you do diagonal reading)

Best, /PA

-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should run
a leader-deposed hook here, but we can't yet

[-- Attachment #1.2: Type: text/html, Size: 912 bytes --]

[-- Attachment #2: elisp-intro.diff --]
[-- Type: text/x-patch, Size: 1211 bytes --]

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index df8fa2f8e7..bf0ccaa301 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -3731,6 +3731,24 @@ Sample let Expression
 value of the variable @code{tiger} is printed at the location of the
 second @samp{%s}.
 
+@need 1500
+When you use a system-wide variable in @code{let}, its value is modified in its
+scope and then restored. As an example, the following snippet manipulates
+@code{system-time-locale} in the scope of the @code{let} only:
+
+@smallexample
+(setq system-time-locale "C") ;; this modifies system-time-locale system-wide
+(let ((system-time-locale "es_ES.UTF8")) ;; change it in the scope of let
+  (message "(inside let) Hoy es %s" (format-time-string "%d de %B de %Y")))
+(message "(outside) Today is %s" (format-time-string "%d %B %Y")) ;; Restore locale set before
+@end smallexample
+
+Will produce
+@smallexample
+(inside let) Hoy es 04 de octubre de 2022
+(outside) Today is 04 October 2022
+@end smallexample
+
 @node Uninitialized let Variables
 @subsection Uninitialized Variables in a @code{let} Statement
 @cindex Uninitialized @code{let} variables

Re: PATCH: Explicitly show how let works on global-variables

[Eli Zaretskii]

> From: Pedro Andres Aranda Gutierrez <paaguti@gmail.com>
> Date: Tue, 4 Oct 2022 08:46:02 +0200
> 
> this is a small patch for the 'Introduction to Emacs LISP programming' guide to show how let works on
> system-wide variables. 
> Understanding this would have made my life easier the past +20 years ;-) and an example is sometimes
> worth 100 lines of explanation (more so if you are in a hurry and you do diagonal reading)

This manual already says, in the previous subsection:

     Local variables created by a ‘let’ expression retain their value
  _only_ within the ‘let’ expression itself (and within expressions called
  within the ‘let’ expression); the local variables have no effect outside
  the ‘let’ expression.

Doesn't this cover the issue?

Re: PATCH: Explicitly show how let works on global-variables

[Pedro Andres Aranda Gutierrez]

[-- Attachment #1: Type: text/plain, Size: 1802 bytes --]

Hi Eli,

may be. But in my case it didn't. I was misled by the term 'local variable'
coming from (and using) other programming languages.

As I understood the text (and to continue with the system-time-locale) I
understood as local variable a 'value that was stored in the function's
stack' to be used in the scope of the let. That implied (once again in my
understanding) that the global system-time-locale would not be affected and
hence format-time-string would not see the change in the value within the
let.

An example like this would have helped me (and possibly shaped the way I
use elisp)...

Just my .02 cents, /PA

On Tue, 4 Oct 2022 at 09:52, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Pedro Andres Aranda Gutierrez <paaguti@gmail.com>
> > Date: Tue, 4 Oct 2022 08:46:02 +0200
> >
> > this is a small patch for the 'Introduction to Emacs LISP programming'
> guide to show how let works on
> > system-wide variables.
> > Understanding this would have made my life easier the past +20 years ;-)
> and an example is sometimes
> > worth 100 lines of explanation (more so if you are in a hurry and you do
> diagonal reading)
>
> This manual already says, in the previous subsection:
>
>      Local variables created by a ‘let’ expression retain their value
>   _only_ within the ‘let’ expression itself (and within expressions called
>   within the ‘let’ expression); the local variables have no effect outside
>   the ‘let’ expression.
>
> Doesn't this cover the issue?
>


-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should run
a leader-deposed hook here, but we can't yet

[-- Attachment #2: Type: text/html, Size: 2558 bytes --]

Re: PATCH: Explicitly show how let works on global-variables

[Phil Sainty]

On 2022-10-04 21:09, Pedro Andres Aranda Gutierrez wrote:
> I understood as local variable a 'value that was stored in the
> function's stack' to be used in the scope of the let. That implied
> (once again in my understanding) that the global system-time-locale
> would not be affected and hence format-time-string would not see the
> change in the value within the let.

Since the addition of lexical binding to Emacs Lisp in Emacs 24.1,
both results are possible depending on whether you are dealing with
a dynamic or a lexical variable.

I.e. given:

  (defun myfunc () foo)
  (let ((foo 'bar)) (myfunc))

If foo is a dynamic variable then the let form will return 'bar.

If foo is a lexical variable, then you'd get this error:
"let: Symbol’s value as variable is void: foo".

Eli quoted the manual:

      Local variables created by a ‘let’ expression retain their value
   _only_ within the ‘let’ expression itself (and within expressions 
called
   within the ‘let’ expression); the local variables have no effect 
outside
   the ‘let’ expression.

That "(and within expressions called within the ‘let’ expression)" is
pretty ambiguous wrt dynamic vs lexical binding, and a few lines later
it comments very briefly on this:

   in Emacs Lisp, the default scoping is dynamic, not lexical.
   (The non-default lexical binding is not discussed in this manual.)

Which keeps the rest of the text accurate, yet in an almost-entirely
unexplained manner.

I suggest that at this point it has become pretty necessary for lexical
binding to be discussed in this manual...

* The *scratch* buffer, in which users will perform many if not most of
   their experiments, now uses lexical binding by default.

* If enabled, auto-insert-mode adds lexical-binding: t to new elisp 
files
   by default.

* IIRC most elisp files in Emacs core are now using lexical binding.

* The emacs-lisp-mode mode-name treats dynamic binding as a warning.

So while it's as true as ever that dynamic binding is the default, the
fact that so many things nowadays default to *enabling* lexical binding
really blurs this line, to the point where I think it's unreasonable to
avoid discussing lexical binding in the introduction to emacs lisp, as
the user will almost unavoidably be exposed to it.

I think examples would be hugely helpful in explaining the difference
between the two types of binding.


-Phil

Re: PATCH: Explicitly show how let works on global-variables

[Stefan Monnier]

> * IIRC most elisp files in Emacs core are now using lexical binding.
         ^^^^
         all

... well, except for

    test/lisp/emacs-lisp/bytecomp-resources/no-byte-compile.el
    test/src/comp-resources/comp-test-funcs-dyn.el
    test/src/lread-resources/lazydoc.el

The first of which is empty (save for a "no-byte-compile" cookie),
the second of which is there specifically to test handling of the old
non-lexical-binding, and the last of which is actually not a `.el` file
but a `.elc` file (not sure why it has a `.el` extension).


        Stefan

Re: PATCH: Explicitly show how let works on global-variables

[Tim Cross]

Phil Sainty <psainty@orcon.net.nz> writes:

> On 2022-10-04 21:09, Pedro Andres Aranda Gutierrez wrote:
>> I understood as local variable a 'value that was stored in the
>> function's stack' to be used in the scope of the let. That implied
>> (once again in my understanding) that the global system-time-locale
>> would not be affected and hence format-time-string would not see the
>> change in the value within the let.
>
> Since the addition of lexical binding to Emacs Lisp in Emacs 24.1,
> both results are possible depending on whether you are dealing with
> a dynamic or a lexical variable.
>
> I.e. given:
>
>  (defun myfunc () foo)
>  (let ((foo 'bar)) (myfunc))
>
> If foo is a dynamic variable then the let form will return 'bar.
>
> If foo is a lexical variable, then you'd get this error:
> "let: Symbol’s value as variable is void: foo".
>
> Eli quoted the manual:
>
>      Local variables created by a ‘let’ expression retain their value
>   _only_ within the ‘let’ expression itself (and within expressions called
>   within the ‘let’ expression); the local variables have no effect outside
>   the ‘let’ expression.
>
> That "(and within expressions called within the ‘let’ expression)" is
> pretty ambiguous wrt dynamic vs lexical binding, and a few lines later
> it comments very briefly on this:
>
>   in Emacs Lisp, the default scoping is dynamic, not lexical.
>   (The non-default lexical binding is not discussed in this manual.)
>
> Which keeps the rest of the text accurate, yet in an almost-entirely
> unexplained manner.
>
> I suggest that at this point it has become pretty necessary for lexical
> binding to be discussed in this manual...
>
> * The *scratch* buffer, in which users will perform many if not most of
>   their experiments, now uses lexical binding by default.
>
> * If enabled, auto-insert-mode adds lexical-binding: t to new elisp files
>   by default.
>
> * IIRC most elisp files in Emacs core are now using lexical binding.
>
> * The emacs-lisp-mode mode-name treats dynamic binding as a warning.
>
> So while it's as true as ever that dynamic binding is the default, the
> fact that so many things nowadays default to *enabling* lexical binding
> really blurs this line, to the point where I think it's unreasonable to
> avoid discussing lexical binding in the introduction to emacs lisp, as
> the user will almost unavoidably be exposed to it.
>
> I think examples would be hugely helpful in explaining the difference
> between the two types of binding.
>

+1. I think this has become quite important.

Re: PATCH: Explicitly show how let works on global-variables

[Pedro Andres Aranda Gutierrez]

[-- Attachment #1: Type: text/plain, Size: 3461 bytes --]

Even more so in the light of lexical binding. I'm trying to introduce
people to Emacs and the easier to understand and use as a source of
inspiration this manual is, the more probable it is that people actually
switch to Emacs. (Or at least this is what I have seen after using it for 7
years as an option in the practical assignments)

/PA

On Wed, 5 Oct 2022 at 00:22, Tim Cross <theophilusx@gmail.com> wrote:

>
> Phil Sainty <psainty@orcon.net.nz> writes:
>
> > On 2022-10-04 21:09, Pedro Andres Aranda Gutierrez wrote:
> >> I understood as local variable a 'value that was stored in the
> >> function's stack' to be used in the scope of the let. That implied
> >> (once again in my understanding) that the global system-time-locale
> >> would not be affected and hence format-time-string would not see the
> >> change in the value within the let.
> >
> > Since the addition of lexical binding to Emacs Lisp in Emacs 24.1,
> > both results are possible depending on whether you are dealing with
> > a dynamic or a lexical variable.
> >
> > I.e. given:
> >
> >  (defun myfunc () foo)
> >  (let ((foo 'bar)) (myfunc))
> >
> > If foo is a dynamic variable then the let form will return 'bar.
> >
> > If foo is a lexical variable, then you'd get this error:
> > "let: Symbol’s value as variable is void: foo".
> >
> > Eli quoted the manual:
> >
> >      Local variables created by a ‘let’ expression retain their value
> >   _only_ within the ‘let’ expression itself (and within expressions
> called
> >   within the ‘let’ expression); the local variables have no effect
> outside
> >   the ‘let’ expression.
> >
> > That "(and within expressions called within the ‘let’ expression)" is
> > pretty ambiguous wrt dynamic vs lexical binding, and a few lines later
> > it comments very briefly on this:
> >
> >   in Emacs Lisp, the default scoping is dynamic, not lexical.
> >   (The non-default lexical binding is not discussed in this manual.)
> >
> > Which keeps the rest of the text accurate, yet in an almost-entirely
> > unexplained manner.
> >
> > I suggest that at this point it has become pretty necessary for lexical
> > binding to be discussed in this manual...
> >
> > * The *scratch* buffer, in which users will perform many if not most of
> >   their experiments, now uses lexical binding by default.
> >
> > * If enabled, auto-insert-mode adds lexical-binding: t to new elisp files
> >   by default.
> >
> > * IIRC most elisp files in Emacs core are now using lexical binding.
> >
> > * The emacs-lisp-mode mode-name treats dynamic binding as a warning.
> >
> > So while it's as true as ever that dynamic binding is the default, the
> > fact that so many things nowadays default to *enabling* lexical binding
> > really blurs this line, to the point where I think it's unreasonable to
> > avoid discussing lexical binding in the introduction to emacs lisp, as
> > the user will almost unavoidably be exposed to it.
> >
> > I think examples would be hugely helpful in explaining the difference
> > between the two types of binding.
> >
>
> +1. I think this has become quite important.
>


-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should run
a leader-deposed hook here, but we can't yet

[-- Attachment #2: Type: text/html, Size: 4407 bytes --]

Re: PATCH: Explicitly show how let works on global-variables

[Pedro Andres Aranda Gutierrez]

[-- Attachment #1: Type: text/plain, Size: 4010 bytes --]

So, can someone more informed than myself provide an informed patch

Thanks, /PA

On Wed, 5 Oct 2022 at 07:28, Pedro Andres Aranda Gutierrez <
paaguti@gmail.com> wrote:

> Even more so in the light of lexical binding. I'm trying to introduce
> people to Emacs and the easier to understand and use as a source of
> inspiration this manual is, the more probable it is that people actually
> switch to Emacs. (Or at least this is what I have seen after using it for 7
> years as an option in the practical assignments)
>
> /PA
>
> On Wed, 5 Oct 2022 at 00:22, Tim Cross <theophilusx@gmail.com> wrote:
>
>>
>> Phil Sainty <psainty@orcon.net.nz> writes:
>>
>> > On 2022-10-04 21:09, Pedro Andres Aranda Gutierrez wrote:
>> >> I understood as local variable a 'value that was stored in the
>> >> function's stack' to be used in the scope of the let. That implied
>> >> (once again in my understanding) that the global system-time-locale
>> >> would not be affected and hence format-time-string would not see the
>> >> change in the value within the let.
>> >
>> > Since the addition of lexical binding to Emacs Lisp in Emacs 24.1,
>> > both results are possible depending on whether you are dealing with
>> > a dynamic or a lexical variable.
>> >
>> > I.e. given:
>> >
>> >  (defun myfunc () foo)
>> >  (let ((foo 'bar)) (myfunc))
>> >
>> > If foo is a dynamic variable then the let form will return 'bar.
>> >
>> > If foo is a lexical variable, then you'd get this error:
>> > "let: Symbol’s value as variable is void: foo".
>> >
>> > Eli quoted the manual:
>> >
>> >      Local variables created by a ‘let’ expression retain their value
>> >   _only_ within the ‘let’ expression itself (and within expressions
>> called
>> >   within the ‘let’ expression); the local variables have no effect
>> outside
>> >   the ‘let’ expression.
>> >
>> > That "(and within expressions called within the ‘let’ expression)" is
>> > pretty ambiguous wrt dynamic vs lexical binding, and a few lines later
>> > it comments very briefly on this:
>> >
>> >   in Emacs Lisp, the default scoping is dynamic, not lexical.
>> >   (The non-default lexical binding is not discussed in this manual.)
>> >
>> > Which keeps the rest of the text accurate, yet in an almost-entirely
>> > unexplained manner.
>> >
>> > I suggest that at this point it has become pretty necessary for lexical
>> > binding to be discussed in this manual...
>> >
>> > * The *scratch* buffer, in which users will perform many if not most of
>> >   their experiments, now uses lexical binding by default.
>> >
>> > * If enabled, auto-insert-mode adds lexical-binding: t to new elisp
>> files
>> >   by default.
>> >
>> > * IIRC most elisp files in Emacs core are now using lexical binding.
>> >
>> > * The emacs-lisp-mode mode-name treats dynamic binding as a warning.
>> >
>> > So while it's as true as ever that dynamic binding is the default, the
>> > fact that so many things nowadays default to *enabling* lexical binding
>> > really blurs this line, to the point where I think it's unreasonable to
>> > avoid discussing lexical binding in the introduction to emacs lisp, as
>> > the user will almost unavoidably be exposed to it.
>> >
>> > I think examples would be hugely helpful in explaining the difference
>> > between the two types of binding.
>> >
>>
>> +1. I think this has become quite important.
>>
>
>
> --
> Fragen sind nicht da um beantwortet zu werden,
> Fragen sind da um gestellt zu werden
> Georg Kreisler
>
> Headaches with a Juju log:
> unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should run
> a leader-deposed hook here, but we can't yet
>
>

-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should run
a leader-deposed hook here, but we can't yet

[-- Attachment #2: Type: text/html, Size: 5325 bytes --]

Re: PATCH: Explicitly show how let works on global-variables

[Emanuel Berg]

Pedro Andres Aranda Gutierrez wrote:

> So, can someone more informed than myself provide an
> informed patch

We should have

- a `dlet' which is always dynamic/special;

- a `let' which is what we have today with `let' and
  ";;; -*- lexical-binding: t -*-", i.e. lexical/static unless
  the variable is already dynamic/special, in which case it
  would remain so only with the new value stacked; and

- a `slet' which is always lexical/static.

Then we would drop ";;; -*- lexical-binding: t -*-" from all
files, we would write three docstrings (`dlet', `let' and
`slet') and that would de it ...

-- 
underground experts united
https://dataswamp.org/~incal

Re: PATCH: Explicitly show how let works on global-variables

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > This manual already says, in the previous subsection:

  >      Local variables created by a ‘let’ expression retain their value
  >   _only_ within the ‘let’ expression itself (and within expressions called
  >   within the ‘let’ expression); the local variables have no effect outside
  >   the ‘let’ expression.

  > Doesn't this cover the issue?

In an introductory manual like this one, it is good
to repeat an important point, if that helps users understand
the subject.  It's worth another few lines to say this a second time,
and even a third time, to get the point across clearly.

An additional example would probably be good too.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: PATCH: Explicitly show how let works on global-variables

[tomas]

[-- Attachment #1: Type: text/plain, Size: 1267 bytes --]

On Tue, Oct 04, 2022 at 08:46:02AM +0200, Pedro Andres Aranda Gutierrez wrote:
> Hi
> 
> this is a small patch for the 'Introduction to Emacs LISP programming'
> guide to show how let works on system-wide variables.
> Understanding this would have made my life easier the past +20 years ;-)
> and an example is sometimes worth 100 lines of explanation (more so if you
> are in a hurry and you do diagonal reading)
> 
> Best, /PA

[...]

> +@need 1500
> +When you use a system-wide variable in @code{let}, its value is modified in its
> +scope and then restored. As an example, the following snippet manipulates
> +@code{system-time-locale} in the scope of the @code{let} only:
> +

I think this is technically wrong and potentially confusing.

I'd tend to say that a new binding is created which shadows the
global binding. The `system-time-locale' in your let-bound scope
is a different variable from the global one, although it has the
same name.

More importantly, nothing gets "restored": it's just the compiler
which sees a different variable depending on scope. This is even
"more true" (I know, I know) with lexical variables.

The example itself seems to me a good idea. Just the mental model
needs fixing :)

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: PATCH: Explicitly show how let works on global-variables

[Phil Sainty]

On 2022-10-04 20:59, tomas@tuxteam.de wrote:
> I think this is technically wrong and potentially confusing.
> 
> I'd tend to say that a new binding is created which shadows the
> global binding. The `system-time-locale' in your let-bound scope
> is a different variable from the global one, although it has the
> same name.
> 
> More importantly, nothing gets "restored": it's just the compiler
> which sees a different variable depending on scope. This is even
> "more true" (I know, I know) with lexical variables.

I think this is technically wrong and potentially confusing :)

(info "(elisp)Dynamic Binding") explains it pretty clearly:

    "Dynamic binding is implemented in Emacs Lisp in a simple way.  Each
symbol has a value cell, which specifies its current dynamic value (or
absence of value).  *Note Symbol Components::.  When a symbol is given a
dynamic local binding, Emacs records the contents of the value cell (or
absence thereof) in a stack, and stores the new local value in the value
cell.  When the binding construct finishes executing, Emacs pops the old
value off the stack, and puts it in the value cell."

Re: PATCH: Explicitly show how let works on global-variables

[Stefan Monnier]

Phil Sainty [2022-10-05 00:56:11] wrote:

> On 2022-10-04 20:59, tomas@tuxteam.de wrote:
>> I think this is technically wrong and potentially confusing.
>> I'd tend to say that a new binding is created which shadows the
>> global binding. The `system-time-locale' in your let-bound scope
>> is a different variable from the global one, although it has the
>> same name.
>> More importantly, nothing gets "restored": it's just the compiler
>> which sees a different variable depending on scope. This is even
>> "more true" (I know, I know) with lexical variables.
>
> I think this is technically wrong and potentially confusing :)
>
> (info "(elisp)Dynamic Binding") explains it pretty clearly:
>
>    "Dynamic binding is implemented in Emacs Lisp in a simple way.  Each
> symbol has a value cell, which specifies its current dynamic value (or
> absence of value).  *Note Symbol Components::.  When a symbol is given a
> dynamic local binding, Emacs records the contents of the value cell (or
> absence thereof) in a stack, and stores the new local value in the value
> cell.  When the binding construct finishes executing, Emacs pops the old
> value off the stack, and puts it in the value cell."

You're both right.

BTW.  You can see the difference when you consider threads: if thread A does
(let ((x 'my-val)) ... <wait> ...) at the time when A waits, A sees `x`
as having value `my-val`, but other threads won't see it.
[ And yes, currently this is implemented by doing the "set/reset" dance
on the variables when we switch from one thread to another :-(  ]


        Stefan

Re: PATCH: Explicitly show how let works on global-variables

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Lexical binding was a fundamental change in Emacs Lisp.
I expect that it calls for a deep revision of the Emacs Lisp Intro
to clearly present lexical and dynamic binding.

I wish Bob Chassell were here to do it.

Do we know anyone else who can do this job well?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

RE: [External] : PATCH: Explicitly show how let works on global-variables

[Drew Adams]

This isn't quite correct:

     When you use a system-wide variable in
     @code{let}, its value is modified in its
     scope and then restored.

1. I'm guessing that by "system-wide" (which is not
   defined) you mean a "special", i.e., "dynamic" var.

2. Dynamic binding has no notion of scope, actually.
   It's instead about duration: the binding has dynamic
   _extent_: it remains in effect until the `let' is
   finished.

See CLTL2, section "Scope and Extent": https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node43.html

("The term 'dynamic scope' is a misnomer. Nevertheless
it is both traditional and useful.")