\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#278: Fix Variable Name Resolution Quirks}
\date{October 03, 2006}
\author{Miguel Sofer, Miguel Sofer, Kevin Kenny, Jan Nijtmans}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#278}&\textbf{Fix Variable Name Resolution Quirks}\\\hline
Author&

Miguel Sofer \tipmail{msofer}{users.sourceforge.net}
\par
Miguel Sofer \tipmail{msofer}{users.sf.net}
\par
Kevin Kenny \tipmail{kennykb}{acm.org}
\par
Jan Nijtmans \tipmail{jan.nijtmans}{gmail.com}
\\
Created&Tuesday, \(\text{3}^{\text{rd}}\) October 2006\\
Type&Project\\
Tcl Version&\(9.0\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.18 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to fix the behaviour for variable name resolution, modelling it on the resolution for namespace names instead of the current command name resolution.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Definitions}
\begin{itemize}
\item{}
a variable name is ``simple'' if it does not contain the character sequence ``::''.
\item{}
a variable name is ``absolute'' if it starts with the character sequence ``::''.
\item{}
a variable name is ``relative'' if it is neither simple nor absolute, it contains the character sequence ``::'', but not at its beginning.
\end{itemize}

\section{Specification}

Variable name resolution shall proceed as follows:
\begin{itemize}
\item{}
a simple name refers to a local variable if within a proc body, to a variable resolved [*] in the current namespace otherwise 
\item{}
an absolute name does not need resolving, ::foo::bar::baz always refers to a variable named ``baz'' in a namespace named ``bar'' that is a child of a namespace named ``foo'' that is a child of the global namespace of the interpreter [*].
\item{}
a relative name is always resolved [*] starting at the current namespace. In the absence of special resolvers, foo::bar::baz refers to a variable named ``baz'' in a namespace named ``bar'' that is a child of a namespace named ``foo'' that is a child of the current namespace of the interpreter.
\end{itemize}

The changes with respect to the current behaviour is for relative names in all contexts, and simple names outside of proc bodies: the alternative lookup starting from the global namespace is lost.

The resolution is independent of the previous existence of namespaces or variables. The 'declaration' of namespace variables with the \textbf{variable} command, currently needed to avoid some confusing behaviour, becomes unnecessary. In short:

\begin{quote}
\textbf{It is possible to know what variable is meant by just looking at its name and knowing the context, without any interference from the rest of the program.}
\end{quote}

These are the same rules as presently used for the resolution of namespace names.

[*] Currently there are hooks in the core for special resolvers that can be attached to a namespace or interpreter, mainly (only?) used by itcl. The present TIP does not address resolvers, except for the specification that an absolute name ignores them. The rule that a simple name in a proc-body always refers to a local variable is not new in that sense, as any resolver hooks in that case create local variables linked to some other vars, in the manner of upvar. 

\section{Rationale: avoid confusion}

Repeating myself: the rationale is to make it a reality that

\begin{quote}
\textbf{It is possible to know what variable is meant by just looking at its name and knowing the context, without any interference from the rest of the program.}
\end{quote}

Ever since the birth of namespaces, the resolution path for variables has been modelled on the resolution path for commands: if a variable is not found in the current namespace, it will be looked up in the global namespace.

This behaviour hides a few surprises, especially but not only with respect to creative writing. Consider for instance the test
\begingroup\small\begin{verbatim}
 test namespace-17.7 {Tcl_FindNamespaceVar, relative name found} {
     namespace eval test_ns_1 {
         unset x
         set x  ;# must be global x now
     }
 } {314159}
\end{verbatim}
\endgroup

as well as following examples:
\begingroup\small\begin{verbatim}
   % set x 1
   1
   % namespace eval a set x
   1
   % set a::x
   can't read "a::x": no such variable

   % namespace eval b {upvar #0 x y}
   % info vars x
   % namespace eval a set x 1
   1
   % set x
   1

   % namespace eval a set x
   can't read "x": no such variable
   % set x 1
   1
   % namespace eval a set x
   1
   % upvar 0 ::a::x y
   % namespace eval a set x
   can't read "x": no such variable

   % namespace eval a set x
   can't read "x": no such variable
   % set x 1
   1
   % namespace eval a set x
   1
   % trace add variable a::x read {;#}
   % namespace eval a set x
   can't read "x": no such variable

   % set x 1
   1
   % namespace eval a {set x 2; set y 3}
   3
   % set x
   2
   % info vars a::*
   ::a::y
   % set a::x
   can't read "a::x": no such variable
   % set a::y
   3
\end{verbatim}
\endgroup

In order to restore some sanity, \textbf{variable} has been invented to selectively force the behaviour that this TIP is proposing (in its usage outside of procedure bodies).

The present behaviour forces a subtle and confusing concept of ``variable existence'', forcing some implementation details to be visible to scripts. Internally, a variable may
\begin{itemize}
\item{}
not exist at all
\item{}
exist in the namespace's hash table, but be undefined
\item{}
exist and have a value
\end{itemize}

In principle scripts should not be able to distinguish the first two states --- except as to the existence of traces on undefined variables. In particular, the existence of a link to an undefined variable (which forces the target to exist in state 2) should have no influence whatsoever on the concept of variable existence. But it does (see examples in \#959052).

This behaviour also causes [namespace which -variable] and [info vars] to give different answers as to the existence of variables: the first looks in the hashtable, the second verifies that the variable has a value or that it has been declared via [variable].

Some of the problems inherent in the current way of things are illustrated by Bugs 959052, 1251123, 1274916, 1274918, 1280497

Bug 1185933 is perhaps particularly illustrative. In it, Kevin Kenny \tipmail{kennykb}{acm.org}, a long-time Tcl maintainer (and reputed expert) had placed in 'clock.tcl' the group of lines:
\begingroup\small\begin{verbatim}
    set i 0
    foreach j $DaysInRomanMonthInLeapYear {
        lappend DaysInPriorMonthsInLeapYear [incr i $j]
    }
    unset i j
\end{verbatim}
\endgroup

within a [namespace eval] context. This code performed without ill effect for some months, until it was observed that it would cause a failure if a script were to create a variable named 'i' or 'j' in the global context prior to the first invocation of the [clock] command. This case was also inordinately difficult to simulate in the test suite, because tcltest reads the clock as part of its initialization. The fix was to move the offending code from the [namespace eval] into an 'init' procedure (which was called once and then deleted via [rename]). 

\section{Side Benefit: Code Simplification, Performance}

Variable name resolution has a relatively complicated implementation, and interplays strangely with many core commands --- in particular \textbf{variable} and \textbf{upvar}. This TIP would enable a non-negligible simplification of a lot of code.

An optimisation in variable name caching that permits massive speed improvements in namespace variable accesses could also be enabled --- it is currently \#ifdef'ed out, it was active briefly in Tcl8.5a2. Note that currently it is wrong to cache the pointer to an undefined variable: as the variable has to be kept in the corresponding hashtable, the variable jumps from the first to the second state of inexistence. This may cause breakage in scripts depending on full non-existence. See also Bug 959052.

Quite a few flag values that are currently needed to specify special code behaviour under different circumstances (VAR\_NAMESPACE\_VAR, LOOKUP\_FOR\_UPVAR, possibly others) become obsolete: the behaviour is the same under all circumstances.

\section{Down-Sides}

This is known to expose some ``bugs'' in code in the wild, and break at least one program (AlphaTk, see below).

\subsection{AlphaTk breakage}

AlphaTk breaks with this change [\url{http://aspn.activestate.com/ASPN/Mail/Message/Tcl-core/2083396}] [\url{http://sf.net/tracker/?func=detail&aid=959786&group_id=10894&atid=110894}].

This is the result of code of the form
\begingroup\small\begin{verbatim}
   namespace eval foo {}
   proc foo::bar {} {
       global foo::name
       set foo::name 1
   }
\end{verbatim}
\endgroup

which works since Tcl7.x until now, and would cease to work properly if this change is implemented. It is interesting to understand how this code works:
\begin{itemize}
\item{}
\textbf{Tcl7.x} I assume that there is conditional compat code that makes \textbf{namespace} a noop. The code creates a global variable foo::name, the proc accesses it as required by \textbf{global}.
\item{}
\textbf{Tcl8.x} the code links the local variable ``name'' to the global ``::foo::name''; after this, ``name'' goes unused. The access to the variable is by the name ``foo::name'': first ``::foo::foo::name'' is attempted, and, as it does not exist, ``::foo::name''. As this variable exists, in the sense that it is in the global hashtable by virtue of the created link, it is used.
\end{itemize}

Note that the code works in Tcl8.x through a quirk, and that it foregoes the usage of fast local variable access to ``name''. Should this TIP be accepted, I commit to helping out with the adaptation of AlphaTk.

Note also that, should both this TIP and \cite{tip277} be accepted, the code will continue to work as is through a different quirk. In that case, the namespace ``::foo::foo'' would be created, and the variable ``::foo::foo::name'' would be getting all the action. The code is however fragile, this aspect is not to be understood as minimising the impact of this TIP.

\section{Reference Implementation and Documentation}

A cvs branch tip-278-branch has been opened to test the implementation of this tip; the modifications are logged in the Changelog of the branch.

\section{Notes}
\begin{itemize}
\item{}
\textbf{namespace which -variable var} becomes relatively useless, as it will always return either \{\} or [namespace current]::var whenever var is not fully qualified.
\item{}
the only effect of \textbf{variable} outside of proc bodies is now on \textbf{namespace which -variable var}. This might change again if TIP276 is approved
\end{itemize}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#277]{tip277}
Miguel Sofer,
\emph{Create Namespaces as Needed},
on-line at \url{http://purl.org/tcl/tip/277.html}
\end{thebibliography}
\end{document}
