\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#276: Specify and Unify Variable Linking Commands}
\date{October 01, 2006}
\author{Miguel Sofer}
\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 \#276}&\textbf{Specify and Unify Variable Linking Commands}\\\hline
Author&

Miguel Sofer \tipmail{msofer}{users.sourceforge.net}
\\
Created&Sunday, \(\text{1}^{\text{st}}\) October 2006\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.20 $\\
Keywords&Tcl, global, variable, upvar, namespace upvar\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The purpose of this TIP is to simplify and clarify the semantics of the commands in Tcl that couple variables in different scopes together.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

This TIP proposes to specify and document the behaviour of the different variable linking commands in Tcl: \textbf{global}, \textbf{variable}, \textbf{upvar} and \textbf{namespace upvar}.

In particular, as many of these commands were initially designed to be mainly useful from within procedure bodies, the documentation does not specify their behaviour with respect to qualified variable names.

This TIP proposes to specify and document this behaviour, insuring that it is essentially the same in all these commands.

\subsection{Current Situation}

There have been a few bug reports concerning the behaviour of variable linking commands with respect to qualified variable names: 604226, 1274916, 1274918. Some are real bugs, some are just surprising but correct behaviour, some are surprising unspecified behaviour.

Within proc bodies all of these commands create local variables that are linked to original variables elsewhere (the following assumes that \textit{local} is a non-qualified name):
\begin{itemize}
\item{}
``\textbf{global} \textit{var}'' creates a local variable ``[\textbf{namespace tail} \textit{var}]'' that is linked to ``\textit{var}'' as resolved from the global namespace.
\item{}
``\textbf{variable} \textit{var}'' creates a local variable ``[\textbf{namespace tail} \textit{var}]'' that is linked to ``\textit{var}'' as resolved from [\textbf{namespace current}].
\item{}
``\textbf{upvar} \textit{level var local}'' creates a local variable ``\textit{local}'' that is linked to ``\textit{var}'' as resolved in the context of the frame identified by \textit{level}. It is an error to try to link to a proc-local variable from a namespace context. It is an error to link a variable to itself.
\item{}
``\textbf{namespace upvar} \textit{ns var local}'' creates a local variable ``\textit{local}'' that is linked to ``\textit{var}'' as resolved from namespace \textit{ns} (itself resolved in the current context). It is an error to link a variable to itself.
\end{itemize}

One undocumented issue is what should happen when \textit{local} is a qualified name.

Another issue is the behaviour of these commands when invoked outside of procedure bodies:
\begin{itemize}
\item{}
``\textbf{global} \textit{var}'' is documented to be a no-op.
\item{}
``\textbf{variable} \textit{var}'' is documented to create a namespace variable in the current namespace, without any mention of the behaviour when ``\textit{var}'' is qualified. Currently that is a a no-op in terms of creating a variable, but it can change the value of the target, see [Bug \#604226]. If \textbf{var} is a simple name and the corresponding variable already existed, \textbf{variable} may set its value (and an internal flag), but does no linking.
\item{}
``\textbf{upvar} \textit{level var local}'' creates a variable ``\textit{local}'' (as resolved from [\textbf{namespace current}]) that is linked to ``\textit{var}'' as resolved in the context of the frame identified by \textit{level}. It is an error to try to link to a proc-local variable from a namespace context. It is an error to link a variable to itself.
\item{}
``\textbf{namespace upvar} \textit{ns var local} creates a variable ''\textit{local}`` (as resolved from [\textbf{namespace current}]) that is linked to ''\textit{var}" as resolved from namespace \textit{ns} (itself resolved in the current context). It is an error to link a variable to itself.
\end{itemize}

\section{Proposal}

This TIP proposes to unify the criteria, making all of these commands essentially implementable in Tcl from the most general, \textbf{upvar}. The behaviour should \textit{not} depend on the commands being invoked within or outside of a procedure body.

In all of the following, it is an error for \textit{local} to be a qualified variable name.
\begin{itemize}
\item{}
``\textbf{global} \textit{var}'' always creates a variable ``[\textbf{namespace tail} \textit{var}]'' in the current context, linked to a global variable ``\textit{var}''.
\item{}
``\textbf{variable} \textit{var}'' always creates a variable ``[\textbf{namespace tail} \textit{var}]'' in the current context, linked to a variable ``\textit{var}'' as resolved from [\textbf{namespace current}].
\item{}
``\textbf{upvar} \textit{level var local}'' always creates a variable ``\textit{local}'' in the current context, linked to ``\textit{var}'' as resolved in the context of the frame identified by \textit{level}. It is an error to try to link to a proc-local variable from a namespace context.
\item{}
``\textbf{namespace upvar} \textit{ns var local}'' always creates a variable ``\textit{local}'' in the current context, linked to ``\textit{var}'' as resolved from namespace \textit{ns} (itself resolved in the current context).
\end{itemize}

In all cases, attempting to link a variable to itself will be a no-op.

\section{Compatibility}

This TIP may cause breakage in some scripts relying on undocumented behaviour.

The specification changes for \textbf{global} and \textbf{variable} outside of proc bodies is almost certainly implementing what the programmer meant them to do, hence likely to fix more bugs than it causes. 

\section{Reference Implementation and Documentation}

Forthcoming at SF.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
