From 4cecd67c394959a374eacea6018f5ab633b31ae8 Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Fri, 16 Oct 2020 15:24:15 -0400 Subject: [PATCH] * doc/lispref/variables.texi (Converting to Lexical Binding): New section Extract it from `Using Lexical Binding` and extend it a bit. --- doc/lispref/variables.texi | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 94c8c88796f..acbc8df6eae 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -934,6 +934,7 @@ Lisp programs. * Dynamic Binding Tips:: Avoiding problems with dynamic binding. * Lexical Binding:: A different type of local variable binding. * Using Lexical Binding:: How to enable lexical binding. +* Converting to Lexical Binding:: Convert existing code to lexical binding. @end menu @node Dynamic Binding @@ -1242,9 +1243,10 @@ for those that are only special in the current lexical scope. @end defun The use of a special variable as a formal argument in a function is -discouraged. Doing so gives rise to unspecified behavior when lexical -binding mode is enabled (it may use lexical binding sometimes, and -dynamic binding other times). +not supported. + +@node Converting to Lexical Binding +@subsection Converting to Lexical Binding Converting an Emacs Lisp program to lexical binding is easy. First, add a file-local variable setting of @code{lexical-binding} to @@ -1264,9 +1266,21 @@ variable. If a non-special variable is bound but not used within a variable. The byte-compiler will also issue a warning if you use a special variable as a function argument. - (To silence byte-compiler warnings about unused variables, just use -a variable name that starts with an underscore. The byte-compiler -interprets this as an indication that this is a variable known not to + A warning about a reference or an assignment to a free variable is +usually a clear sign that that variable should be marked as +dynamically scoped, so you need to add an appropriate @code{defvar} +before the first use of that variable. + + A warning about an unused variable may be a good hint that the +variable was intended to be dynamically scoped (because it is actually +used, but in another function), but it may also be an indication that +the variable is simply really not used and could simply be removed. +So you need to find out which case it is, and based on that, either +add a @code{defvar} or remove the variable altogether. If removal is +not possible or not desirable (typically because it is a formal +argument and that we cannot or don't want to change all the callers), +you can also add a leading underscore to the variable's name to +indicate to the compiler that this is a variable known not to be used.) @node Buffer-Local Variables -- 2.39.2