bug#11407: 24.0.96; Doc for lexical binding in Elisp manual

bug#11407: 24.0.96; Doc for lexical binding in Elisp manual

[Drew Adams]

With the arrival of lexical scoping in Emacs 24, it is even more
important, not less, that the Elisp manual document `lexical-let(*)'.
 
The `lexical-let(*)' doc string too could also be beefed up.  It says
only this:
 
 "Like `let', but lexically scoped.
  The main visible difference is that lambdas inside BODY will create
  lexical closures as in Common Lisp."
 
It should include something that lets users know whether such closures
close only the vars that are explicitly declared in the `lexical-let(*)'
or also the vars that are lexically available.  IOW, it should say just
what variables are encapsulated in the closures referred to.
 
E.g.:
 
(defun foo (arg)
  (lexical-let ((beta  (something)))
    #'(lambda () (alpha arg beta))))
 
Does the closure here treat ARG as lexically bound by the `defun', or is
ARG a dynamically bound free var in the lambda?  I believe the answer it
that the value of ARG encapsulated in the closure is the value that is
passed as argument to foo.  Whatever the correct answer is, it should be
made clear to users.
 
It would be fine to document this stuff together with the other info
about lexical bindings, in node (elisp) `Lexical Binding'.  But it
should be documented somewhere (whatever the exact behavior is).
 
 
 
In GNU Emacs 24.0.96.1 (i386-mingw-nt5.1.2600)
 of 2012-04-28 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'
 

bug#11407: 24.0.96; Doc for lexical binding in Elisp manual

[Stefan Monnier]

tags 11407 wontfix
thanks

> With the arrival of lexical scoping in Emacs 24, it is even more
> important, not less, that the Elisp manual document `lexical-let(*)'.

Why?  I intend to mark lexical-let as obsolete in 24.2.

> (defun foo (arg)
>   (lexical-let ((beta  (something)))
>     #'(lambda () (alpha arg beta))))
 
> Does the closure here treat ARG as lexically bound by the `defun', or is
> ARG a dynamically bound free var in the lambda?  I believe the answer it

The behavior is largely the result of some accidental design decisions
taken years ago in the implementation of lexical-let, and I have no
intention to document the result.


        Stefan

bug#11407: 24.0.96; Doc for lexical binding in Elisp manual

[Drew Adams]

> tags 11407 wontfix
> thanks
> 
> > With the arrival of lexical scoping in Emacs 24, it is even more
> > important, not less, that the Elisp manual document
> > `lexical-let(*)'.
> 
> Why?  I intend to mark lexical-let as obsolete in 24.2.

Why consider it obsolete?

It gives users a choice:

a. Make a file use lexical binding by default (e.g., using a file-level
declaration, as now), and use defvars to override that to get dynamic binding
for certain vars.

b. Let a file use dynamic binding by default, and use `lexical-let' to override
that and get lexical binding for certain vars.

There is *lots* of code that expects its file to use dynamic binding in general.
And some of that code might need lexical binding here or there.  Especially
files containing code that tries to be compatible across multiple Emacs
versions.

> > (defun foo (arg)
> >   (lexical-let ((beta  (something)))
> >     #'(lambda () (alpha arg beta))))
>  
> > Does the closure here treat ARG as lexically bound by the 
> > `defun', or is ARG a dynamically bound free var in the lambda?
> > I believe the answer is that the value of ARG encapsulated
> > in the closure is the value that is passed as argument to foo.
> 
> The behavior is largely the result of some accidental design decisions
> taken years ago in the implementation of lexical-let, and I have no
> intention to document the result.

Surely, if `lexical-let' is to be used by users (see above), they deserve a
description of its behavior in this regard.  The behavior is, as I think you're
agreeing, not obvious.

bug#11407: 24.0.96; Doc for lexical binding in Elisp manual

[Drew Adams]

> > > (defun foo (arg)
> > >   (lexical-let ((beta  (something)))
> > >     #'(lambda () (alpha arg beta))))
> >  
> > > Does the closure here treat ARG as lexically bound by the 
> > > `defun', or is ARG a dynamically bound free var in the lambda?
> > > I believe the answer is that the value of ARG encapsulated
> > > in the closure is the value that is passed as argument to foo.
> > 
> > The behavior is largely the result of some accidental 
> > design decisions taken years ago in the implementation of
> > lexical-let, and I have no intention to document the result.
> 
> Surely, if `lexical-let' is to be used by users (see above), 
> they deserve a description of its behavior in this regard.
> The behavior is, as I think you're agreeing, not obvious.

Not to mention the additional reason that people converting code that uses
`lexical-let' to use file-wide lexical behavior instead might in some cases need
to be aware of this idiosyncratic behavior, to convert properly.